REST API documentation

Use our API to automatically initiate device transfers and monitor their progress until completion. Available in Enterprise & Custom plans only.

Why an API integration?

Do you want to automate the process of recovering devices from your employees? Do you not use any of the HR systems ReReady is integrated with? Do you have in-house technical capability? Then you can build your own API integration, and enjoy automated device deployments and returns.

What can be done through the API?

You can use the API to:

Who has access to the API?

Only Enterprise customers have access to the API. To learn more, see What is an Enterprise account?

Overview

The ReReady API is a RESTful JSON API. That means it is designed to:

Enable API access

Only Enterprise users can use the API. To enable your organization's Enterprise plan:

  1. Log in to your ReReady account (or open a free account).
  2. Click the "Settings" button at the top.
  3. If you haven't already, click "Enable Enterprise plan".

Authentication

Every API request must include an Authorization header containing your API key secret as a Token:

Authorization: Token YOUR-API-KEY-SECRET-HERE

To manage your API keys:

  1. Log in to your ReReady account (or open a free account).
  2. Click the "Settings" button at the top.
  3. Click the "Manage API keys" button.

Create a device transfer

Create a new device transfer (deployment or return). ReReady will send a sturdy box containing a prepaid shipping label so the device can be deployed/returned.

Method POST
URL https://sandbox.reready.co/api/v1/device_transfers
JSON parameters

box_shipment_carrier_code_required (optional): Defaults to nothing. See pricing. Options are a subset of: DHLExpress, FedEx, Sendle, and UPS
(see carrier requirements documentation for subsets)

box_shipment_rush (optional): A boolean. Defaults to false. See pricing. Options are: false, true

box_shipment_waived (optional): A boolean. Defaults to false. See discount. Options are: false, true

company_address: See organization_address.

device_condition (required for international device shipments): A string. Options are:

  • new
  • used

device_fair_market_value (required for international device shipments): A decimal or string. If given, min of $10.00.

device_make (required for international device shipments): A string. If given, min of 2 characters.

device_model (required for international device shipments): A string. If given, min of 5 characters.

device_serial_number (required for international device shipments): A string. If given, min of 5 characters.

device_shipment_carrier_code_required (optional): A string. Defaults to nothing. See pricing. Options are a subset of: DHLExpress, FedEx, Sendle, and UPS
(see carrier requirements documentation for subsets)

device_shipment_insured_amount (optional): An integer. Defaults to 0. See pricing. Options are: 0, 1000, 2000, 3000, 4000, and 5000

device_shipment_pickup_scheduling_enabled (optional; previously device_shipment_pickup_scheduling): A boolean. Defaults to false. See pricing. Options are: false, true

device_shipment_rush (optional): A boolean. Defaults to false. See pricing. Options are: false, true

device_type (optional): A string. Defaults to laptop. Options are:

  • desktop_small
  • desktop_large
  • imac_small
  • imac_large
  • laptop
  • laptop_five
  • monitor
  • tablet

device_year (required for international device shipments): An integer. If given, min of 2000.

employee_address: A JSON object with these parameters:

  • person_name
  • line_1
  • line_2 (optional)
  • city
  • state_code (AU, CA, IE, MX, and US only): 2 characters
  • postal_code
  • country_code: 2 characters
  • phone_number: Prefix and digits like "+15125556666". Prefix "+1" (US/Canada) assumed if no prefix given.
  • notification_emails (recommended): An array of email addresses. Max of 3.
  • notification_sms_phone_numbers (recommended): An array of SMS-capable phone numbers. Max of 3.

organization_address (previously company_address): A JSON object with these parameters:

  • organization_name
  • attention_name (optional)
  • line_1
  • line_2 (optional)
  • city
  • state_code (AU, CA, IE, MX, and US only): 2 characters
  • postal_code
  • country_code: 2 characters
  • phone_number: Prefix and digits like "+15125556666". Prefix "+1" (US/Canada) assumed if no prefix given.
  • notification_emails (optional): An array of email addresses. Max of 3. Defaults to your account email.

organization_id (optional): A UUID. The ID of the organization to create the device transfer for. Only useful if you are creating a device transfer on behalf of one of your sub-accounts. Defaults to your organization ID.

skip_manual_confirm (optional): A boolean. Defaults to false. If set to true, payment will be processed immediately. The user's default payment method will be used, or if that is not set the organization's most recently-added payment method. Options are: false, true

ticket_reference (optional): A string. The reference for the service desk ticket associated with this order.

type (optional): A string. Defaults to return. Options are:

  • deployment (box to organization, device to employee)
  • return (box to employee, device to organization)
