Documents | ID.me Developer

ID.me verifies the following document types:

Driver’s License / State ID
Passport
Passcard

All document endpoints require at least a front_image submitted as form-data. Driver’s License and Passcard endpoints also require a back_image. Images must be in image/jpeg or image/png format, between 40KB and 16MB in size.

All document endpoints accept an optional verification_id in the request body. If one is not provided, a new verification will be created and returned in the response.

You can check the status of a document verification at either the GET /api/v2/document/:transaction_id endpoint or the GET /api/v2/verification/:verification_id endpoint.

If a webhook is configured for your organization, ID.me will return the initial document verification result to the Document Verification Result Webhook. The webhook POST body is the same format as the GET /api/v2/document/:transaction_id response.

Watch the Documents API and mock errors demo for a walkthrough.

Driver’s License / State ID

POST /api/v2/document/license/verify

Verifies a driver’s license or state ID by processing front and back images of the document.

Parameters

Parameter	Required or Optional	Data Type	Description
`front_image`	Required	`image/jpeg` or `image/png`	Front image of the document. Must be between 40KB and 16MB
`back_image`	Required	`image/jpeg` or `image/png`	Back image of the document. Must be between 40KB and 16MB
`callback_url`	Optional	string	The URL to receive the callback for the transaction
`verification_id`	Optional	string	The ID of the verification to associate with this transaction. If not provided, a new verification will be created
`metadata`	Optional	application/json	Custom metadata for the transaction. Can be any valid JSON value up to 500 characters

Example request

Example

$ curl --location 'https://services.idmelabs.com/api/v2/document/license/verify' \
> --form 'front_image=@"license/success.jpg"' \
> --form 'back_image=@"license/success_back.jpg"'

Example response

200 OK

1 {
2   "transaction_id": "6ba2c24b-efad-4ec2-919a-d901f872f35e",
3   "verification_id": "a1d32b35-51ad-41f1-8ef9-00d59e86fcf3",
4   "product": "document.license.verify",
5   "status": {
6     "code": 210,
7     "message": "Transaction pending review",
8     "created": "2023-03-20T19:35:04.055Z",
9     "updated": "2023-03-20T19:35:04.055Z"
10   }
11 }

Error responses

HTTP Status	Code	Message
`422`	`3101`	Transaction parameter front_image is missing or invalid
`422`	`3100`	Transaction parameter callback_url is invalid

Passport

POST /api/v2/document/passport/verify

Verifies a passport by processing a front image of the document. Only a front_image is required.

Parameters

Parameter	Required or Optional	Data Type	Description
`front_image`	Required	`image/jpeg` or `image/png`	Front image of the document. Must be between 40KB and 16MB
`callback_url`	Optional	string	The URL to receive the callback for the transaction
`verification_id`	Optional	string	The ID of the verification to associate with this transaction. If not provided, a new verification will be created
`metadata`	Optional	application/json	Custom metadata for the transaction. Can be any valid JSON value up to 500 characters

Example request

Example

$ curl --location 'https://services.idmelabs.com/api/v2/document/passport/verify' \
> --form 'front_image=@"passport/success.jpg"'

Example response

200 OK

1 {
2   "transaction_id": "3aeaa8d2-4d8d-44fb-a289-a8eae3aa6000",
3   "verification_id": "7c94e937-3ee6-4b40-be48-ecbfd0630f84",
4   "product": "document.passport.verify",
5   "status": {
6     "code": 210,
7     "message": "Transaction pending review",
8     "created": "2023-03-20T19:32:59.617Z",
9     "updated": "2023-03-20T19:32:59.617Z"
10   }
11 }

Error responses

HTTP Status	Code	Message
`422`	`3101`	Transaction parameter front_image is missing or invalid
`422`	`3100`	Transaction parameter callback_url is invalid

Passcard

POST /api/v2/document/passcard/verify

Verifies a passcard by processing front and back images of the document.

Parameters

Parameter	Required or Optional	Data Type	Description
`front_image`	Required	`image/jpeg` or `image/png`	Front image of the document. Must be between 40KB and 16MB
`back_image`	Required	`image/jpeg` or `image/png`	Back image of the document. Must be between 40KB and 16MB
`callback_url`	Optional	string	The URL to receive the callback for the transaction
`verification_id`	Optional	string	The ID of the verification to associate with this transaction. If not provided, a new verification will be created
`metadata`	Optional	application/json	Custom metadata for the transaction. Can be any valid JSON value up to 500 characters

Example request

Example

$ curl --location 'https://services.idmelabs.com/api/v2/document/passcard/verify' \
> --form 'front_image=@"passcard/success.jpg"' \
> --form 'back_image=@"passcard/success_back.jpg"'

Example response

200 OK

1 {
2   "transaction_id": "0d1a9a80-581c-4963-913c-583d33aea016",
3   "verification_id": "eb3432a7-6c14-4cd5-94e6-0e980667bbbe",
4   "product": "document.passcard.verify",
5   "status": {
6     "code": 210,
7     "message": "Transaction pending review",
8     "created": "2023-03-20T23:01:02.159Z",
9     "updated": "2023-03-20T23:01:02.159Z"
10   }
11 }

Error responses

HTTP Status	Code	Message
`422`	`3101`	Transaction parameter front_image is missing or invalid
`422`	`3100`	Transaction parameter callback_url is invalid

Document verification status

GET /api/v2/document/:transaction_id

Returns the current status of a document verification transaction.

Parameters

Parameter	Required or Optional	Data Type	Description
`transaction_id`	Required	string	A valid `transaction_id`

Document errors

When a document verification fails, the result will include one of the following error codes:

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

Example request

Example

$ curl --location 'https://services.idmelabs.com/api/v2/document/c9298cc5-9917-4b88-850d-991df3864afe'

Example response

200 OK

1 {
2   "transaction_id": "c9298cc5-9917-4b88-850d-991df3864afe",
3   "verification_id": "e469c856-7f8e-4aba-8fb4-230bcfea7cf8",
4   "product": "document.license.verify",
5   "status": {
6     "code": 200,
7     "message": "Transaction successfully completed",
8     "created": "2023-04-04T21:15:52.171Z",
9     "updated": "2023-04-04T21:15:52.171Z"
10   }
11 }