Request info about a phone number

post

https://rest-ww.telesign.com/v1/phoneid

Enter a phone number with country code to receive detailed information about carrier, location, and other details.

General requirements

Authentication: Basic (easiest to implement) or Digest
Encoding: Accepts only UTF-8 unicode characters as inputs.
Accepts: application/json
Responds with: application/json
Required headers: Content-Type - application/json
Rate limit: Default rate limits by product

Body Params

phone_number

string

required

The phone number you want to collect information about. Provide the entire phone number, including the country code, with no spaces or special characters.

account_lifecycle_event

string

Indicates what stage an end user is in when you make this request. Acceptable values for this parameter are:

create - For the creation of a new account.
sign-in - For when an end user signs in to their account.
transact - For when an end user completes a transaction within their account.
update - For when an update is performed, such as an update of account information.
delete - For when an account is deleted.

external_id

string

A customer-generated ID for this transaction. The response simply echoes the value provided for this parameter.

originating_ip

string

Your end user's IP address (do not send your own IP address). IPv4 and IPv6 are supported. For IPv4, the value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Internet Protocol. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled IP Version 6 Addressing Architecture.

addons

object

Indicates which identity attributes you want to use with this request and contains any other inputs for use with those identity attributes.

consent

object

A record of how and when you obtained consent to query this phone number. This is required for some add-ons.

Responses

Status Code	Associated Text String	Description
300	Transaction successfully completed	The system was able to obtain all of the requested data for Phone ID.
301	Transaction partially completed	The system was able to obtain some of the data for Phone ID, but not all of it.

Status Code	Associated Text String
10032	Request blocked due to this number appearing on a Telesign blocklist.
10033	Unverified phone_number requested for trial account.
11000	Invalid value for parameter phone_number
11001	Invalid country code for parameter phone_number
11003	Invalid value for parameter account_lifecycle_event
11005	Invalid value for parameter customer_id
11010	Invalid value for parameter originating_ip
11011	Invalid value for parameter reference_id
12000	Missing required parameter phone_number

Status Code	Associated Text String
10008	Invalid signature
10009	Invalid value for parameter message
10010	Invalid value for parameter originating_ip
10011	Invalid value for parameter reference_id
10012	This feature is not enabled for this CustomerID
10013	Invalid Request. CustomerID Account Not Found
10014	Invalid source IP address
10015	Invalid customer ID

Status Code	Associated Text String
10019	Rate Limit Exceeded
10020	PhoneId Standard exceeded transaction hard cap. Request denied.

402Payment Required. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response. Status CodeAssociated Text String10030Insufficient funds in prepaid wallet

404Not Found, the server has not found anything matching the Request-URI. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response. Status CodeAssociated Text String10017Customer ID / Reference ID not found

500Invalid Transaction, transaction not attempted.

503Service Unavailable, system unavailable, try again.