> 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.

# Document Passback API Guide

> Retrieve images of identity documents verified through IDMe using the Document Passback API.

The Document Passback API lets your organization retrieve images of the identity documents used during IDMe verification, such as driver's licenses and passports. Access requires an API token provisioned by your IDMe account team.

## Environments

IDMe provides two environments:

#### Sandbox

`https://api.idmelabs.com/`

#### Production

`https://api.id.me/`

## Prerequisites

Before using the Document Passback API:

* Document Passback must be enabled on your consumer by your IDMe account team
* Your consumer must be configured to return the `document_tokens` attribute from the attributes endpoint
* You must have an API token provisioned by your IDMe account team

## How it works

Retrieving a document image requires two values obtained from separate sources:

* A **document token** — returned dynamically from the attributes endpoint for each verified session
* An **API token** — a static token provisioned for your consumer by your IDMe account team

#### Get document tokens from the attributes endpoint

Call the attributes endpoint with a valid access token:

**`Example`**

```bash Example
GET https://api.idmelabs.com/api/public/v3/attributes.json?access_token={ACCESS_TOKEN}
```

When `document_tokens` is enabled on your consumer, the response includes a `front` and `back` token for the verified identity document:

**`Example`**

```json Example
{
  "handle": "document_tokens",
  "name": "Document Passback Tokens",
  "value": {
    "front": "d9ec9c13-f3e6-4b2e-a34f-e3f45b21206f",
    "back": "fb4ad373-45a6-4a64-bb3c-43e0c59d1ab5"
  }
}
```

> **Warning**
>
> Document tokens are unique per call to the attributes endpoint — store them immediately if you need them for subsequent requests

#### Retrieve the document image

Make a POST request to the Document endpoint using the document token and your API token:

**`Example`**

```bash Example
POST https://api.idmelabs.com/api/public/v3/documents/{DOCUMENT_TOKEN}?token={API_TOKEN}
```

**Example:**

**`Example`**

```bash Example
POST https://api.idmelabs.com/api/public/v3/documents/3696f8c1a8ee4ae9aab56fb38c3dbd03?token=1234567-fd03-4ca4-a93e-aae6fce8e82b
```

The response is the raw image file of the identity document.

## Token refresh

If you need a document image for a repeat transaction but have not made a new call to the attributes endpoint, use the Token Refresh endpoint to generate a new document token without requiring a new user session.

**`Example`**

```bash Example
POST https://api.idmelabs.com/api/public/v3/documents/refresh/{DOCUMENT_TOKEN}?token={API_TOKEN}
```

**Example response:**

**`Example`**

```json Example
{ "document_token": "8003c78ead9641bcbd284e97acac3f85" }
```

Use the returned token to call the Document endpoint as normal.

## Dynamic image sizing

Pass a `size` parameter to resize the returned image:

**`Example`**

```bash Example
POST https://api.idmelabs.com/api/public/v3/documents/{DOCUMENT_TOKEN}?token={API_TOKEN}&size=300x200
```

If no `size` parameter is provided, the image is returned at its original uploaded resolution.

### Aspect ratio

IDMe preserves the original aspect ratio using the smaller dimension as the constraint. For example, requesting `300x200` on a `500x400` image returns `250x200`.

### Size bounds

|         | Value  |
| ------- | ------ |
| Minimum | `100`  |
| Maximum | `1000` |

## Rate limiting

The Document endpoint is rate-limited to **2 requests per minute** per document.