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 create, read, and manage orders, read shipments, and more:

Device transfers ("orders")

Notes

Shipments

Who has access to the API?

Only organization admin users can use the API. Your organization must have Enterprise plan enabled and a payment method on file. 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

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".

To add a payment method:

  1. Click the "Settings" button at the top.
  2. Click to "Manage payment methods".

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://mta-sts.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-09-04T18:09:08.149Z",
  "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": "e4c94ef3-9541-4ae9-9732-94f2e76406fe",
  "messages": [],
  "notes": [],
  "number": 75696,
  "object": "DeviceTransfer",
  "payments": [],
  "plan_code": "enterprise",
  "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://mta-sts.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-09-04T18:09:08.162Z",
    "state": "pre_transit",
    "tracking_id": "11111111111111111111",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=11111111111111111111",
    "updated_at": "2026-09-04T18:09:08.162Z"
  },
  "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-09-04T18:09:08.162Z",
  "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-09-04T18:09:08.163Z"
  },
  "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": "a257c24a-19c3-4e0a-b673-557df6ff4031",
  "messages": [
    {
      "body": "<html><body><p>We are sending you a box and prepaid shipping label to return your StarCo laptop.</p><p>The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered. It will contain full instructions for you to return the laptop.</p></body></html>",
      "created_at": "2026-09-04T18:09:08.163Z",
      "state": "delivered",
      "subject": "Sending you a box to return your StarCo laptop",
      "summary": "Sending you a box to return your StarCo laptop",
      "type": "email"
    },
    {
      "body": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
      "created_at": "2026-09-04T18:09:08.165Z",
      "state": "sent",
      "subject": null,
      "summary": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
      "type": "sms"
    }
  ],
  "notes": [
    {
      "body": "Employee may be delayed by weather.",
      "created_at": "2026-09-04T18:09:08.165Z",
      "user_email": "hr@example.com"
    }
  ],
  "number": 71249,
  "object": "DeviceTransfer",
  "payments": [
    {
      "amount_cents": 8500,
      "created_at": "2026-09-04T18:09:08.171Z",
      "refunded_amount_cents": 0,
      "state": "succeeded"
    }
  ],
  "plan_code": "enterprise",
  "state": "pending_box_shipment",
  "ticket_reference": null,
  "type": "return",
  "user_email": "hr@example.com"
}

Update a device transfer

Update an existing device transfer. Please note that only certain attributes can be updated after create.

Method PATCH
URL https://mta-sts.sandbox.reready.co/api/v1/device_transfers/DEVICE-RETURN-UUID-HERE
JSON parameters

device_serial_number*

ticket_reference*

* See definitions above

Example JSON request 
{
  "device_serial_number": "1234567890"
}
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-09-04T18:09:08.180Z",
  "device_condition": null,
  "device_make": null,
  "device_model": null,
  "device_serial_number": "1234567890",
  "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": "4205ef49-b038-4a36-930e-6dada92e0359",
  "messages": [],
  "notes": [],
  "number": 44854,
  "object": "DeviceTransfer",
  "payments": [],
  "plan_code": "enterprise",
  "state": "not_started",
  "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://mta-sts.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-09-04T18:09:08.193Z",
    "state": "pre_transit",
    "tracking_id": "11111111111111111111",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=11111111111111111111",
    "updated_at": "2026-09-04T18:09:08.193Z"
  },
  "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-09-04T18:09:08.193Z",
  "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-09-04T18:09:08.193Z"
  },
  "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": "ab30e0ac-7654-41c8-af45-7b541589cdab",
  "messages": [
    {
      "body": "<html><body><p>We are sending you a box and prepaid shipping label to return your StarCo laptop.</p><p>The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered. It will contain full instructions for you to return the laptop.</p></body></html>",
      "created_at": "2026-09-04T18:09:08.194Z",
      "state": "delivered",
      "subject": "Sending you a box to return your StarCo laptop",
      "summary": "Sending you a box to return your StarCo laptop",
      "type": "email"
    },
    {
      "body": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
      "created_at": "2026-09-04T18:09:08.196Z",
      "state": "sent",
      "subject": null,
      "summary": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
      "type": "sms"
    }
  ],
  "notes": [
    {
      "body": "Employee may be delayed by weather.",
      "created_at": "2026-09-04T18:09:08.200Z",
      "user_email": "hr@example.com"
    }
  ],
  "number": 85371,
  "object": "DeviceTransfer",
  "payments": [
    {
      "amount_cents": 8500,
      "created_at": "2026-09-04T18:09:08.204Z",
      "refunded_amount_cents": 0,
      "state": "succeeded"
    }
  ],
  "plan_code": "enterprise",
  "state": "canceled",
  "ticket_reference": null,
  "type": "return",
  "user_email": "hr@example.com"
}