Example JSON request 
{
  "organization_address": {
    "organization_name": "Maas Biolabs",
    "attention_name": "Human Resources",
    "line_1": "555 Nondescript Road",
    "city": "Maricopa",
    "state_code": "AZ",
    "postal_code": "85139",
    "country_code": "US"
  },
  "device_type": "laptop",
  "employee_address": {
    "person_name": "Christopher Mitchell",
    "line_1": "404 Hidden Spring Lane",
    "city": "Pittsburgh",
    "state_code": "PA",
    "postal_code": "15238",
    "country_code": "US"
  }
}
Example JSON response 
{
  "box_shipment": null,
  "box_shipment_carrier_code_required": null,
  "box_shipment_rush": false,
  "box_shipment_waived": false,
  "organization_address": {
    "organization_name": null,
    "attention_name": "Human Resources",
    "line_1": "555 Nondescript Road",
    "line_2": null,
    "city": "Maricopa",
    "state_code": "AZ",
    "postal_code": "85139",
    "country_code": "US",
    "notification_emails": []
  },
  "created_at": "2026-07-29T13:23:24.548Z",
  "device_condition": null,
  "device_make": null,
  "device_model": null,
  "device_serial_number": null,
  "device_shipment": null,
  "device_shipment_carrier_code_required": null,
  "device_shipment_insured_amount": 0,
  "device_shipment_pickup_scheduling_enabled": null,
  "device_shipment_rush": false,
  "device_type": "laptop",
  "employee_address": {
    "person_name": "Christopher Mitchell",
    "line_1": "404 Hidden Spring Lane",
    "line_2": null,
    "city": "Pittsburgh",
    "state_code": "PA",
    "postal_code": "15238",
    "country_code": "US",
    "notification_emails": [],
    "notification_sms_phone_numbers": []
  },
  "id": "980e4fa0-9a2f-440a-a707-2a02adfdae14",
  "notes": [],
  "number": 98420,
  "object": "DeviceTransfer",
  "payments": [],
  "plan_code": "basic",
  "state": "not_started",
  "ticket_reference": null,
  "type": "return",
  "user_email": "hr@example.com"
}

View a device transfer

View an existing device transfer. This is how to check the status of a device transfer.

Want automatic notifications whenever a device transfer is updated? You can enable webhooks and we'll send you a JSON payload including the device transfer state.
Method GET
URL https://sandbox.reready.co/api/v1/device_transfers/DEVICE-RETURN-UUID-HERE
JSON parameters

None

Example JSON request 
{}
Example JSON response 
{
  "box_shipment": {
    "carrier_code": "USPS",
    "delivered_at": null,
    "shipped_at": "2026-07-29T13:23:24.596Z",
    "state": "pre_transit",
    "tracking_id": "11111111111111111111",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=11111111111111111111",
    "updated_at": "2026-07-29T13:23:24.596Z"
  },
  "box_shipment_carrier_code_required": null,
  "box_shipment_rush": false,
  "box_shipment_waived": false,
  "organization_address": {
    "organization_name": null,
    "attention_name": "Human Resources",
    "line_1": "555 Nondescript Road",
    "line_2": null,
    "city": "Maricopa",
    "state_code": "AZ",
    "postal_code": "85139",
    "country_code": "US",
    "notification_emails": []
  },
  "created_at": "2026-07-29T13:23:24.596Z",
  "device_condition": null,
  "device_make": null,
  "device_model": null,
  "device_serial_number": null,
  "device_shipment": {
    "carrier_code": "FedEx",
    "delivered_at": null,
    "shipped_at": null,
    "state": "pre_transit",
    "tracking_id": "222222222222",
    "tracking_url": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=222222222222&cntry_code=us",
    "updated_at": "2026-07-29T13:23:24.596Z"
  },
  "device_shipment_carrier_code_required": null,
  "device_shipment_insured_amount": 0,
  "device_shipment_pickup_scheduling_enabled": null,
  "device_shipment_rush": false,
  "device_type": "laptop",
  "employee_address": {
    "person_name": "Christopher Mitchell",
    "line_1": "404 Hidden Spring Lane",
    "line_2": null,
    "city": "Pittsburgh",
    "state_code": "PA",
    "postal_code": "15238",
    "country_code": "US",
    "notification_emails": [],
    "notification_sms_phone_numbers": []
  },
  "id": "0a46b12c-9e5d-4ee0-8ce8-f9ddec410cef",
  "notes": [
    {
      "body": "Employee may be delayed by weather.",
      "created_at": "2026-07-29T13:23:24.596Z",
      "user_email": "hr@example.com"
    }
  ],
  "number": 83450,
  "object": "DeviceTransfer",
  "payments": [
    {
      "amount_cents": 8500,
      "created_at": "2026-07-29T13:23:24.603Z",
      "refunded_amount_cents": 0,
      "state": "succeeded"
    }
  ],
  "plan_code": "basic",
  "state": "pending_box_shipment",
  "ticket_reference": null,
  "type": "return",
  "user_email": "hr@example.com"
}

Cancel a device transfer

Cancel an existing device transfer that is pending payment or verification.

Method POST
URL https://sandbox.reready.co/api/v1/device_transfers/DEVICE-RETURN-UUID-HERE/cancels
JSON parameters

None

