Getting Started

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: gzip on 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 CodeOne-Line SummaryShould Request Be Resubmitted?
200OK: Request succeeded.No, request succeeded.
201Created: Resource created successfully.No, request succeeded.
400Bad Request: Server could not understand request.No, fix the request before retrying.
401Unauthorized: Authentication required.Yes, after providing credentials.
403Forbidden: Server refuses to fulfill request.No, do not resubmit.
404Not Found: Resource does not exist.No, unless resource is expected soon.
405Method Not Allowed: HTTP method not supported.No, use correct HTTP method.
408Request Timeout: Server timed out waiting.Yes, may retry.
422Unprocessable Entity: Server understands request but cannot process it.No, fix the request before retrying.
429Too Many Requests: Rate limit exceeded.Yes, after waiting as instructed.
500Internal Server Error: Server encountered error.Yes, may retry later.
502Bad Gateway: Invalid response from upstream server.Yes, may retry.
503Service Unavailable: Server temporarily unavailable.Yes, may retry after some time.
504Gateway 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