Confirm a device transfer

Confirm a device transfer previously created with skip_manual_confirm not given or given as false. Confirming commits payment and triggers fulfillment of your order. If the organization has enabled monthly auto-pay, payment will be captured on the 1st of the next month. Otherwise, payment will be captured immediately using either 1) the payment method you have configured in your user settings, or 2) the organization's last-created payment method.

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

None

Example JSON request 
{}
Example JSON response 
{
  "box_shipment": {
    "carrier_code": "USPS",
    "delivered_at": null,
    "shipped_at": "2026-09-04T18:09:08.212Z",
    "state": "pre_transit",
    "tracking_id": "11111111111111111111",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=11111111111111111111",
    "updated_at": "2026-09-04T18:09:08.212Z"
  },
  "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-09-04T18:09:08.212Z",
  "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-09-04T18:09:08.213Z"
  },
  "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": "92730e66-7712-4cbd-bd42-5362416aac47",
  "messages": [
    {
      "body": "<html><body><p>We are sending you a box and prepaid shipping label to return your StarCo laptop.</p><p>The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered. It will contain full instructions for you to return the laptop.</p></body></html>",
      "created_at": "2026-09-04T18:09:08.213Z",
      "state": "delivered",
      "subject": "Sending you a box to return your StarCo laptop",
      "summary": "Sending you a box to return your StarCo laptop",
      "type": "email"
    },
    {
      "body": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
      "created_at": "2026-09-04T18:09:08.215Z",
      "state": "sent",
      "subject": null,
      "summary": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
      "type": "sms"
    }
  ],
  "notes": [
    {
      "body": "Employee may be delayed by weather.",
      "created_at": "2026-09-04T18:09:08.216Z",
      "user_email": "hr@example.com"
    }
  ],
  "number": 49135,
  "object": "DeviceTransfer",
  "payments": [
    {
      "amount_cents": 8500,
      "created_at": "2026-09-04T18:09:08.220Z",
      "refunded_amount_cents": 0,
      "state": "succeeded"
    }
  ],
  "plan_code": "enterprise",
  "state": "pending_box_shipment",
  "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://mta-sts.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-09-04T18:09:08.229Z",
      "state": "pre_transit",
      "tracking_id": "11111111111111111111",
      "tracking_url": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=11111111111111111111",
      "updated_at": "2026-09-04T18:09:08.229Z"
    },
    "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-09-04T18:09:08.228Z",
    "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-09-04T18:09:08.229Z"
    },
    "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": "510bbe1f-cfa6-47c0-8653-eb83ff3fb75f",
    "messages": [
      {
        "body": "<html><body><p>We are sending you a box and prepaid shipping label to return your StarCo laptop.</p><p>The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered. It will contain full instructions for you to return the laptop.</p></body></html>",
        "created_at": "2026-09-04T18:09:08.229Z",
        "state": "delivered",
        "subject": "Sending you a box to return your StarCo laptop",
        "summary": "Sending you a box to return your StarCo laptop",
        "type": "email"
      },
      {
        "body": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
        "created_at": "2026-09-04T18:09:08.231Z",
        "state": "sent",
        "subject": null,
        "summary": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
        "type": "sms"
      }
    ],
    "notes": [
      {
        "body": "Employee may be delayed by weather.",
        "created_at": "2026-09-04T18:09:08.232Z",
        "user_email": "hr@example.com"
      }
    ],
    "number": 83908,
    "object": "DeviceTransfer",
    "payments": [
      {
        "amount_cents": 8500,
        "created_at": "2026-09-04T18:09:08.235Z",
        "refunded_amount_cents": 0,
        "state": "succeeded"
      }
    ],
    "plan_code": "enterprise",
    "state": "pending_box_shipment",
    "ticket_reference": null,
    "type": "return",
    "user_email": "hr@example.com"
  }
]

