REST API documentation

Use our API to automatically initiate device returns and monitor their progress until completion. Available for Enterprise accounts 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 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 company's Enterprise status:

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

Authentication

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

Authorization: Token YOUR-API-KEY-HERE

To view 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.

Creating a device return

Create a new device return. This will cause your payment method to be charged. As a result, an empty box will be sent to the employee address, containing a prepaid shipping label, which the employee can use to send the device to the company address.

Method POST
URL https://www.reready.co/api/v1/device_returns
JSON parameters

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

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

company_address: A JSON object with these parameters:

  • company_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

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

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

type (optional): Defaults to laptop. Options are: laptop and monitor (in the future there will be options for mobile, tablet, etc.)

Example JSON request 
{
  "company_address": {
    "company_name": "Maas Biolabs",
    "attention_name": "Human Resources",
    "line_1": "555 Nondescript Road",
    "city": "Maricopa",
    "state_code": "AZ",
    "postal_code": "85139",
    "country_code": "US"
  },
  "employee_address": {
    "person_name": "Christopher Mitchell",
    "line_1": "404 Hidden Spring Lane",
    "city": "Pittsburgh",
    "state_code": "PA",
    "postal_code": "15238",
    "country_code": "US"
  },
  "type": "laptop"
}
Example JSON response 
{
  "company_address": {
    "company_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",
    "tracking_emails": [

    ]
  },
  "created_at": "2024-11-19T04:35:08.565Z",
  "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",
    "email": null
  },
  "enterprise": false,
  "id": "14264d0f-c4e5-49f1-ad7b-c020e36fc88d",
  "object": "DeviceReturn",
  "return_shipment_insured_amount": 0,
  "state": "pending_outbound_shipment",
  "type": "laptop",
  "user_email": "hr@example.com"
}

Viewing a device return

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

Method GET
URL https://www.reready.co/api/v1/device_returns/DEVICE-RETURN-UUID-HERE
JSON parameters

None

Example JSON request 
{
}
Example JSON response 
{
  "company_address": {
    "company_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",
    "tracking_emails": [

    ]
  },
  "created_at": "2024-11-19T04:35:08.565Z",
  "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",
    "email": null
  },
  "enterprise": false,
  "id": "14264d0f-c4e5-49f1-ad7b-c020e36fc88d",
  "object": "DeviceReturn",
  "return_shipment_insured_amount": 0,
  "state": "pending_outbound_shipment",
  "type": "laptop",
  "user_email": "hr@example.com"
}