Documentation
API
Our API documentation provides a comprehensive guide to integrating and using our platform’s features efficiently.
Heads up — we’re upgrading to API version v2.3.1!
As part of our ongoing improvements to the Unduit platform, we began work in February 2025 on upgrading our API platform. we’re rolling out API v2.3.1, built on our next-gen tech stack to improve scalability, security, and dev experience.
During this transition, a few endpoints may be temporarily unavailable or in read-only mode.
No action is required for customers already integrated — all existing APIs will remain stable and fully supported.
Introduction
Authentication
Recover App
Manage Orders App
Device Hub App
Buyback Orders App
Invoice App
Support App
Platform Users
Unduit APIs
Welcome to the Unduit API Collection
The Unduit API collection enables developers to seamlessly integrate their platforms with the Unduit system. Using these APIs, you can access and interact with data related to your company on the Unduit platform.
Purpose
This collection provides endpoints to:
- Authenticate and manage access securely using tokens.
- Fetch and manage records relevant to your company.
- Support seamless integrations with high efficiency and security.
Key Features
- Secure Access: Every request requires proper authentication, ensuring secure data handling.
- Company-Specific Data: All APIs are scoped to provide data that is specific to your company in the Unduit system.
- Ease of Use: Example requests and detailed documentation included for each endpoint.
- Scalable Integration: Built to handle multiple integrations and high-volume requests efficiently.
- Standardized Error Handling: Clear error codes are provided for better debugging and integration management.
Error Codes
The Unduit API follows standard HTTP status codes for responses:
| Code | Description |
|---|---|
| 200 | Successful response. |
| 400 | Bad request (e.g., missing parameters). |
| 401 | Unauthorized (e.g., invalid or expired token). |
| 404 | Not found (e.g., invalid endpoint or resource). |
| 422 | Validation error (e.g., invalid input format). |
| 500 | Server error (e.g., an unexpected issue). |
Getting Started
- Import this Postman collection into your workspace.
- Set up an environment with the following variables:
- base_url: https://dev-api.unduit.com/api/v1
- auth_token: The Bearer Token obtained from the Login API.
- Follow the detailed instructions provided in each API folder to understand specific functionality.
Support
If you have any questions or need assistance, feel free to reach out to the Unduit team at [email protected].
Authentication
The Authentication folder contains endpoints required to securely access the Unduit API. These APIs help you manage your access tokens and ensure secure interactions with the platform.
- Login API: Obtain an access token by authenticating with your email and password.
Refresh Token API: Renew your access token when it is about to expire.
1. Login API
Purpose:
Authenticate a user and retrieve a JSON Web Token for subsequent API requests. This token is required to authorize every request to the Unduit APIs.
Endpoint:
Request Structure
{ "email": "your-email@example.com", "password": "your-password"}
Response
On successful login, you’ll receive a token valid for 4 hours.
Example Response:
{
"message": "Login successful",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MiwiZW1haWwiOiJmYWlyd2F5aW5kZXBlbmRlbnRtb3J0Z2FnZWNvcnBvcmF0aW9uQHVuZHVpdC5jb20iLCJjb21wYW55X2lkIjozMTcsImlhdCI6MTczMzMxNTY4OCwiZXhwIjoxNzMzMzE5Mjg4fQ.RNon3WMwoBrz0C0HZxi3TDSt-LjIwL38Wnrue6yvCVw"
}
Error Handling
If the credentials are invalid, you’ll receive an error response:
{
"message": "Invalid email or password"
}
2. Refresh Token API
Purpose:
Renew an expired or soon-to-expire token to maintain uninterrupted access to the API.
Endpoint:
Request Structure:
- Body: (Raw JSON)
Example Request
{
"refresh_token": "your_current_token"
}
Response
On success, you’ll receive a new token valid for the next 4 hours.
Example Response:
{
"message": "Token refreshed successfully",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MiwiZW1haWwiOiJmYWlyd2F5aW5kZXBlbmRlbnRtb3J0Z2FnZWNvcnBvcmF0aW9uQHVuZHVpdC5jb20iLCJjb21wYW55X2lkIjozMTcsImlhdCI6MTczMzIxNTc4OCwiZXhwIjoxNzMzMzE5Mjg4fQ.RNon3WMwoBrz0C0HZxi3TDSt-LjIwL38Wnrue6yvCVw"
}
Error Handling:
If the token is invalid or expired, you’ll receive an error response
{
"message": "Invalid token"
}
Usage Notes
- Always include the Bearer Token in the Authorization header for secured endpoints.
- Tokens expire after 4 hours. Use the Refresh Token API to renew them before expiry.
- Ensure secure storage of tokens on the client-side to prevent unauthorized access.
POST Login
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/auth/login' \
--data-raw '{
"email": "jane.smith@example.com",
"password": "password"
}'
Example Response
{
"message": "Login successful",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MiwiZW1haWwiOiJmYWlyd2F5aW5kZXBlbmRlbnRtb3J0Z2FnZWNvcnBvcmF0aW9uQHVuZHVpdC5jb20iLCJjb21wYW55X2lkIjozMTcsImlhdCI6MTczMzM5Mzk5NSwiZXhwIjoxNzMzMzk3NTk1fQ.qvWAgXO-AUr5-JurBC_cBMJ1y-SWJmkcTlihS-n5gjw"
}
POST Refresh Token
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/refresh-token' \
--data '{
"refresh_token": "<token>"
}'
Example Response
{
"message": "Token has been refreshed successfully.",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MiwiZW1haWwiOiJmYWlyd2F5aW5kZXBlbmRlbnRtb3J0Z2FnZWNvcnBvcmF0aW9uQHVuZHVpdC5jb20iLCJjb21wYW55X2lkIjozMTcsImlhdCI6MTczMzM5Mzk5NSwiZXhwIjoxNzMzMzk3NTk1fQ.qvWAgXO-AUr5-JurBC_cBMJ1y-SWJmkcTlihS-n5gjw"
}
General
The General section provides foundational APIs used across the Unduit platform for managing core organizational data such as employees and their associated locations. These APIs enable customers to fetch and maintain employee records, including contact details and shipping addresses.
Data managed through these endpoints is shared across key Unduit modules such as the Locations app, Manage app (Users view), and shipping address selectors used during order workflows in Shop, Buyback, Device Hub, and Repair.
These APIs are ideal for customers who want to automate user onboarding or sync their internal systems (e.g. HR platforms) with Unduit’s IT Asset Management ecosystem.
GETEmployee Directory
These APIs allow your system to directly interact with the Unduit platform’s employee and location directory.
Use the GET Employee Directory endpoint to retrieve all employees and their associated locations registered on your organization’s Unduit account — including remote employees, corporate offices, warehouses, and more. This data powers the dynamic address selectors across Unduit apps (e.g. Shop, Buyback, Device Hub, Repair).
Employee Directory
- Retrieves a paginated list of users associated with the company. Each page contains up to 10 records by default. Developers can apply filters, such as by email, to narrow down the results. Each user object includes an AssignedAssets array, which contains all assets assigned to the user. If no asset is assigned, this array will be empty.
Example Request
Method: GET
Get all employee (default behaviour)
- https://dev-api.unduit.com/api/v1/employees?page=1
- Retrieves the first page of users, containing up to 10 records per page.
Filter by email:
- https://dev-api.unduit.com/api/v1/emoloyees?page=1&[email protected]
- Retrieves users matching the provided email address.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| page | Number | Specifies the page number for pagination. Default is 1. |
| String | (Optional) Filters users by email address. Returns matching users only. |
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/employees?page=1' \
--header 'Authorization: Bearer <token>'
Example Response
{
"totalUsers": 2,
"totalPages": 1,
"currentPage": 1,
"users": [
{
"FirstName": "John",
"LastName": "Doe",
"LocationName": "Los Angeles HQ",
"PhoneCountryCode": "+1",
"ContactInfo": "2135550198",
"Email": "john.doe@unduit.com",
"Country": "US",
"State": "CA",
"City": "Los Angeles",
"Zip": "90001",
"LocationType": "Warehouse",
"Address_1": "1234 Elm Street",
"Address_2": "Suite 400"
},
{
"FirstName": "Jane",
"LastName": "Smith",
"LocationName": "New York Branch",
"PhoneCountryCode": "+1",
"ContactInfo": "6465550123",
"Email": "jane.smith@unduit.com",
"Country": "US",
"State": "NY",
"City": "New York",
"Zip": "10001",
"LocationType": "Corporate",
"Address_1": "5678 Oak Avenue",
"Address_2": "Unit 202"
}
]
}
POSTEmployee Record
Use the POST Employee Record endpoint to programmatically create employee records, including contact information and shipping addresses.
Any record added via this API is automatically reflected in:
- The Locations app
- The Manage app → Users view
- The Shipping Address selector in Unduit’s order workflows
This enables seamless integration between your internal HR/location systems and Unduit’s IT Asset Management platform.
Request Body (JSON)
| Field | Type | Required | Description | Validation Rules |
|---|---|---|---|---|
| firstname | String | ✅ Yes | First name of the user | Must not be empty, letters and spaces only |
| lastname | String | ✅ Yes | Last name of the user | Must not be empty, letters and spaces only |
| location_name | String | ✅ Yes | Name of the associated location | Must not be empty |
| location_type | String | ✅ Yes | Type of location (e.g., Warehouse, Office, Store) | Must be one of allowed values (e.g., Warehouse, Office, etc.) |
| contact_info | Number | ✅ Yes | Phone number for contact | Must contain only numbers |
| String | ✅ Yes | Email address of the contact | Must be valid email format and must not be empty | |
| address_1 | String | ✅ Yes | Address line 1 | Must not be empty |
| address_2 | string | ❌ No | Address line 2 (e.g., apartment, suite number) | Optional |
| city | String | ✅ Yes | City name | Must not be empty |
| state | string | ✅ Yes | State or province | Must not be empty |
| zip | String | ✅ Yes | Zip or postal code | Must not be empty |
| country | String | ✅ Yes | Country code (ISO 3166-1 alpha-2, e.g., US, GB) | Must be a valid ISO 3166-1 alpha-2 country code and must not be empty. |
| contact_country | String | ✅ Yes | Country code of the contact's location | Must not be empty |
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/employee/add' \
--data-raw '{
"firstname": "John",
"lastname": "Doe",
"location_name": "San Francisco Remote Hub",
"contact_info": "3242342",
"email": "john.doe@example.com",
"address_1": "123 Market Street",
"address_2": "Suite 400",
"city": "San Francisco",
"state": "CA",
"zip": "94103",
"country": "US",
"contact_country": "US",
"location_type": "Warehouse"
}'
Example Response
{
"message": "Address added successfully",
"address": {
"firstname": "John",
"lastname": "Doe",
"username": "John Doe",
"location_name": "San Francisco Remote Hub",
"email": "john.doe@example.com",
"contact_info": "3242342",
"contact_country": "US",
"address_1": "123 Market Street",
"address_2": "Suite 400",
"city": "San Francisco",
"state": "CA",
"country": "US",
"zip": "94103",
"location_type": "Warehouse",
"id": 8027,
"user_id": 0,
"company_id": 317,
"is_default": 0,
"is_deleted": 0,
"created_at": "2025-05-12 05:56:05",
"updated_at": "2025-05-12 05:56:05",
"updatedAt": "2025-05-12T05:56:05.202Z",
"createdAt": "2025-05-12T05:56:05.202Z"
}
}
PUTEmployee Record
Use the PUT Employee Record endpoint to programmatically update employee records, including contact information and shipping addresses.
Any record added via this API is automatically reflected in:
- The Locations app
- The Manage app → Users view
- The Shipping Address selector in Unduit’s order workflows
This enables seamless integration between your internal HR/location systems and Unduit’s IT Asset Management platform.
Request Body (JSON)
| Field | Type | Required | Description | Validation Rules |
|---|---|---|---|---|
| firstname | String | ✅ Yes | First name of the user | Must not be empty, letters and spaces only |
| lastname | String | ✅ Yes | Last name of the user | Must not be empty, letters and spaces only |
| location_name | String | ✅ Yes | Name of the associated location | Must not be empty |
| location_type | String | ✅ Yes | Type of location (Warehouse, Corporate Office, Retail Store, Remote Employee) | Must be one of allowed values (Warehouse, Corporate Office, Retail Store, Remote Employee) |
| contact_info | Number | ✅ Yes | Phone number for contact | Must contain only numbers |
| String | ✅ Yes | Email address of the contact | Must be valid email format and must not be empty | |
| address_1 | String | ✅ Yes | Address line 1 | Must not be empty |
| address_2 | string | ❌ No | Address line 2 (e.g., apartment, suite number) | Optional |
| city | String | ✅ Yes | City name | Must not be empty |
| state | string | ✅ Yes | State or province | Must not be empty |
| zip | String | ✅ Yes | Zip or postal code | Must not be empty |
| country | String | ✅ Yes | Country code (ISO 3166-1 alpha-2, e.g., US, GB) | Must be a valid ISO 3166-1 alpha-2 country code and must not be empty. |
| contact_country | String | ✅ Yes | Country code of the contact's location | Must not be empty |
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/employee/update/VEl0K0tWdnVwWXJ4ai82RXFXTGNWZz98' \
--data-raw '{
"firstname": "John",
"lastname": "Doe",
"location_name": "San Francisco Remote Hub",
"contact_info": "3242342",
"email": "john.doe@example.com",
"address_1": "123 Market Street",
"address_2": "Suite 400",
"city": "San Francisco",
"state": "CA",
"zip": "94103",
"country": "US",
"contact_country": "US",
"location_type": "Warehouse"
}'
Example Response
{
"message": "Record updated successfully"
}
Manage
The Manage folder provides APIs to manage users and assets associated with a company on the Unduit platform. These APIs enable developers to retrieve lists of users and assets, view detailed information, and filter assets based on specific criteria. Below is a detailed breakdown of the APIs within this folder:
GETUser List
Retrieves a paginated list of users associated with the company. Each page contains up to 10 records by default. Developers can apply filters, such as by email, to narrow down the results. Each user object includes an AssignedAssets array, which contains all assets assigned to the user. If no asset is assigned, this array will be empty.
Example Request
Method: GET
- Get all users (default behaviour)
- https://dev-api.unduit.com/api/v1/users?page=1
- Retrieves the first page of users, containing up to 10 records per page.
- Filter by email:
- https://dev-api.unduit.com/api/v1/users?page=1&[email protected]
- Retrieves users matching the provided email address.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| page | Number | Specifies the page number for pagination. Default is 1. |
| String | (Optional) Filters users by email address. Returns matching users only. |
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/users?page=1' \
--header 'Authorization: Bearer <token>'
Example Response
{
"totalUsers": 465,
"totalPages": 47,
"currentPage": 1,
"users": [
{
"FirstName": "John",
"LastName": "Doe",
"LocationName": null,
"PhoneCountryCode": "US",
"ContactInfo": "1234567890",
"Email": "john.doe@example.com",
"Country": "US",
"State": "CA",
"City": "Los Angeles",
"Zip": "90001",
"LocationType": "Remote Employee",
"Address_1": "1234 Elm Street",
"Address_2": "",
"AssignedAssets": []
},
{
"FirstName": "Jane",
"LastName": "Smith",
"LocationName": null,
"PhoneCountryCode": "US",
"ContactInfo": "0987654321",
"Email": "jane.smith@example.com",
"Country": "US",
"State": "NY",
"City": "New York",
"Zip": "10001",
"LocationType": "Remote Employee",
"Address_1": "5678 Oak Avenue",
"Address_2": "Unit 202",
"AssignedAssets": [
{
"assetId": "LEN-0000-ABCD1234",
"modelName": "Demo Laptop",
"modelNumber": "DL-1234",
"productType": "Laptop",
"purchaseDate": "2024-10-31",
"serialNumber": "SN-ABCD1234",
"imei": "",
"imei2": "",
"sku": "",
"assetStatus": "In Use",
}
]
}
]
}
GETAssets List
Retrieves a paginated list of all assets associated with the company. Each page contains up to 10 records by default. Developers can apply filters such as serialNumber and assetId to narrow down the results. Each asset object includes an AssignedUser object, which contains the name and email of the user to whom the device is assigned. If the device is unassigned, the AssignedUser object will be null.
Example Request
Method: GET
- Get all assets (default behaviour):
- https://dev-api-v1.unduit.com/api/v1/assets?page=1
- Retrieves the first page of assets, containing up to 10 records per page.
- Filter by serial number:
- https://dev-api-v1.unduit.com/api/v1/assets?page=1&serialNumber=MBP2022XYZ
Retrieves assets with the specified serial number.
- Filter by asset ID:
- https://dev-api-v1.unduit.com/api/v1/assets?page=1&assetId=101
- Retrieves assets with the specified asset ID.
- Filter by both serial number and asset ID:
- https://dev-api-v1.unduit.com/api/v1/assets?page=1&serialNumber=MBP2022XYZ&assetId=101
Retrieves assets that match both the specified serial number and asset ID.
- https://dev-api-v1.unduit.com/api/v1/assets?page=1&serialNumber=MBP2022XYZ&assetId=101
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| page | Number | Specifies the page number for pagination. Default is 1. |
| serialNumber | String | (Optional) Filters assets by serial number. |
| assetId | String | (Optional) Filters assets by ID. |
| asset_number | String | (Optional) Filters assets by number. |
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/assets?page=1' \
--header 'Authorization: Bearer <token>'
Example Response
{
"currentPage": 1,
"totalPages": 53,
"totalItems": 523,
"assets": [
{
"asset_number": "106519700101000000",
"assetId": "DEMO-ASSET-123",
"modelName": "Core i7 10th Gen",
"modelNumber": "Model X",
"productType": "Laptop",
"purchaseDate": "2024-01-01",
"serialNumber": "SN123456",
"imei": "",
"imei2": "",
"sku": "SKU123",
"assetStatus": "In Use",
"AssignedUser": {
"firstname": "John",
"lastname": "Doe",
"username": "John Doe",
"email": "john.doe@example.com"
}
},
{
"asset_number": "116519700101000000",
"assetId": "DEMO-ASSET-456",
"modelName": "Samsung Galaxy Tab A8",
"modelNumber": "Model Y",
"productType": "Tablet",
"purchaseDate": "2024-02-01",
"serialNumber": "SN654321",
"imei": "",
"imei2": "",
"sku": "SKU456",
"assetStatus": "In Use",
"AssignedUser": {
"firstname": "Jane",
"lastname": "Smith",
"username": "Jane Smith",
"email": "jane.smith@example.com"
}
}
]
}
Key Notes
- These APIs allow developers to efficiently manage user and asset data for their company on the Unduit platform.
- Be mindful of user and asset identifiers when making requests to ensure accurate results.
- Always secure your API calls with a valid token as described in the Authentication section.
POSTAdd Asset
This endpoint allows you to add a new asset to the Manage App inventory system. It is typically used by IT administrators or asset managers to register company equipment such as laptops, desktops, phones, or other devices.
Assets added through this endpoint will be available for tracking, assignment, warranty monitoring, and lifecycle management in the application.
When adding an asset, the email field is mandatory only if the status type is set to “deployed”. For all other status types, including “undeployed”, “deployable”, “archived”, and “pending”, the email field is not required.
Request Body Parameters:
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| product_type | String | ✅ | Type of asset being added (e.g., Laptop, Mobile) | Laptop |
| product_name | String | ✅ | Full product name including model/version | MacBook Pro 2 |
| manufacturer | String | ✅ | Brand or manufacturer of the device | Apple |
| serial_number | String | ✅ | Device serial number (must be unique) | SN-XYZ-123456 |
| asset_status | String | ✅ | Current state of the asset (In Use, Available, Retired) | In Use |
| model_number | String | ❌ | Model identifier from the manufacturer | A23338 |
| sku | String | ❌ | Internal stock keeping unit ID | MBP-16-2021 |
| asset_id | String | ✅ | Unique internal asset identifier | IT-1234-ABCD-5678 |
| condition | String | ✅ | Condition of the asset (New, Good, Fair, Damaged) | Good |
| purchase_date | Date | ✅ | Purchase or lease date (ISO format YYYY-MM-DD) | 2023-01-15 |
| purchase_cost | Number | ❌ | Cost of the asset at acquisition | 1999.99 |
| purchase_type | String | ✅ | Acquisition method (Purchased, Leased) | Leased |
| warranty_start | Date | ❌ | Warranty start date | 2023-01-15 |
| warranty_expire | Date | ❌ | Warranty end date | 2025-01-14 |
| warranty_type | String | ❌ | Type of warranty coverage (e.g., AppleCare) | AppleCare |
| assign_to_email | String | ❌ | Email should be required if the status type is deployed | [email protected] |
| department | String | ❌ | Department responsible for the asset | IT |
| location_name | String | ❌ | Physical or office location of the asset | Headquarters |
| imei | String | ❌ | IMEI number (for phones/tablets only) | (optional or empty) |
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/assets/add-asset' \
--data-raw '{
"product_type": "Laptop",
"product_name": "MacBook 2 Pro",
"manufacturer": "Apple",
"serial_number": "2322334e234",
"asset_status": "in use",
"model_number": "A23338",
"sku": "MBP-16-2021",
"asset_id": "IT-12342443122ddes341234",
"condition": "Good",
"purchase_date": "2023-01-15",
"purchase_cost": 1999.99,
"purchase_type": "Leased",
"warranty_start": "2023-01-15",
"warranty_expire": "2025-01-14",
"warranty_type": "AppleCare",
"assign_to_email": "john.doe@example.com",
"department": "IT",
"location_name": "Headquarters",
"imei": ""
}'
Example Response
{
"success": "Asset created successfully",
"data": {
"id": 24546,
"company_id": 317,
"user_id": 0,
"purchase_id": 0,
"product_type_id": 4108,
"product_category_id": 1,
"model_id": 1196,
"asset_id": "",
"customer_asset_id": "IT-112342443E1234",
"serial_number": "2312E2334E234",
"model_number": "A23338",
"status_id": 60,
"condition": "Good",
"purchase_date": "2023-01-15",
"price": 1999.99,
"purchase_type": 1,
"warranty_start": "2023-01-15",
"warranty_expire": "2025-01-14",
"warranty_type": "AppleCare",
"assign_to": 8019,
"department_id": 88,
"asset_location_beta": 132,
"imei": "",
"imei2": "",
"asset_assign_date": "",
"vendor_id": 0,
"currency_code": "",
"currency_symbol": "",
"sku": "MBP-16-2021",
"address_1": "",
"city": "",
"state": "",
"zip": "",
"is_old": 0,
"created_at": "2025-06-02 04:48:25",
"updatedAt": "2025-06-02T04:48:25.221Z",
"createdAt": "2025-06-02T04:48:25.216Z",
"asset_number": "2454620250602044825"
}
}
POSTAssign Assets
This endpoint assigns an existing asset to a user within the system, based on the asset number and the user’s email address. It’s typically used by administrators or asset managers to link devices or hardware to specific employees for accountability and lifecycle tracking. Asset status type must be ‘Deployable’ to assign the asset.
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/assets/assign/user' \
--data-raw '{
"asset_number": "441819700101000000",
"assign_to_email": "john.doe@example.com"
}'
Example Response
{
"message": "Asset assigned successfully."
}
POSTUnassign Asset
This endpoint unassigns an asset from a user. It is used to remove the link between a specific asset and the user it’s currently assigned to. Typically used when a user leaves, changes departments, or returns the equipment. Asset status must not be set to ‘Deployed’ in order to unassign the asset
Query Parameters:
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| asset_number | String | ✅ | The unique ID of the asset to assign | 2454820250602045337 |
| assign_to_email | String | ✅ | The email of the user to whom the asset is being assigned | [email protected] |
| asset_status | String | ✅ | Status of the asset post-assignment (e.g., Ready to Deploy) | Ready to Deploy |
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/assets//unassign/user'
Example Response
{
"message": "Asset unassigned successfully."
}
Recover
The Recover folder provides APIs to manage IT asset recovery workflows on the Unduit platform. These APIs allow users to create recovery orders, retrieve lists of users participating in campaigns, view asset and order information, monitor recovery statuses, and access shipment tracking details. The APIs offer full visibility into the recovery process, helping organizations efficiently track and manage returning assets without modifying asset records.
GETCampaign List
1. Recover Campaigns List API
- Endpoint: GET https://dev-api.unduit.com/api/v1/recover/campaigns
- Description: Retrieves a paginated list of Recover Campaigns associated with the company. By default, the response includes up to 10 campaigns per page. The API also supports filtering options to narrow down the results as needed.
Query Parameters:
Method: GET
Endpoint: https://dev-api.unduit.com/api/v1/recover/campaigns
Query Parameters:
| Parameter | Type | Description | Example |
|---|---|---|---|
| page | Number | Page number for pagination | 1 |
| limit | Number | (Optional) Number of records per page (default is 10) | 10 |
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/recover/campaigns' \
--header 'Authorization: Bearer <token>'
Example Response
{
"total_records": 10,
"total_pages": 1,
"currentPage": 1,
"campaigns": [
{
"campaign_number": "17458430682853",
"compain_title": "Rolling Campaign for Desktops",
"start_date": "Apr 28th, 2025",
"country": {
"name": "France",
"code": "FR"
},
"total_device_count": 120,
"total_employee": 57
},
{
"campaign_number": "17448093142852",
"compain_title": "Rolling Campaign for Network Devices",
"start_date": "Apr 11th, 2025",
"country": {
"name": "India",
"code": "IN"
},
"total_device_count": 13,
"total_employee": 5
},
{
"campaign_number": "17448094992831",
"compain_title": "Rolling Campaign for MacBooks",
"start_date": "Feb 5th, 2025",
"country": {
"name": "India",
"code": "IN"
},
"total_device_count": 14,
"total_employee": 6
},
{
"campaign_number": "17448094992829",
"compain_title": "UK Cmapaign",
"start_date": "Feb 5th, 2025",
"country": {
"name": "United Kingdom",
"code": "GB"
},
"total_device_count": 7,
"total_employee": 6
},
{
"campaign_number": "17448094992654",
"compain_title": "Rolling Campaign for Printer",
"start_date": "Oct 25th, 2023",
"country": {
"name": "United States",
"code": "US"
},
"total_device_count": 20,
"total_employee": 5
},
{
"campaign_number": "17448094992450",
"compain_title": "Rolling Campaign",
"start_date": "Jan 27th, 2023",
"country": {
"name": "United States",
"code": "US"
},
"total_device_count": 8017,
"total_employee": 3422
},
{
"campaign_number": "17448094992391",
"compain_title": "Equipment Return - Corp",
"start_date": "Dec 21st, 2022",
"country": {
"name": "United States",
"code": "US"
},
"total_device_count": 64,
"total_employee": 25
}
]
}
Key Notes for Recover Campaigns List API
- This API allows developers to retrieve and manage Recover Campaign data associated with their company on the Unduit platform.
- Campaign data includes details such as campaign number, title, start date, country, total devices, and total employees.
- Results are paginated by default, with 10 campaigns per page unless otherwise specified via query parameters.
- The response structure includes country information (name and ISO code) to help with region-specific filtering or analytics.
- The assignedAssets array is present in associated employee’s data, indicating which devices are tied to specific employees (if applicable).
- Ensure your API calls are secured using a valid Bearer token, as outlined in the Authentication section.
- Use the page query parameter to navigate through multiple pages of campaign records.
- Be consistent with date formatting, and consider converting human-readable dates to a machine-parsable format if needed on the client side.
- Always validate the campaign number and associated identifiers when integrating with other modules or systems to maintain data integrity
GETCampaign Details
Description:
This API retrieves detailed information about a specific Recover Campaign, including:
- Campaign metadata (title, country, start date)
- Return address information
- A list of employee associated with the campaign
- Assets assigned to each employee
- Tracking information for each employee
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| campaign_number | String | ✅ Yes | Unique identifier of the recover campaign |
Query Parameters (for pagination)
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| page | Number | ❌ No | 1 | Page number to retrieve (for paginated employee results) |
| limit | Number | ❌ No | 10 | Number of employees to return per page |
Example Request
curl --location 'https://dev-api.unduit.com/api/v1/recover/employees/details/17449821332893'
Example Response
{
"campaign_number": "17458430682853",
"title": "Rolling Campaign for Desktops",
"country": {
"name": "France",
"code": "FR"
},
"start_date": "Apr 28th, 2025",
"helpdesk_email": null,
"return_address": [
{
"name": "John Doe",
"title": "Rolling Campaign for Desktops",
"company": "xxxxx",
"country": {
"name": "France",
"code": "FR"
},
"state": null,
"city": "xxxx",
"zip_code": "xxxx",
"address": "xxxxx",
"phone": "xxxxxxxx",
"email": "xxxxxxxx",
"packages": [
{
"device": "Laptop",
"qty": 1,
"incomingWeight": 10,
"length": 16,
"width": 12,
"height": 4
},
{
"device": "Monitor 32\"",
"qty": 1,
"incomingWeight": 30,
"length": 30,
"width": 30,
"height": 12
}
]
}
],
"employees": [
{
"recovery_id": "174584241251583",
"email": "xxxxxx",
"firstname": "John",
"lastname": "Doe",
"phone_country": "FR",
"phone_number": "xxxxxxx",
"country": {
"name": "France",
"code": "FR"
},
"state": {
"name": "Paris",
"code": "PR",
"country_code": "FR"
},
"city": "paris",
"zip": "xxxx",
"address_line_1": "xxxxxxxx",
"address_line_2": "xxxxxxxxx",
"items": [
{
"item": "Laptop",
"item_serial_no": null,
"item_asset_id": null,
"item_imei": null,
"custom_field_1": null,
"custom_field_2": null
},
{
"item": "Desktop",
"item_serial_no": null,
"item_asset_id": null,
"item_imei": null,
"custom_field_1": null,
"custom_field_2": null
},
{
"item": "iphone",
"item_serial_no": null,
"item_asset_id": null,
"item_imei": null,
"custom_field_1": null,
"custom_field_2": null
},
{
"item": "Apple iPhone 14 Pro Max",
"item_serial_no": null,
"item_asset_id": null,
"item_imei": null,
"custom_field_1": null,
"custom_field_2": null
},
{
"item": "Apple iPhone 15 Pro Max",
"item_serial_no": null,
"item_asset_id": null,
"item_imei": null,
"custom_field_1": null,
"custom_field_2": null
}
],
"status": "Order Received",
"tracking": [
{
"carrier_name": "ups",
"forward_shipping": {
"tracking_number": "xxxxxxxx",
"tracking_link": "null"
},
"return_shipping": {
"return_tracking_number": "xxxxxxxxxx",
"return_tracking_link": "https://wwwapps.ups.com/WebTracking/processRequest?HTMLVersion=5.0&Requester=NES&loc=en_US&tracknum=xxxxxxxx"
}
},
{
"carrier_name": "ups",
"forward_shipping": {
"tracking_number": "",
"tracking_link": null
},
"return_shipping": {
"return_tracking_number": "xxxxxxxxx",
"return_tracking_link": "https://wwwapps.ups.com/WebTracking/processRequest?HTMLVersion=5.0&Requester=NES&loc=en_US&tracknum=xxxxxx"
}
},
],
"last_updated": "Apr 28th, 2025"
}
],
"total_employees": 2,
"total_pages": 1,
"current_page": 1
}
POSTAdd Employee
This API is used to add a new employee to an existing Recover Campaign, along with their return address and assigned asset details. The employee will be associated with the specified campaign and will be expected to return the listed items.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| campaign_number | String | ✅ Yes | Unique identifier of the recover campaign |
| String | ✅ Yes | Employee's email address | |
| firstname | String | ✅ Yes | First name of the employee |
| lastname | String | ✅ Yes | Last name of the employee |
| phone | String | ✅ Yes | Employee's phone number (with country code if international) |
| address_line_1 | String | ✅ Yes | Primary address line |
| address_line_2 | String | ❌ No | Secondary address line |
| city | String | ✅ Yes | City of the employee’s address |
| state | String | ✅ Yes | State or province code |
| zip | String | ✅ Yes | ZIP or postal code |
| country | String | ✅ Yes | ISO 2-letter country code (e.g., US, IN, GB) |
| shipping_option | String | ✅ Yes | Defines how the recovery will proceed. Options: • create_prepaid_shipping_label • send_recovery_kit |
| callback_url | String | ⚠️ Conditionally Required | Required only if shipping_option is create_prepaid_shipping_label. The shipping label will be sent to the provided callback URL. Not required for send_recovery_kit. |
| items | Array | ✅ Yes | List of items/assets assigned to the employee (at least one item is required) |
⚠️ Max limit: You can assign a maximum of 5 items per employee.
🔁 Items Object (each item in items array)
| Field | Type | Required | Description |
|---|---|---|---|
| item | String | ✅ Yes | Name/label of the asset |
| item_serial_no | String | ❌ No | Serial number of the asset |
| item_asset_id | String | ❌ No | Internal asset ID |
| item_imei | String | ❌ No | IMEI number (for mobile devices) |
| custom_field_1 | String | ❌ No | Custom metadata field 1 |
| custom_field_2 | String | ❌ No | Custom metadata field 2 |
Example Request
curl --location --request GET 'https://dev-api.unduit.com/api/v1/recover/user/add' \
--data-raw '{
"campaign_number": 17449821332893,
"email": "john.doe@company.com",
"firstname": "John",
"lastname": "Doe",
"phone": "1632960123",
"address_line_1": "123 Business Park",
"address_line_2": "Suite 200",
"city": "London",
"state": "LDN",
"zip": "10001",
"country": "GB",
"items": [
{
"item": "MacBook Pro 16",
"item_serial_no": "C02XL0XXXXX1",
"item_asset_id": "IT-APPLE-001",
"item_imei": "",
"custom_field_1": "2023-issue",
"custom_field_2": "Finance Dept"
},
{
"item": "iPhone 15 Pro",
"item_serial_no": "DNXXXXXX1JKL",
"item_asset_id": "IT-APPLE-002",
"item_imei": "35693803564XXXX",
"custom_field_1": "Mobile Plan: Corp",
"custom_field_2": "Manager Approval"
}
]
}'
Example Response
{
"success": true,
"message": "Employee added successfully"
}
