post

/v1/phoneid/{complete_phone_number}

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

General Requirements

Request Requirements

  • Authentication: Basic (easiest to implement) or Digest
  • Endpoint: https://rest-ww.telesign.com/v1/phoneid/{complete_phone_number}
    The phone number must include the country code.
  • Encoding: Accepts only UTF-8 unicode characters as inputs
  • MIME Type: application/json
  • Required Headers: Content-Type

Response Details

  • MIME Type: application/json

Request Parameters

1 Path Parameter

Request Body

Schema
object
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.
1 validation
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 doucment 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 Arcitecture.

1 validation
addons
object

Indicates which add-ons you want to use with this request, and contains any other inputs for use with those add-ons.

consent
object

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

Responses

Your request was fulfilled and resulted in a new resource being created. 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 Code Associated Text String Description
300 Transaction successfully completed The system was able to obtain all of the requested data for PhoneID.
301 Transaction partially completed The system was able to obtain some of the data for PhoneID, but not all of it.
Schema
object
reference_id
string

A 32-digit hex value used to identify the web service requests. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.

phone_type
object

An object containing details about the phone type.

blocklisting
object

Contains details about whether the number was blocked and who requested the block. To see this information, speak with our Customer Support Team to have blocklisting information enabled.

status
object

Contains details about the status of your request.

numbering
object

An object containing details about the numbering attributes of the specified phone number.

location
object

An object containing geographical location information associated with the phone number.

carrier
object

Contains sub-properties related to the carrier for this number.

call_forward_detection
object

Contains call forwarding status details for this phone number. Only present if you included the flag for the Call Forward Detection add-on in your request and TeleSign has enabled this add-on for your account.

contact
object

Contains contact information for this phone number. You will only see this in your response if you used the associated add-on (Contact or Contact Plus) and TeleSign has enabled this add-on for your account. See Contact Add-on or Contact Plus Add-on for more details.

contact_match
object

Contains contact match information for this phone number. Only present if you included the flag for the Contact Match add-on in your request and TeleSign has enabled this add-on for your account.

contact_plus
object

Contains contact information for this phone number. You will only see this in your response if you used the associated add-on (Contact or Contact Plus) and TeleSign has enabled this add-on for your account. See Contact Add-on or Contact Plus Add-on for more details.

number_deactivation
object

You will only see this in your response if you used the number_deactivation add-on.

subscriber_status
object

You will only see this if you used the subscriber_status add-on.

porting_history
object

Contains porting history information for this phone number. Only present if you included the flag for the Porting History add-on in your request and TeleSign has enabled this add-on for your account.

porting_status
object

Contains porting status information for this phone number. Only present if you included the flag for the Porting Status add-on in your request and TeleSign has enabled this add-on for your account.

sim_swap
object

Contains SIM swap information for this phone number. Only present if you included the flag for the SIM Swap add-on in your request and TeleSign has enabled this add-on for your account.

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
complete_phone_number
$$.env
1 variable not set
host