Example JSON request 
{}
Example JSON response 
{
  "box_shipment": {
    "carrier_code": "USPS",
    "delivered_at": null,
    "shipped_at": "2026-07-29T13:23:24.611Z",
    "state": "pre_transit",
    "tracking_id": "11111111111111111111",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=11111111111111111111",
    "updated_at": "2026-07-29T13:23:24.611Z"
  },
  "box_shipment_carrier_code_required": null,
  "box_shipment_rush": false,
  "box_shipment_waived": false,
  "organization_address": {
    "organization_name": null,
    "attention_name": "Human Resources",
    "line_1": "555 Nondescript Road",
    "line_2": null,
    "city": "Maricopa",
    "state_code": "AZ",
    "postal_code": "85139",
    "country_code": "US",
    "notification_emails": []
  },
  "created_at": "2026-07-29T13:23:24.610Z",
  "device_condition": null,
  "device_make": null,
  "device_model": null,
  "device_serial_number": null,
  "device_shipment": {
    "carrier_code": "FedEx",
    "delivered_at": null,
    "shipped_at": null,
    "state": "pre_transit",
    "tracking_id": "222222222222",
    "tracking_url": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=222222222222&cntry_code=us",
    "updated_at": "2026-07-29T13:23:24.611Z"
  },
  "device_shipment_carrier_code_required": null,
  "device_shipment_insured_amount": 0,
  "device_shipment_pickup_scheduling_enabled": null,
  "device_shipment_rush": false,
  "device_type": "laptop",
  "employee_address": {
    "person_name": "Christopher Mitchell",
    "line_1": "404 Hidden Spring Lane",
    "line_2": null,
    "city": "Pittsburgh",
    "state_code": "PA",
    "postal_code": "15238",
    "country_code": "US",
    "notification_emails": [],
    "notification_sms_phone_numbers": []
  },
  "id": "113832eb-e4aa-4f89-8d53-d1fbf24de05e",
  "notes": [
    {
      "body": "Employee may be delayed by weather.",
      "created_at": "2026-07-29T13:23:24.611Z",
      "user_email": "hr@example.com"
    }
  ],
  "number": 69286,
  "object": "DeviceTransfer",
  "payments": [
    {
      "amount_cents": 8500,
      "created_at": "2026-07-29T13:23:24.615Z",
      "refunded_amount_cents": 0,
      "state": "succeeded"
    }
  ],
  "plan_code": "basic",
  "state": "canceled",
  "ticket_reference": null,
  "type": "return",
  "user_email": "hr@example.com"
}

List all device transfers

List all existing device transfers. This is useful for generating your own reports. (You can also "Request Report" on your orders dashboard, or "Request Report" on your payments dashboard.)

Method GET
URL https://sandbox.reready.co/api/v1/device_transfers
JSON parameters (optional) 

{
  "page": 1
}

Defaults to 50 records per page. If you receive a response with 50 records, and want to check for more, increment your page and make another request.

Example JSON request 
{}
Example JSON response 
[
  {
    "box_shipment": {
      "carrier_code": "USPS",
      "delivered_at": null,
      "shipped_at": "2026-07-29T13:23:24.622Z",
      "state": "pre_transit",
      "tracking_id": "11111111111111111111",
      "tracking_url": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=11111111111111111111",
      "updated_at": "2026-07-29T13:23:24.622Z"
    },
    "box_shipment_carrier_code_required": null,
    "box_shipment_rush": false,
    "box_shipment_waived": false,
    "organization_address": {
      "organization_name": null,
      "attention_name": "Human Resources",
      "line_1": "555 Nondescript Road",
      "line_2": null,
      "city": "Maricopa",
      "state_code": "AZ",
      "postal_code": "85139",
      "country_code": "US",
      "notification_emails": []
    },
    "created_at": "2026-07-29T13:23:24.620Z",
    "device_condition": null,
    "device_make": null,
    "device_model": null,
    "device_serial_number": null,
    "device_shipment": {
      "carrier_code": "FedEx",
      "delivered_at": null,
      "shipped_at": null,
      "state": "pre_transit",
      "tracking_id": "222222222222",
      "tracking_url": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=222222222222&cntry_code=us",
      "updated_at": "2026-07-29T13:23:24.622Z"
    },
    "device_shipment_carrier_code_required": null,
    "device_shipment_insured_amount": 0,
    "device_shipment_pickup_scheduling_enabled": null,
    "device_shipment_rush": false,
    "device_type": "laptop",
    "employee_address": {
      "person_name": "Christopher Mitchell",
      "line_1": "404 Hidden Spring Lane",
      "line_2": null,
      "city": "Pittsburgh",
      "state_code": "PA",
      "postal_code": "15238",
      "country_code": "US",
      "notification_emails": [],
      "notification_sms_phone_numbers": []
    },
    "id": "01b699fe-eed7-47fb-9db7-8e3f8a9c6445",
    "notes": [
      {
        "body": "Employee may be delayed by weather.",
        "created_at": "2026-07-29T13:23:24.622Z",
        "user_email": "hr@example.com"
      }
    ],
    "number": 11401,
    "object": "DeviceTransfer",
    "payments": [
      {
        "amount_cents": 8500,
        "created_at": "2026-07-29T13:23:24.626Z",
        "refunded_amount_cents": 0,
        "state": "succeeded"
      }
    ],
    "plan_code": "basic",
    "state": "pending_box_shipment",
    "ticket_reference": null,
    "type": "return",
    "user_email": "hr@example.com"
  }
]