Create a device transfer note

Add your own note to an existing device transfer, timestamped and attributed to you. Your note will be returned under notes when you view a device transfer or list all device transfers in the API, and visible when you view the order in the interface.

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

body: A string. Min of 5 characters and max of 10000.

Example JSON request 

{
  "body": "Employee may be delayed by weather."
}
Example JSON response 
[
  {
    "box_shipment": {
      "carrier_code": "USPS",
      "delivered_at": null,
      "shipped_at": "2026-09-04T18:09:08.256Z",
      "state": "pre_transit",
      "tracking_id": "11111111111111111111",
      "tracking_url": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=11111111111111111111",
      "updated_at": "2026-09-04T18:09:08.256Z"
    },
    "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-09-04T18:09:08.255Z",
    "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-09-04T18:09:08.256Z"
    },
    "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": "54a2b7e6-6a20-48ff-8560-72526b379ba7",
    "messages": [
      {
        "body": "<html><body><p>We are sending you a box and prepaid shipping label to return your StarCo laptop.</p><p>The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered. It will contain full instructions for you to return the laptop.</p></body></html>",
        "created_at": "2026-09-04T18:09:08.256Z",
        "state": "delivered",
        "subject": "Sending you a box to return your StarCo laptop",
        "summary": "Sending you a box to return your StarCo laptop",
        "type": "email"
      },
      {
        "body": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
        "created_at": "2026-09-04T18:09:08.259Z",
        "state": "sent",
        "subject": null,
        "summary": "We are sending you a box and prepaid shipping label to return your StarCo laptop. The USPS tracking number is 5555555555555555. We will notify you as soon as this box is delivered.",
        "type": "sms"
      }
    ],
    "notes": [
      {
        "body": "Employee may be delayed by weather.",
        "created_at": "2026-09-04T18:09:08.260Z",
        "user_email": "hr@example.com"
      }
    ],
    "number": 30309,
    "object": "DeviceTransfer",
    "payments": [
      {
        "amount_cents": 8500,
        "created_at": "2026-09-04T18:09:08.265Z",
        "refunded_amount_cents": 0,
        "state": "succeeded"
      }
    ],
    "plan_code": "enterprise",
    "state": "pending_box_shipment",
    "ticket_reference": null,
    "type": "return",
    "user_email": "hr@example.com"
  }
]

View a shipment

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

Method GET
URL https://mta-sts.sandbox.reready.co/api/v1/shipments/SHIPMENT-TRACKING-OR-UUID-HERE
JSON parameters

None

Example JSON request 
{}
Example JSON response 
{
  "carrier_code": "UPS",
  "created_at": "2026-09-04T18:09:08.271Z",
  "delivered_at": null,
  "device_transfer_id": "d7e91ced-15b0-4307-8e82-876f45c29422",
  "from_address": {
    "line_1": "123 Apple St",
    "line_2": null,
    "city": "Orchard",
    "district": null,
    "state_code": "PA",
    "postal_code": "16841",
    "country_code": "US"
  },
  "id": "636bbd6c-098a-4421-bc0e-2085241dfdc0",
  "object": "Shipment",
  "shipped_at": null,
  "state": "in_transit",
  "to_address": {
    "line_1": "456 Beach Blvd",
    "line_2": null,
    "city": "Oceanside",
    "district": null,
    "state_code": "CA",
    "postal_code": "92054",
    "country_code": "US"
  },
  "tracking_code": "123456789012",
  "tracking_url": "https://www.ups.com/track?loc=en_US&tracknum=123456789012",
  "updated_at": "2026-09-04T18:09:08.272Z"
}