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](/getting-started/customizing).

### 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:

```json
{
  "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.