APIs

Document passback API

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

Environments

ID.me 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 ID.me 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 ID.me 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 ID.me account team
1

Get document tokens from the attributes endpoint

Call the attributes endpoint with a valid access token:

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
1{
2  "handle": "document_tokens",
3  "name": "Document Passback Tokens",
4  "value": {
5    "front": "d9ec9c13-f3e6-4b2e-a34f-e3f45b21206f",
6    "back": "fb4ad373-45a6-4a64-bb3c-43e0c59d1ab5"
7  }
8}

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

2

Retrieve the document image

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

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

Example:

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
$POST https://api.idmelabs.com/api/public/v3/documents/refresh/{DOCUMENT_TOKEN}?token={API_TOKEN}

Example response:

Example
1{ "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
$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

ID.me 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
Minimum100
Maximum1000

Rate limiting

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