Welcome to the Revivn API documentation! This documentation will cover the basics of authenticating with the Revivn API and usage of the available routes.
\nLogin to the Revivn App and generate OAuth2 credentials from the API section:
\nMake an OAuth2 client_credentials POST request to obtain an access token:
\n $ curl --request POST --url 'https://api.revivn.dev/oauth/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=client_credentials' --data-urlencode 'client_id=client_id' --data-urlencode 'client_secret=client_secret' --verbose\n\nThe response should look like this:
\n{\"access_token\":\"uSeGV7Ukqi2w9JSbDP_9OxsssseZsUWSQUcyssset7w\",\"token_type\":\"Bearer\",\"expires_in\":5184000,\"scope\":\"read write\",\"created_at\":1686608864}\n\nPass this token as a header in all of your requests to the below endpoints in the below format:
\nAuthorizaton: Bearer <access_token>\n\nReturns a paginated collection of assets.
\nList of variables that appear in each asset object:
\nIncluded in the response is a meta object with page and count information:
A filter can be built using a field, operator, and a value: filter[]=field,operator,value. Repeat filter[] to combine filters. All filters must match.
Example using two filters: filter[]=manufacturer,is,Apple&filter[]=device_type,is,Laptop
created_at and updated_at support is, not, after, on_or_after, before and on_or_before. Values must be YYYY-MM-DD dates, such as 2026-09-01, and are compared by calendar day in UTC. Timestamps and other formats are rejected.
updated_at changes when a device is added, when its details change, or when a certificate of destruction is attached to that device. A certificate attached only at the pickup level does not change it.
Syncing new and updated devices: after a one-time full sync, request a rolling window each day instead of only the changes since your last run. For example, for the last 40 days:
\nfilter[]=updated_at,on_or_after,2026-08-30&page[size]=200
An invalid filter returns 400 Bad Request with a message that explains the problem:
{ \"errors\": \"Invalid filter: retired_at is not an allowed filter\" }
This includes a field that can't be filtered, an unknown operator, an operator a field doesn't support, and a date that isn't YYYY-MM-DD.
Use pagination to navigate pages of collections.
\npage[size]: Defaults to 25. Max 200
\npage[number]: Defaults to 1.
\n","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":"Returns a paginated collection of pickups.
\nList of variables that appear in each pickup object:
\nIncluded in the response is a meta object with page and count information:
A filter can be built using a field, operator, and a value.
\nExample using two filters: filter[]=state,is,complete&filter[]=initial_report_published_at,after,2026-01-01
Use pagination to navigate pages of collections.
\npage[size]: Defaults to 25. Max 200
\npage[number]: Defaults to 1.
\nAn invalid filter returns 400 Bad Request with a message that explains the problem:
{ \"errors\": \"Invalid filter: date/time field value out of range: \\\"26-01-01\\\"\" }
This includes a field that can't be filtered, an unknown operator, and a date that isn't YYYY-MM-DD.
Cancels an asset retrieval.
\nYou can cancel an asset retrieval when its order_status is one of these values:
order_placedlabels_printedpackage_out_to_employeepackage_received_by_employeeorder_staleReturns 200 OK. The cancelled asset retrieval is in the asset_retrieval key, and its order_status is order_cancelled:
{\n \"asset_retrieval\": { ... }\n}\nIt has the same fields as each item in List asset retrievals, including devices. See that request for the field list.
If you subscribe to the Retrieval Cancelled webhook event, Revivn also sends that event. See the Webhooks folder.
Returns 404 Not Found when no asset retrieval with that id exists in your organization.
Returns 422 Unprocessable Entity when the asset retrieval cannot be cancelled in its current order_status. For example, it is already order_cancelled, the employee shipped the box back (package_out_to_final_destination or package_received_by_final_destination), or it is order_completed:
{\n \"errors\": [\"Invalid state transition\"]\n}\nReturns one asset retrieval. Use it to check the status of an order without paging through List asset retrievals.
\nThe asset retrieval is in the asset_retrieval key:
{\n \"asset_retrieval\": { ... }\n}\nIt has the same fields as each item in List asset retrievals, including devices. See that request for the field list.
Returns 404 Not Found when no asset retrieval with that id exists in your organization. This includes a deleted asset retrieval.
Returns a paginated collection of asset retrievals.
\nList of variables that appear in each asset retrieval object:
\nserial_number and enrolled_status describe the first device in the order. To see every device, use devices.
devicesEvery device in the order, in the order they were added:
\nIncluded in the response is a meta object with page and count information:
A filter can be built using a field, operator, and a value.
\nExample using two filters: filter[]=box_type,is,laptop&filter[]=created_at,after,2026-01-01
Use q to find orders by text, for example q=jane doe or q=PMQ4. The search ignores case.
q must match the same order or one of its devices.AB34 finds order 5E12AB34.devices, even when only one device matched.q with filters and pagination, for example q=jane&filter[]=box_type,is,laptop&page[size]=50.Use pagination to navigate pages of collections.
\npage[size]: Defaults to 25. Max 200
\npage[number]: Defaults to 1.
\nAn invalid filter returns 400 Bad Request with a message that explains the problem:
{ \"errors\": \"Invalid filter: date/time field value out of range: \\\"26-01-01\\\"\" }
This includes a field that can't be filtered, an unknown operator, and a date that isn't YYYY-MM-DD.
\n\nPlease note: You may notice there are two keys in the response data;
\nasset_retrievalandasset_retreival. Theasset_retreivalkey will be deprecated and removed in the future. When building your automation workflow, be sure to use and expect theasset_retrievalkey.
Creates an asset retrieval (an order). Revivn ships a box to the employee, and the employee sends the device back to the return recipient, or to Revivn when direct_to_revivn is true.
Send all fields inside an asset_retrieval object.
These three mistakes cause most failed orders:
\ninsurance must be a string. Send \"1000\", not 1000. A number is rejected with 422.direct_to_revivn must be a JSON boolean. Send true or false, not \"true\", \"false\", 1, or 0. Other values are rejected with 422.country becomes US without an error. Revivn accepts US, USA, United States, and United States of America, and also CA, CAN, and Canada if your organization can ship to Canada (any capitalization). Revivn treats any other value, such as Mexico or a typo, as US when it checks the address, and does not tell you. Always send US or CA.asset_retrievalemployee_labelreturn_recipientAsset retrievals can be sent to the United States and, if enabled for your organization, Canada. From Canada, the return address must also be in Canada, unless your organization is set up to return from Canada to the United States.
\nRevivn checks the employee address, and the return address unless direct_to_revivn is true, before it creates the order. PO boxes are not supported. Use Validate address to check an address first.
Send asset for one device. All its fields are optional, but send them when you know them:
The device type comes from box_type. For example, box_type desktop makes the device a desktop.
Send assets and box_type to put several devices in one box. assets is an array of 1 or more devices, up to the capacity of the box. Send asset or assets, not both.
The device types must match the box. For example, laptop_mobile takes exactly 1 \"laptop\" and 1 \"mobile phone\".
Returns 422 Unprocessable Entity when a field is missing or not valid. errors is a message that names the problem:
{\n \"errors\": \"Missing required employee_label fields: zipcode.\"\n}\nReturns the price of asset retrievals for your organization before you create them. All amounts are in cents.
\nExample: GET /api/v1/asset_retrievals/pricing?box_type=laptop&quantity=3&country=US
The response has a pricing object.
Example: 3 laptop boxes at $85.00 each with a 10% discount:
\n","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":"Returns all webhook subscriptions of your organization, newest first. This endpoint does not use pagination.
\nThe response has a webhook_subscriptions array. See Create webhook subscription for the fields of each subscription.
Creates a webhook subscription. Revivn then sends a request to endpoint each time the event happens. See the Webhooks folder for the events and their payloads.
Send the fields inside a webhook_subscription object:
{\n \"webhook_subscription\": {\n \"event_name\": \"Pickup Complete\",\n \"endpoint\": \"https://example.com/revivn/webhooks\",\n \"request_type\": \"post\",\n \"channel\": \"rest_api\",\n \"description\": \"Notify our ITAM system\",\n \"custom_headers\": \"{\\\"X-Webhook-Secret\\\": \\\"my-shared-secret\\\"}\"\n }\n}\nReturns 201 Created and the subscription:
Returns 422 Unprocessable Entity if a field is not valid. errors has a list of messages for each field that is not valid:
{\n \"errors\": {\n \"event_name\": [\"is not included in the list\"],\n \"custom_headers\": [\"must be a JSON object\"]\n }\n}\nFor example:
\nevent_name is not one of the values above.request_type is missing, or is not post or put.custom_headers is not valid JSON, or is not a JSON object.Deletes a webhook subscription. Revivn stops sending requests for it.
\nSet webhook_subscription_id to the uuid of the subscription.
Returns 200 OK with {\"message\": \"deleted\"}.
Returns 404 Not Found if your organization has no subscription with this uuid, or if the subscription is already deleted.
Sends a sample payload for the event of the subscription to its endpoint, immediately. Use it to check that your endpoint receives and reads the request.
Set webhook_subscription_id to the uuid of the subscription.
The test request uses the same method, headers, and payload shape as a real event. The values in the payload are examples. See the Webhooks folder for the payloads.
\nReturns 200 OK with {\"message\": \"test sent\"} after Revivn sends the request. The response does not tell you which status code your endpoint returned.
Returns 404 Not Found if your organization has no subscription with this uuid.
A webhook subscription tells Revivn to send an HTTP request to your endpoint when an event happens to one of your pickups, asset retrievals, or donations.
\nSet event_name to one of these values when you create a subscription:
Pickup events are not sent for virtual pickups.
\nrequest_type of the subscription (post or put).Content-Type: application/json, plus any custom_headers you set on the subscription. Use a custom header, for example a shared secret, to confirm that a request comes from Revivn. Revivn does not sign requests.2xx status code to acknowledge the event. Revivn does not resend an event when your endpoint returns an error status code.channel is slack, set endpoint to a Slack incoming webhook URL. Revivn then sends a Slack message instead of the JSON payloads below.{\n \"pickup\": {\n \"id\": \"8b5e6a0e-3c1d-4f0e-9a51-0f6b1c2d3e4f\",\n \"order_number\": \"A1B2C3D4\",\n \"state\": \"scheduled\",\n \"scheduled_date\": \"2026-11-16\",\n \"confirmed_time\": \"9:00 AM\"\n },\n \"location\": {\n \"address\": \"141 Flushing Ave\",\n \"address2\": \"Suite 601\",\n \"city\": \"Brooklyn\",\n \"state\": \"NY\",\n \"zipcode\": \"11205\"\n },\n \"contacts\": [\n {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone_number\": \"1231231234\",\n \"point_of_contact_type\": \"main\"\n }\n ]\n}\npickup.initial_report_url is a signed link to the initial report PDF.
{\n \"pickup\": {\n \"id\": \"8b5e6a0e-3c1d-4f0e-9a51-0f6b1c2d3e4f\",\n \"order_number\": \"A1B2C3D4\",\n \"state\": \"initial_report_ready\",\n \"initial_report_url\": \"https://...\",\n \"scheduled_date\": \"2026-11-16\",\n \"confirmed_time\": \"9:00 AM\"\n },\n \"assets\": [\n {\n \"id\": \"1712dc93-6e23-47d6-9761-678b0e30c225\",\n \"serial_number\": \"C02Z1BBUL333\",\n \"device_type\": \"laptop\",\n \"manufacturer\": \"apple\"\n }\n ],\n \"location\": {\n \"address\": \"141 Flushing Ave\",\n \"address2\": \"Suite 601\",\n \"city\": \"Brooklyn\",\n \"state\": \"NY\",\n \"zipcode\": \"11205\"\n }\n}\nenrolled_status is enrolled for each device that is still enrolled in MDM, and null for the other devices.
{\n \"pickup\": {\n \"id\": \"8b5e6a0e-3c1d-4f0e-9a51-0f6b1c2d3e4f\",\n \"order_number\": \"A1B2C3D4\",\n \"state\": \"on_hold\",\n \"scheduled_date\": \"2026-11-16\",\n \"confirmed_time\": \"9:00 AM\"\n },\n \"assets\": [\n {\n \"id\": \"1712dc93-6e23-47d6-9761-678b0e30c225\",\n \"serial_number\": \"C02Z1BBUL333\",\n \"device_type\": \"laptop\",\n \"manufacturer\": \"apple\",\n \"enrolled_status\": \"enrolled\"\n }\n ],\n \"location\": {\n \"address\": \"141 Flushing Ave\",\n \"address2\": \"Suite 601\",\n \"city\": \"Brooklyn\",\n \"state\": \"NY\",\n \"zipcode\": \"11205\"\n }\n}\npickup.cod_url is a signed link to the certificate of destruction for the pickup. Each asset has its own cod_url.
{\n \"pickup\": {\n \"id\": \"8b5e6a0e-3c1d-4f0e-9a51-0f6b1c2d3e4f\",\n \"order_number\": \"A1B2C3D4\",\n \"state\": \"complete\",\n \"scheduled_date\": \"2026-11-16\",\n \"confirmed_time\": \"9:00 AM\",\n \"cod_url\": \"https://...\"\n },\n \"assets\": [\n {\n \"id\": \"1712dc93-6e23-47d6-9761-678b0e30c225\",\n \"serial_number\": \"C02Z1BBUL333\",\n \"device_type\": \"laptop\",\n \"manufacturer\": \"apple\",\n \"cod_url\": \"https://...\"\n }\n ],\n \"location\": {\n \"address\": \"141 Flushing Ave\",\n \"address2\": \"Suite 601\",\n \"city\": \"Brooklyn\",\n \"state\": \"NY\",\n \"zipcode\": \"11205\"\n }\n}\ndonation.date uses the format YYYY-MM-DD.
{\n \"donation\": {\n \"total_dollars_amount\": 6657,\n \"performed_by\": \"donor@example.com\",\n \"date\": \"2026-10-16\"\n },\n \"campaign\": {\n \"organization\": \"Boys Hope Girls Hope of New York\",\n \"description\": \"Getting laptops for our organization will support our staff...\"\n }\n}\nThe six Retrieval events use the same payload. event_type tells you which event it is:
asset_retrieval.state is the state of the asset retrieval when Revivn sends the request. asset_retrieval.completed_at is null until the asset retrieval is complete.
{\n \"event_type\": \"order_completed\",\n \"asset_retrieval\": {\n \"id\": \"0f6b1c2d-3e4f-4a51-9c1d-8b5e6a0e3c1d\",\n \"order_number\": \"DED5EC1A2B3C\",\n \"state\": \"order_completed\",\n \"completed_at\": \"2026-10-16T14:03:22.000Z\"\n },\n \"devices\": [\n {\n \"manufacturer\": \"apple\",\n \"model\": \"MacBook Pro\",\n \"serial_number\": \"C02Z1BBUL333\"\n }\n ],\n \"employee\": {\n \"name\": \"Jane Smith\",\n \"address\": \"1 Main Street, New York, NY 10001\",\n \"email\": \"employee@example.com\"\n },\n \"return_recipient\": {\n \"name\": \"John Doe\",\n \"address\": \"28201 E. Bonanza Street, South Park, CO 80440\",\n \"email\": \"recipient@example.com\"\n }\n}\nReturns the earnings balance of your organization and a paginated list of its published earnings transactions, newest first.
\nUse the same filter format as List assets: filter[]=field,operator,value.
Example: filter[]=pickup_id,is,1234
Use pagination to navigate pages of collections.
\npage[size]: Defaults to 25. Max 200
\npage[number]: Defaults to 1.
\n","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":"Checks that UPS can deliver to an address. Use it before you create an asset retrieval, to find address problems early. Create asset retrieval runs the same check on the employee address, and on the return recipient address unless direct_to_revivn is true.
Send the fields inside an address object:
{\n \"address\": {\n \"address_line_1\": \"141 Flushing Ave\",\n \"address_line_2\": \"Suite 601\",\n \"city_locality\": \"Brooklyn\",\n \"state_province\": \"NY\",\n \"postal_code\": \"11205\",\n \"country\": \"US\"\n }\n}\nReturns 200 OK with an empty object {} if the address is valid.
Returns 422 Unprocessable Entity if the address is not valid. errors is a list of messages:
{\n \"errors\": [\n {\n \"code\": \"po_box_not_allowed\",\n \"message\": \"UPS does not ship to PO Boxes. Please provide a physical street address.\",\n \"type\": \"error\"\n }\n ]\n}\nExamples of errors:
\npo_box_not_allowed: address_line_1 is a PO Box. UPS does not deliver to PO Boxes.invalid_address_format: address_line_1 contains the city, state, or postal code.