API Key
Need an API Key? Click here!
Authentication
API requests must include an AdeptID API key in the authentication header:
Set the HTTP header X-API-KEY: <AdeptID API Key> on the request.
Enable JSON content
AdeptID APIs send and respond to JSON. Set the following HTTP headers on all requests to enable sending and receiving JSON:
Content-Type: application/json
Accept: application/json
Compress Payloads
AdeptID recommends always compressing inbound payloads. The default inbound payload is limited to 20MB.
To send compressed payloads:
- Add or enable gzip compression in your client code. Many HTTP client libraries support this natively, but the payload can also be compressed as a step before sending the request.
- Set the HTTP header
Content-Encoding: gzipon the request.
API Versioning
We periodically release new, dated versions of the API whenever we make breaking changes. We try to only make backwards compatible changes, but sometimes we have to make a breaking change to iterate on the API.
We consider the following changes backwards compatible:
- Adding new API endpoints
- Adding new optional parameters to existing endpoints
- Adding new data elements to existing responses
- Adding new errors
- Changing parameters from “Required” to “Optional”
API HTTP Status Codes
This table provides a reference for common HTTP status codes, their meanings, and guidance on whether requests should be resubmitted.
| Status Code | One-Line Summary | Should Request Be Resubmitted? |
|---|---|---|
| 200 | OK: Request succeeded. | No, request succeeded. |
| 201 | Created: Resource created successfully. | No, request succeeded. |
| 400 | Bad Request: Server could not understand request. | No, fix the request before retrying. |
| 401 | Unauthorized: Authentication required. | Yes, after providing credentials. |
| 403 | Forbidden: Server refuses to fulfill request. | No, do not resubmit. |
| 404 | Not Found: Resource does not exist. | No, unless resource is expected soon. |
| 405 | Method Not Allowed: HTTP method not supported. | No, use correct HTTP method. |
| 408 | Request Timeout: Server timed out waiting. | Yes, may retry. |
| 422 | Unprocessable Entity: Server understands request but cannot process it. | No, fix the request before retrying. |
| 429 | Too Many Requests: Rate limit exceeded. | Yes, after waiting as instructed. |
| 500 | Internal Server Error: Server encountered error. | Yes, may retry later. |
| 502 | Bad Gateway: Invalid response from upstream server. | Yes, may retry. |
| 503 | Service Unavailable: Server temporarily unavailable. | Yes, may retry after some time. |
| 504 | Gateway Timeout: Upstream server timed out. | Yes, may retry. |
Summary Notes
- 2xx codes (200, 201): Success responses - no need to resubmit
- 4xx codes (400, 401, 403, 404, 405, 408, 422, 429): Client errors - only retry after fixing the issue or waiting (for 429)
- 5xx codes (500, 502, 503, 504): Server errors - generally safe to retry, possibly after a delay