> 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. # Telecom > Verify phone possession and identity using the Services API telecom endpoints. 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 IDMe 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. > **Warning** > > If a webhook is configured for your organization, IDMe will return the initial telecom verification result to the Telecom Verification Result Webhook. The webhook POST body is the same format as the `GET /api/v2/telecom/:transaction_id` response. > **Info** > > Watch the [telecom endpoints demo](https://youtu.be/5Byhpr2XDGQ) and the [telecom mocks and errors demo](https://youtu.be/zzy6OR169b0) for walkthroughs. --- ## 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](#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 | Parameter | Required or Optional | Data Type | Description | | ----------------- | -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ | | `phone` | Required | string | The phone number to receive the OTP via SMS. Must be a 10-digit valid number that can receive SMS messages | | `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`** ```bash Example 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 **`200 OK`** ```json 200 OK { "transaction_id": "afae99c6-f5c0-4c05-a5f6-f9578db460fa", "verification_id": "4b4e00be-9333-409c-b76e-fe9b20c17be4", "product": "telecom.possession_send", "status": { "code": 210, "message": "Transaction pending review", "created": "2023-03-22T05:57:33.493Z", "updated": "2023-03-22T05:57:33.511Z" } } ``` ### Error responses | HTTP Status | Code | Message | | ----------- | ------ | ------------------------------------------------- | | `422` | `3101` | Transaction parameter phone is missing or invalid | | `422` | `3100` | Transaction parameter callback_url is invalid | --- ## 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](#possession---sms) for details. ### Parameters | Parameter | Required or Optional | Data Type | Description | | ---------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------- | | `code` | Required | string | The six-digit OTP received by the user. In sandbox, code `123123` will trigger a success response | | `transaction_id` | Required | string | The `transaction_id` from the Possession - SMS Send request | | `callback_url` | Optional | string | The URL to receive the callback for the transaction | ### Example request **`Example`** ```bash Example 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 **`200 OK`** ```json 200 OK { "transaction_id": "39f7e607-5140-474a-a205-433e0c1e3b90", "verification_id": "3b02773e-121c-455f-b6f5-d8cf7e79093c", "product": "telecom.possession_send", "status": { "code": 200, "message": "Transaction successfully completed", "created": "2023-05-29T21:08:42.417Z", "updated": "2023-05-29T21:08:42.451Z" }, "result": { "phone": "8885551234" } } ``` ### Error responses | HTTP Status | Code | Message | | ----------- | ------ | ----------------------------------------------------------- | | `422` | `3102` | Transaction parameter code is missing or invalid | | `422` | `3103` | Transaction parameter code is expired | | `422` | `3104` | Transaction retry limit exceeded | | `422` | `3105` | Transaction is not associated with a valid possession check | | `422` | `3100` | Transaction parameter callback_url is invalid | --- ## 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 | Parameter | Required or Optional | Data Type | Description | | ----------------- | -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ | | `phone` | Required | string | The phone number to run an identity check against. Must be a 10-digit valid phone number | | `birth_date` | Required | string | The user's date of birth in ISO 8601 format: `YYYY-MM-DD` | | `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`** ```bash Example 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 **`200 OK`** ```json 200 OK { "transaction_id": "36967ac5-ecb1-4418-8ad3-e6ca5bc32c6b", "verification_id": "e469c856-7f8e-4aba-8fb4-230bcfea7cf8", "product": "telecom.identity", "status": { "code": 210, "message": "Transaction pending review", "created": "2023-04-04T14:55:39.405Z", "updated": "2023-04-04T14:55:39.405Z" } } ``` ### 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. **`Example`** ```json Example { "transaction_id": "30a04f19-1bbe-4ac1-914f-2a9fefe86cbb", "product": "telecom.identity", "result": { "errors": [ { "code": 1014, "message": "Could not find the user", "additional_info": "birth_date does not match data on file." } ] } } ``` 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 | HTTP Status | Code | Message | | ----------- | ------ | ------------------------------------------------------------ | | `422` | `3108` | Transaction parameter birth_date is not in YYYY-MM-DD format | | `422` | `3101` | Transaction parameter phone is missing or invalid | | `422` | `3107` | Transaction parameter birth_date indicates user is a minor | | `422` | `3100` | Transaction parameter callback_url is invalid | --- ## Telecom verification status GET `/api/v2/telecom/:transaction_id` Returns the current status of a telecom transaction. ### Parameters | Parameter | Required or Optional | Data Type | Description | | ---------------- | -------------------- | --------- | ------------------------ | | `transaction_id` | Required | string | A valid `transaction_id` | ### Example request **`Example`** ```bash Example curl --location 'https://services.idmelabs.com/api/v2/telecom/40a9248e-77e2-4778-bbad-062ebf38edff' ``` ### Example response **`200 OK`** ```json 200 OK { "transaction_id": "40a9248e-77e2-4778-bbad-062ebf38edff", "verification_id": "14976a21-f03a-4399-bdc6-3e16de5394b3", "product": "telecom.possession_send", "status": { "code": 200, "message": "Transaction successfully completed", "created": "2023-05-27T22:34:04.100Z", "updated": "2023-05-27T22:34:04.126Z" } } ```