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: Most likely a required parameter is missing or in the wrong format. |
| 401 | Unauthorized: Our API server has determined the user or the account doesn't have the required permissions to use the API or has access to that resource. |
| 404 | Not found: That resource was not found. |
| 405 | Method not allowed: The method that you were calling doesn't exist for that integration. |
| 429 | Rate-Limiting has been hit by the 3rd-party vendor's API. Wait 1 second and try again. Each vendor (and your customer's plan at that vendor) will have different rate-limits. |
| 500 | Crash: Help, our server crashed... Don't worry, we know and we will fix it. |