> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.id.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.id.me/_mcp/server.

# Services API Guide

> Introduction to the ID.me Services API, including authorization, error handling, and the health check endpoint.

The ID.me Services API v2 enables partners to perform programmatic identity verifications through telecom and document verification endpoints.

## Getting started

You will receive an API key from your account manager at ID.me. This API key is required for all requests to the Services API.

### Example flow

![Sequence diagram showing the ID.me document verification flow between an End User, Integrating Partner, and ID.me API: the partner optionally initiates a verification request, the user uploads documents, the partner submits them to the document/license/verify endpoint, polls document/status while processing is pending, and optionally receives a success callback before confirming the final success status to the user.](/_fern-files/idme.docs.buildwithfern.com/a90f2aef5c64de1fcc0fbedd01e74da46b2b4e0e92322bc3959de26ce09e0e70/images/services_api/example_flow.svg)

## Authorization

All requests to the API require a Bearer token in the following format:

```
Authorization: Bearer ID.me {{token}}
```

Your token is the secret key for your account, Base64 encoded.

> **Info**
>
> Watch the [authorization demo](https://youtu.be/P4m9kqcXNmE) for a walkthrough of how to generate and use your token.

## Errors and HTTP status codes

The API uses three levels of detail in error reporting:

1. **HTTP status code** — indicates whether the request was successfully received by the API
2. **`response["status"]`** — top-level indication of whether the transaction completed successfully
3. **`response["results"]["errors"]`** — detailed error information for the transaction

**Example error response:**

**`Example`**

```json Example
{
  "errors": [{
    "code": 2200,
    "message": "Referenced product is not active"
  }]
}
```

### HTTP status codes

#### 401 — Invalid authentication credentials

| Code   | Message                                                       |
| ------ | ------------------------------------------------------------- |
| `1100` | Credentials used are not associated with any account          |
| `1200` | Credentials used are associated with an inactive account      |
| `1300` | Credentials used are associated with an inactive organization |

#### 403 — Credentials do not have access to given resource

| Code   | Message                                            |
| ------ | -------------------------------------------------- |
| `2100` | Referenced product cannot be found                 |
| `2200` | Referenced product is not active                   |
| `2300` | Referenced product is not enabled for this account |
| `3200` | Transaction is not owned by this account           |
| `3300` | Verification is not owned by this account          |

#### 404 — Accessed resource does not exist

| Code   | Message            |
| ------ | ------------------ |
| `4100` | Resource not found |

#### 422 — Invalid or missing input parameters

| Code   | Message                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| `3100` | Transaction parameter `callback_url` is invalid                                         |
| `3101` | Transaction parameter `phone` is missing or invalid                                     |
| `3102` | Transaction parameter `code` is missing or not valid                                    |
| `3103` | Transaction parameter `code` is expired                                                 |
| `3104` | Transaction retry limit exceeded                                                        |
| `3105` | Transaction is not associated with a valid possession check                             |
| `3107` | Transaction parameter `birth_date` indicates user is a minor                            |
| `3108` | Transaction parameter `birth_date` is not in YYYY-MM-DD format                          |
| `3109` | The file size is too small. Uploaded files must be greater than 40KB and less than 16MB |
| `3110` | The file size is too large. Uploaded files must be greater than 40KB and less than 16MB |
| `3111` | Image type not supported. Please send .jpeg, .jpg, or .png files                        |

#### 429 — Rate limit exceeded

| Code   | Message                              |
| ------ | ------------------------------------ |
| `5100` | Rate limit exceeded for this product |
| `5200` | Rate limit exceeded for this account |

#### 500 — Internal service errors

| Code   | Message                            |
| ------ | ---------------------------------- |
| `5000` | An error occurred for this account |

### Transaction status codes

An HTTP `200` response indicates the request was received, but `status.code` in the response body indicates whether the transaction itself completed successfully.

**`Example`**

```json Example
"status": {
  "code": 300,
  "message": "Transaction unsuccessful",
  "created": "2023-05-01T11:56:53.504-04:00",
  "updated": "2023-05-01T11:56:53.563-04:00"
}
```

A `status.code` of `300` indicates the transaction was unsuccessful.

### Transaction result errors

When `response["status"]["code"]` is not `200`, the `response["results"]["errors"]` array contains details about what went wrong:

**`Example`**

```json Example
"result": {
  "verified": false,
  "errors": [{
    "code": 2006,
    "message": "The file size is too small. Uploaded files must be greater than 40KB and less than 16MB."
  }]
}
```

Some failed identity verifications include an `additional_info` field with further context:

**`Example`**

```json Example
"result": {
  "verified": false,
  "errors": [{
    "code": 1014,
    "message": "Could not find the user",
    "additional_info": "birth_date does not match data on file."
  }]
}
```

### Full list of transaction errors

**Telecom**

| Code   | Message                                                                               |
| ------ | ------------------------------------------------------------------------------------- |
| `1001` | Phone number cannot receive SMS message                                               |
| `1002` | SMS could not be sent                                                                 |
| `1003` | The phone number you provided is blocked from receiving text messages                 |
| `1004` | The phone number you provided has recently been deactivated                           |
| `1005` | Something went wrong while delivering the text message. Please try again              |
| `1006` | The network was unable to route the text message to your phone                        |
| `1007` | The text message failed to deliver due to an issue with the phone or cellular network |
| `1008` | The phone number you provided has been flagged for fraudulent activity                |
| `1009` | The text message failed to deliver. Please make sure your phone is turned on          |
| `1010` | Text messaging is not supported by the phone, carrier, or data plan                   |
| `1011` | Something went wrong when attempting to deliver the sign in code                      |
| `1012` | Something went wrong when attempting to deliver the sign in code                      |
| `1013` | Name attribute is invalid                                                             |
| `1014` | Could not find the user                                                               |

**Document**

| Code   | Message                                                                                                                           |
| ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `2001` | Cannot verify users under 18 years old                                                                                            |
| `2002` | The document provided is expired. Please upload a valid document                                                                  |
| `2003` | The front of the document does not match to the back of the document                                                              |
| `2004` | Please ensure your document's information is clear and visible, taken on a contrasting background, and all four corners are shown |
| `2005` | We were unable to verify your document                                                                                            |

---

## Health check

GET `/health`

Returns the health status of the API. There are no parameters for this endpoint.

**`Example`**

```bash Example
curl --location 'https://services.idmelabs.com/health'
```

Returns `200 OK` with no response body.