Overview | ID.me Developer

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

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.

Watch the authorization demo 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:

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

Example error response:

Example

1 {
2   "errors": [{
3     "code": 2200,
4     "message": "Referenced product is not active"
5   }]
6 }

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

1 "status": {
2   "code": 300,
3   "message": "Transaction unsuccessful",
4   "created": "2023-05-01T11:56:53.504-04:00",
5   "updated": "2023-05-01T11:56:53.563-04:00"
6 }

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

1 "result": {
2   "verified": false,
3   "errors": [{
4     "code": 2006,
5     "message": "The file size is too small. Uploaded files must be greater than 40KB and less than 16MB."
6   }]
7 }

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

Example

1 "result": {
2   "verified": false,
3   "errors": [{
4     "code": 1014,
5     "message": "Could not find the user",
6     "additional_info": "birth_date does not match data on file."
7   }]
8 }

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

$ curl --location 'https://services.idmelabs.com/health'

Returns 200 OK with no response body.