Basics of APIs
The methods, headers, parameters and status codes the TrueIdentity API uses.
The TrueIdentity API is a JSON REST API. Requests and responses are application/json, and every call is authenticated. If you are deciding which integration suits you, start at Choosing an Integration.
HTTP methods
The API uses three, and no others.
GET reads something: the details of an identity request, a credential, the service status.
POST creates something or asks for an action: requesting a new TrueIdentity, submitting a credential, revoking one.
DELETE removes something: cancelling an identity request that has not been completed.
There is no PUT or PATCH. Nothing in the API is edited in place - an identity request is created, read, and either completed or deleted.
Headers
Four headers matter, and the first three are required on every authenticated call.
| Header | Purpose |
|---|---|
Authorization | The access token from the auth endpoint |
X-Tenant-Id | Your tenant, issued to you when your account is set up |
X-Request-Timestamp | Unix timestamp of the request |
X-Correlation-Id | Optional. Your own identifier for the request, echoed back on the response and in our logs. Worth sending: it is the fastest way for us to find a specific call |
Parameters
Path parameters identify what you are acting on, and are part of the address:
/identity/request/{access_request_code}/{identity_session_code}.Request body parameters carry the data itself, as JSON.
The API takes no query parameters. Anything that shapes a request is either in the path or in the body.
Status codes
| Code | Meaning |
|---|---|
200 | The request succeeded |
400 | The request was malformed, or a value failed validation |
401 | Authentication failed, or no token was sent |
403 | Authenticated, but not allowed to do this |
404 | No such resource, or not yours |
409 | Conflicts with something that already exists |
410 | The credential has been revoked |
412 | A precondition failed: expired, revoked, or awaiting acceptance |
413 | The uploaded file is too large |
422 | Understood, but could not be processed |
429 | Rate limited. Back off and retry |
500 | Something failed on our side |
503 | A service the request depends on is unavailable |
Errors
Every error returns the same shape, whatever the status code:
{
"error": {
"message": "Invalid phone number format",
"type": "VALIDATION_ERROR",
"code": "E1001",
"timestamp": "2026-02-20T03:14:15Z",
"correlation_id": "req-64b4a7e123456"
}
}
Match on type or code, never on message. The message is written for people and may be reworded; the other two are part of the contract. The full list is in the Error schema on any endpoint page.
correlation_id is the one to quote if you contact us about a specific request.