Introduction
Authentication
Manage App
Recover App
Device Hub App
Buyback Orders App
Manage Orders App
General
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:
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/v1auth_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.
Endpoints in this Folder
- 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:
POST https://dev-api.unduit.com/api/v1/auth/login
Request Structure
Response
On successful login, you’ll receive a token valid for 4 hours.
Example Response:
Error Handling
If the credentials are invalid, you’ll receive an error response:
2. Refresh Token API
Purpose:
Renew an expired or soon-to-expire token to maintain uninterrupted access to the API.
Endpoint:
POST https://dev-api.unduit.com/api/v1/refresh-token
Request Structure:
- Body: (Raw JSON)
Example Request
Response
On success, you’ll receive a new token valid for the next 4 hours.
Example Response:
Error Handling:
If the token is invalid or expired, you’ll receive an error response
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
Example Response
POST Refresh Token
Example Request
Example Response
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:
API Endpoints
1. Users List
- Endpoint:
https://dev-api.unduit.com/api/v1/users - Description: 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
AssignedAssetsarray, which contains all assets assigned to the user. If no asset is assigned, this array will be empty.
Example Request:
Method: GET
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:
Example Response
2. Asset List
Method: GET
Endpoint: https://dev-api-v1.unduit.com/api/v1/assets
Description: 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.
-
Query Parameters:
Example Response
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.
GET Users List
Example Request
Example Response
GETAssets List
Example Request
Example Response
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:
Example Request
Example Response
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
Query Parameters (for pagination)
Example Request
Example Response
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
⚠️ Max limit: You can assign a maximum of 5 items per employee.
🔁 Items Object (each item in items array)