Telecom

The telecom endpoints support two types of verification:

• Phone Possession — establishes that the user has possession of a given phone number
• Identity — matches a phone number and birth date against carrier records to return the user’s current address

ID.me recommends performing a Possession Check on the phone number prior to calling the Identity endpoint.

All telecom 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 telecom verification at either the GET /api/v2/telecom/:transaction_id endpoint or the GET /api/v2/verification/:verification_id endpoint.

Possession - SMS

POST /api/v2/telecom/possession/sms/send

Sends a six-digit OTP to the provided phone number to establish possession. The SMS Send and SMS Confirm endpoints share the same transaction_id and together form a single transaction.

After sending, use the Possession Confirmation - SMS endpoint with the returned transaction_id to validate the code the user received.

Mocks

To simulate a failure, pass a phone number with area code 999. The last four digits of the phone number should be the error code you want to trigger. For example, to simulate error 3104 (max retries exceeded), pass the phone 9995553104.

To simulate success on the Confirm endpoint, pass any valid phone number that does not begin with 999 to the Send endpoint, then submit code 123123 to the Confirm endpoint.

Parameters

Example request

$
curl --location 'https://services.idmelabs.com/api/v2/telecom/possession/sms/send' \
>
--header 'Content-Type: application/json' \
>
--data '{
>
    "phone": "8888269018",
>
    "callback_url": "http://example.com/callback"
>
}'

Example response

1
{
2
  "transaction_id": "afae99c6-f5c0-4c05-a5f6-f9578db460fa",
3
  "verification_id": "4b4e00be-9333-409c-b76e-fe9b20c17be4",
4
  "product": "telecom.possession_send",
5
  "status": {
6
    "code": 210,
7
    "message": "Transaction pending review",
8
    "created": "2023-03-22T05:57:33.493Z",
9
    "updated": "2023-03-22T05:57:33.511Z"
10
  }
11
}

Error responses

Possession confirmation - SMS

POST /api/v2/telecom/possession/sms/confirm

Validates the OTP submitted by the user. Requires a transaction_id from a prior Possession - SMS Send request. By default, users have 5 attempts to provide the correct code before the transaction is marked as failed.

The SMS Send and SMS Confirm endpoints share the same transaction_id and together form a single transaction.

Mocks

To simulate success, submit code 123123. To simulate multiple failures, submit any code other than 123123. Failure behavior on the Send endpoint is controlled by the phone number’s area code — see Possession - SMS for details.

Parameters

Example request

$
curl --location 'https://services.idmelabs.com/api/v2/telecom/possession/sms/confirm' \
>
--header 'Content-Type: application/json' \
>
--data '{
>
    "transaction_id": "343ecd11-a3f3-4e92-93ea-ec8e333e9368",
>
    "code": "123123"
>
}'

Example response

1
{
2
  "transaction_id": "39f7e607-5140-474a-a205-433e0c1e3b90",
3
  "verification_id": "3b02773e-121c-455f-b6f5-d8cf7e79093c",
4
  "product": "telecom.possession_send",
5
  "status": {
6
    "code": 200,
7
    "message": "Transaction successfully completed",
8
    "created": "2023-05-29T21:08:42.417Z",
9
    "updated": "2023-05-29T21:08:42.451Z"
10
  },
11
  "result": {
12
    "phone": "8885551234"
13
  }
14
}

Error responses

Identity

POST /api/v2/telecom/identity

Matches a phone number and birth date against carrier records. Returns the user’s current address if a match is found. Both phone and birth_date are required.

Mocks

Pass a phone number with area code 888 to trigger a success mock response. Pass a phone number with area code 999 to trigger a failure mock response.

Parameters

Example request

$
curl --location 'https://services.idmelabs.com/api/v2/telecom/identity' \
>
--header 'Content-Type: application/json' \
>
--data '{
>
    "phone": "8885551234",
>
    "birth_date": "1968-05-27",
>
    "verification_id": "e469c856-7f8e-4aba-8fb4-230bcfea7cf8"
>
}'

Example response

1
{
2
  "transaction_id": "36967ac5-ecb1-4418-8ad3-e6ca5bc32c6b",
3
  "verification_id": "e469c856-7f8e-4aba-8fb4-230bcfea7cf8",
4
  "product": "telecom.identity",
5
  "status": {
6
    "code": 210,
7
    "message": "Transaction pending review",
8
    "created": "2023-04-04T14:55:39.405Z",
9
    "updated": "2023-04-04T14:55:39.405Z"
10
  }
11
}

Failed identity verification response

A failed verification returns HTTP 200 and includes an errors array in the result. An additional_info field may be present with further detail.

1
{
2
  "transaction_id": "30a04f19-1bbe-4ac1-914f-2a9fefe86cbb",
3
  "product": "telecom.identity",
4
  "result": {
5
    "errors": [
6
      {
7
        "code": 1014,
8
        "message": "Could not find the user",
9
        "additional_info": "birth_date does not match data on file."
10
      }
11
    ]
12
  }
13
}

Possible additional_info values for telecom identity:

• Phone cannot be reached.
• Mobile data for phone number is inaccessible.
• No data available for mobile subscriber.
• Carrier information received does not match the information on file.
• Cannot reach third party data provider.
• Invalid phone number, review number and retry.
• birth_date does not match data on file.
• ssn does not match data on file.

Error responses

Telecom verification status

GET /api/v2/telecom/:transaction_id

Returns the current status of a telecom transaction.

Parameters

Example request

$
curl --location 'https://services.idmelabs.com/api/v2/telecom/40a9248e-77e2-4778-bbad-062ebf38edff'

Example response

1
{
2
  "transaction_id": "40a9248e-77e2-4778-bbad-062ebf38edff",
3
  "verification_id": "14976a21-f03a-4399-bdc6-3e16de5394b3",
4
  "product": "telecom.possession_send",
5
  "status": {
6
    "code": 200,
7
    "message": "Transaction successfully completed",
8
    "created": "2023-05-27T22:34:04.100Z",
9
    "updated": "2023-05-27T22:34:04.126Z"
10
  }
11
}