REST API
This API is organized around REST and utilizes predictable resource-oriented URLs, accepts various request formats, returns responses in multiple formats, and uses standard HTTP response codes, authentication, and verbs.
It provides predictable URLs for accessing resources and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with from a wide variety of environments, from command-line utilities to gadgets to the browser URL bar itself.
The API accepts JSON in requests and multiple content types for responses, including JSON, CSV, XML, NDJSON, and SCIM+JSON. Only the UTF-8 character encoding is supported for both requests and responses.
Authentication
Send your API token in the Authorization HTTP header for each API request.
Example: Authorization: Bearer eyJhbGciOiJIUzI1NiIXVCJ9
All API requests must be made over HTTPS. API requests made over plain HTTP or without authentication will fail. Furthermore, all connections must support the TLS 1.2 version for their SSL/HTTPS protocol.
Find your workspace API Token at app.unified.to/settings/api
API URLs
Unified has two separate data-regions around the world currently. To use the API URL in a data-region, you must register an account with our application in that data region.
| Region | API URL | Application URL |
|---|---|---|
| North America | https://api.unified.to | https://app.unified.to |
| Europe | https://api-eu.unified.to | https://app-eu.unified.to |
HTTP Methods
| Method | Description |
|---|---|
| GET | Retrieve a single resource or get an array of resources |
| PUT / PATCH | Update a single resource partially or fully |
| POST | Create a single resource |
| DELETE | Remove a single resource |
Request Format
This API accepts JSON payloads. You must supply a Content-Type: application/json header in PUT and POST requests.
The documented JSON properties for this API are case sensitive. For example, id and Id would not constitute the same property.
Response Format
This API can return responses in multiple formats. You can specify your preferred response format by setting the Accept header in your request. The supported response formats are:
| Format | Header |
|---|---|
| JSON (default) | Accept: application/json |
| NDJSON (Newline Delimited JSON) | Accept: application/ndjson |
| CSV (Comma-Separated Values) | Accept: text/csv |
| XML | Accept: text/xml |
| SCIM+JSON (for SCIM endpoints) | Accept: application/scim+json |
If no Accept header is specified, the API will default to returning JSON responses.
When you successfully create or update a resource, the API will respond with the resulting resource in the requested format.
This API responds to successful requests with HTTP status codes in the 200 or 300 range, and with HTTP status codes in the 400 range if an error occurred.
A list of objects is sent as an array of objects in JSON and NDJSON formats, as rows in CSV format, or as nested elements in XML format. All other operations return a single object.
Note: The SCIM+JSON format is only available for specific endpoints (e.g. employee and group).
Common HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Ok: The request was successful. |
| 400 | Bad Request: Required parameters are missing or in the wrong format. Check the request payload against the API documentation. |
| 401 | Unauthorized: The connection is likely broken and requires recreation. This typically occurs when app access has been revoked or authentication credentials are invalid. |
| 403 | Forbidden: The connection lacks the required permissions or scopes. This usually indicates a mismatch between the scopes configured in your provider's developer account and what Unified.to is requesting. |
| 404 | Not Found: The requested resource was not found. |
| 429 | Rate Limit Exceeded: The provider's API rate limit has been reached. Each platform (and customer plan) has different rate limits. Consider using webhooks or implementing request throttling. |
| 500 | Internal Server Error: Our server encountered an unexpected condition. We monitor these errors and will work to resolve them. For platform issues, retry after a short delay. |
| 501 | Not Implemented: The requested functionality is not supported by this integration. Check the integration's documentation for supported features. |
For more help with error codes, review our troubleshooting guide.