openapi: 3.2.0
info:
title: Telesign Intelligence API
version: '1.0'
contact:
name: TeleSign Customer Support Team
email: support@telesign.com
description: 'Operations tagged Intelligence across 2 of this provider''s published API definitions: telesign-detect-api-openapi.json, telesign-intelligence-cloud-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://rest-ww.telesign.com/v1
- url: detect.telesign.com
security:
- Basic: []
- Digest: []
tags:
- name: Intelligence
paths:
/score/{complete_phone_number}:
parameters:
- schema:
type: string
name: complete_phone_number
in: path
required: true
post:
summary: Submit a phone number to evaluate
operationId: submitPhoneNumberForIntelligence
responses:
'200':
description: "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 code property in the response object and use that, rather than the HTTP status code. Individual packages within the response may have their own status codes as well.\n \n| Status Code | Associated Text String | Description |\n|-------------|------------------------|--------|\n| 300 | Transaction successfully completed | The system was able to obtain all of the requested data. |\n| 301 | Transaction partially completed | The system was able to obtain some of the data, but not all of it. |"
content:
application/json:
schema:
$ref: '#/components/schemas/postScoreResponse'
examples:
Success:
value:
reference_id: CFMJ6FTL09O22UE1KC5NBD7ZMWKTMJB8
external_id: CustomExternalID7349
status:
code: 300
description: Transaction successfully completed
updated_on: '2024-10-06T21:25:03.420503Z'
location:
city: Los Angeles
county: Los Angeles County
state: CA
zip: '90066'
country:
iso2: US
iso3: USA
name: United States
time_zone:
name: America/Los_Angeles
utc_offset_max: '-8'
utc_offset_min: '-8'
coordinates:
latitude: 33.99791
longitude: -118.42302
metro_code: '4480'
numbering:
original:
phone_number: '1234567890'
complete_phone_number: '11234567890'
country_code: '1'
cleansing:
call:
cleansed_code: 100
country_code: '1'
max_length: 10
min_length: 10
phone_number: '1234567890'
sms:
cleansed_code: 100
country_code: '1'
max_length: 10
min_length: 10
phone_number: '1234567890'
phone_type:
code: '1'
override_reason: Non SMS-enabled Phone Number
description: FIXED_LINE
override_reason_id: 11
blocklisting:
block_code: 0
block_description: Not blocked
blocked: true
carrier:
carrier_id: 309
name: AT&T Wireless
risk:
level: high
recommendation: block
score: 959
risk_insights:
status: 800
category:
- 10002
a2p:
- 20001
- 20101
- 21002
p2p:
- 30201
number_type:
- 40005
- 40011
ip:
- 50001
- 50004
email:
- 60003
- 60006
'400':
description: "Bad request, the request could not be understood by the server due to malformed syntax. 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. \n\n | Status Code | Associated Text String | \n |-------------|------------------------|\n | 10032 | Request blocked due to this number appearing on a TeleSign blocklist. | \n | 10033 | Unverified phone_number requested for trial account. | \n | 11000 | Invalid value for parameter phone_number | \n | 11001 | Invalid country code for parameter phone_number | \n | 11002 | Invalid value for parameter account_id |\n | 11003 | Invalid value for parameter account_lifecycle_event | \n | 11005 | Invalid value for parameter customer_id | \n | 11006 | Invalid value for parameter device_id |\n | 11007 | Invalid value for email_address |\n | 11010 | Invalid value for parameter originating_ip | \n | 11011 | Invalid value for parameter reference_id | \n | 12000 | Missing required parameter phone_number |\n | 12003 | Missing required parameter account_lifecycle_event |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Invalid Request:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10032
description: Request blocked due to this number appearing on a TeleSign blacklist.
'401':
description: "Unauthorized, the request requires user authentication. 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. \n\n | Status Code | Associated Text String | \n |-------------|------------------------|\n | 10008 | Invalid signature | \n | 10009 | Invalid value for parameter message | \n | 10010 | Invalid value for parameter originating_ip | \n | 10011 | Invalid value for parameter reference_id | \n | 10012 | This feature is not enabled for this CustomerID |\n | 10013 | Invalid Request. CustomerID Account Not Found |\n | 10014 | Invalid source IP address |\n | 10015 | Invalid customer ID |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Unauthorized:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10008
description: Invalid signature
'402':
description: "Payment 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.\n\n| Status Code | Associated Text String | \n|-------------|------------------------|\n| 10030 | Insufficient funds in prepaid wallet |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Payment Required:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10030
description: Insufficient funds in prepaid wallet
'404':
description: "Not 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.\n\n| Status Code | Associated Text String | \n|-------------|------------------------|\n| 10017 | Customer ID / Reference ID not found |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Not Found:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10017
description: Customer ID / Reference ID not found
'429':
description: "Too Many Requests, the user sent too many requests in a given amount of time. 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.\n\n| Status Code | Associated Text String | \n|-------------|------------------------|\n| 10019 | Rate Limit Exceeded |\n| 10020 | PhoneId Standard exceeded transaction hard cap. Request denied. |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Too Many Requests:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10019
description: Rate Limit Exceeded
'500':
description: Invalid Transaction, transaction not attempted.
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Invalid Transaction:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: -90001
description: Transaction not attempted
'503':
description: Service Unavailable, system unavailable, try again.
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
System Unavailable:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: -10000
description: System unavailable. Please try again later.
description: '> đ NOTE:
>
> This page is for the on-prem version of Intelligence which is deprecated. Please complete your migration to the Intelligence Cloud API. This migration is mandatory.
Obtain a risk recommendation for this phone number, as well as other relevant information.
## General requirements
* **Authentication:** Basic (easiest to implement) or Digest
* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.
* **Accepts:** `application/x-www-form-urlencoded`
* **Responds with:** `application/json`
* **Required headers:** `Content-Type - application/x-www-form-urlencoded`
* **Rate limit:** Default rate limits by product'
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
account_lifecycle_event:
type: string
enum:
- create
- sign-in
- transact
- update
- delete
description: 'The attempted action associated with this phone number for which you want to evaluate its risk. 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 or similar.
* delete - For when an account is deleted.'
external_id:
type: string
example: CustomExternalID7349
description: A customer-generated ID for this transaction. The response simply echoes the value provided for this parameter.
originating_ip:
type: string
description: 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](https://tools.ietf.org/html/rfc791). For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled [IP Version 6 Addressing Architecture](https://tools.ietf.org/html/rfc4291#section-2.2).
device_id:
type: string
description: Your end user's device ID. This value is case sensitive.
account_id:
type: string
description: Your end user's account ID. This value is case sensitive.
email_address:
type: string
description: Your end user's email address. This value is case sensitive.
required:
- account_lifecycle_event
description: ''
tags:
- Intelligence
security:
- Basic: []
deprecated: true
servers:
- url: https://rest-ww.telesign.com/v1
/intelligence/phone:
parameters: []
post:
summary: Intelligence Cloud - Submit a phone number to evaluate
operationId: submitPhoneNumberForIntelligenceCloud
responses:
'200':
description: "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 code property in the response object and use that, rather than the HTTP status code. Individual packages within the response may have their own status codes as well.\n \n| Status Code | Associated Text String | Description |\n|-------------|------------------------|--------|\n| 300 | Transaction successfully completed | The system was able to obtain all of the requested data. |\n| 301 | Transaction partially completed | The system was able to obtain some of the data, but not all of it. |"
content:
application/json:
schema:
$ref: '#/components/schemas/postScoreResponse_2'
examples:
Success:
value:
reference_id: CFMJ6FTL09O22UE1KC5NBD7ZMWKTMJB8
external_id: CustomExternalID7349
status:
code: 300
description: Transaction successfully completed
updated_on: '2024-10-06T21:25:03.420503Z'
location:
city: Los Angeles
county: Los Angeles County
state: CA
zip: '90066'
country:
iso2: US
iso3: USA
name: United States
time_zone:
name: America/Los_Angeles
utc_offset_max: '-8'
utc_offset_min: '-8'
coordinates:
latitude: 33.99791
longitude: -118.42302
metro_code: '4480'
numbering:
original:
phone_number: '1234567890'
complete_phone_number: '11234567890'
country_code: '1'
cleansing:
call:
cleansed_code: 100
country_code: '1'
max_length: 10
min_length: 10
phone_number: '1234567890'
sms:
cleansed_code: 100
country_code: '1'
max_length: 10
min_length: 10
phone_number: '1234567890'
phone_type:
code: '1'
override_reason: Non SMS-enabled Phone Number
description: FIXED_LINE
override_reason_id: 11
blocklisting:
block_code: 0
block_description: Not blocked
blocked: true
carrier:
carrier_id: 309
name: AT&T Wireless
risk:
level: high
recommendation: block
score: 959
risk_insights:
status: 800
category:
- 10002
a2p:
- 20001
- 20101
- 21002
p2p:
- 30201
number_type:
- 40005
- 40011
ip:
- 50001
- 50004
email:
- 60003
- 60006
'400':
description: "Bad request, the request could not be understood by the server due to malformed syntax. 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. \n\n | Status Code | Associated Text String | \n |-------------|------------------------|\n | 10032 | Request blocked due to this number appearing on a TeleSign blocklist. | \n | 10033 | Unverified phone_number requested for trial account. | \n | 10041 | Blocked due to legal compliance | \n | 11000 | Invalid value for parameter phone_number | \n | 11001 | Invalid country code for parameter phone_number | \n | 11002 | Invalid value for parameter account_id |\n | 11003 | Invalid value for parameter account_lifecycle_event | \n | 11005 | Invalid value for parameter customer_id | \n | 11006 | Invalid value for parameter device_id |\n | 11007 | Invalid value for email_address |\n | 11010 | Invalid value for parameter originating_ip | \n | 11011 | Invalid value for parameter reference_id | \n | 12000 | Missing required parameter phone_number |\n | 12003 | Missing required parameter account_lifecycle_event |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Invalid Request:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10032
description: Request blocked due to this number appearing on a TeleSign blacklist.
'401':
description: "Unauthorized, the request requires user authentication. 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. \n\n | Status Code | Associated Text String | \n |-------------|------------------------|\n | 10008 | Invalid signature | \n | 10009 | Invalid value for parameter message | \n | 10010 | Invalid value for parameter originating_ip | \n | 10011 | Invalid value for parameter reference_id | \n | 10012 | This feature is not enabled for this CustomerID |\n | 10013 | Invalid Request. CustomerID Account Not Found |\n | 10014 | Invalid source IP address |\n | 10015 | Invalid customer ID |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Unauthorized:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10008
description: Invalid signature
'402':
description: "Payment 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.\n\n| Status Code | Associated Text String | \n|-------------|------------------------|\n| 10030 | Insufficient funds in prepaid wallet |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Payment Required:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10030
description: Insufficient funds in prepaid wallet
'404':
description: "Not 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.\n\n| Status Code | Associated Text String | \n|-------------|------------------------|\n| 10017 | Customer ID / Reference ID not found |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Not Found:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10017
description: Customer ID / Reference ID not found
'429':
description: "Too Many Requests, the user sent too many requests in a given amount of time. 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.\n\n| Status Code | Associated Text String | \n|-------------|------------------------|\n| 10019 | Rate Limit Exceeded |\n| 10020 | PhoneId Standard exceeded transaction hard cap. Request denied. |\n"
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Too Many Requests:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: 10019
description: Rate Limit Exceeded
'500':
description: Invalid Transaction, transaction not attempted.
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
Invalid Transaction:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: -90001
description: Transaction not attempted
'503':
description: Service Unavailable, system unavailable, try again.
content:
application/json:
schema:
$ref: '#/components/schemas/errorObject'
examples:
System Unavailable:
value:
reference_id: 0123456789ABCDEF0123456789ABCDEF
external_id: CustomExternalID7349
status:
updated_on: '2024-02-01T00:33:34.860418Z'
code: -10000
description: System unavailable. Please try again later.
description: 'Obtain a risk recommendation for this phone number, as well as other relevant information using Telesign Cloud API.
Migration from Intelligence to the Intelligence Cloud API is mandatory.
## General requirements
* **Authentication:** Basic (easiest to implement) or Digest
* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.
* **Accepts:** `application/x-www-form-urlencoded`
* **Responds with:** `application/json`
* **Required headers:** `Content-Type - application/x-www-form-urlencoded`
* **Rate limit:** Default rate limits by product'
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
phone_number:
type: string
account_lifecycle_event:
type: string
enum:
- create
- sign-in
- transact
- update
- delete
description: 'The attempted action associated with this phone number for which you want to evaluate its risk. 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 or similar.
* delete - For when an account is deleted.'
account_id:
type: string
description: Your end user's account ID. This value is case sensitive.
device_id:
type: string
description: Your end user's device ID. This value is case sensitive.
email_address:
type: string
description: Your end user's email address. This value is case sensitive.
external_id:
type: string
example: CustomExternalID7349
description: Any ID passed from you that can uniquely identify this transaction in your system. The response simply echoes the value provided for this parameter.
originating_ip:
type: string
description: 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](https://tools.ietf.org/html/rfc791). For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled [IP Version 6 Addressing Architecture](https://tools.ietf.org/html/rfc4291#section-2.2).
required:
- phone_number
- account_lifecycle_event
description: ''
tags:
- Intelligence
security:
- Basic: []
servers:
- url: detect.telesign.com
components:
schemas:
Risk:
title: Risk
type: object
description: Contains properties related to the risk recommendation for the specified phone number.
properties:
level:
type: string
example: high
description: The severity of the risk. [Risk Recommendation Scales](/enterprise/docs/intelligence-get-started#risk-recommendation-scales) provides a table.
recommendation:
type: string
example: block
enum:
- allow
- flag
- block
description: The action that Telesign recommends that you take based on the risk recommendation.
score:
type: integer
example: 959
description: A measure of the transaction risk involved with conducting an online business transaction at the current time for this phone number. The scale ranges from zero to 1000, with a higher value indicating a higher risk.
Carrier:
title: Carrier
type: object
description: Contains details about the company that provides telecommunications services for this phone number. Behavior of this property, including information returned for ported phone numbers, can vary depending on the country of the phone number. See [How does carrier data vary by country?](https://support.telesign.com/s/article/How-does-carrier-data-vary-by-country) for more details.
properties:
carrier_id:
type: integer
description: An ID specifying this carrier. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response.
example: 309
name:
type: string
description: The name of this carrier.
example: AT&T Wireless
Location:
title: Location
type: object
description: Contains geographical location information associated with the rate center of the phone number when the device was activated. Null is returned when data for a field isn't available for a specific market or country.
properties:
city:
type: string
example: Odessa
description: The city associated with the rate center of the phone number when the device was activated.
county:
type: string
example: Ector
description: The county (or parish) associated with the rate center of the phone number when the device was activated (U.S. only).
state:
type: string
description: The two-letter [state abbreviation code](http://pe.usps.com/text/pub28/28apb.htm) of the state (province, district, or territory) associated with the rate center of the phone number when the device was activated (North America only).
example: TX
zip:
type: string
example: '79758'
description: The five-digit United States Postal Service [ZIP Code](https://www.usps.com/nationalpremieraccounts/findzipcodes.htm) associated with the rate center of the phone number when the device was activated (U.S. only).
country:
type: object
description: Contains properties related to the country associated with the rate center of the phone number when the device was activated.
properties:
iso2:
type: string
example: US
description: The ISO 3166-1 2-letter [country code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the rate center of the phone number when the device was activated.
iso3:
type: string
example: USA
description: ' The ISO 3166-1 3-letter country code associated with the rate center of the phone number when the device was activated.'
name:
type: string
example: United States
description: The [country name](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the rate center of the phone number when the device was activated.
time_zone:
type: object
description: Contains properties related to the time zone associated with the rate center of the phone number when the device was activated. For maximum and minimum UTC offsets, they are specified in units of hours, and range from -12 to +14. For positive numbers, the plus sign (+) may not be returned. Additional offsets due to Daylight Savings Time or Summer Time are not considered. For example, Russia, which spans 11 time zones, has a minimum UTC offset of +2, and a maximum of +12.
properties:
name:
type: string
example: America/Chicago
description: The time zone associated with the rate center of the phone number when the device was activated (U.S. only).
utc_offset_max:
type: string
example: '-6'
description: ' For international phone numbers, this parameter returns the maximum UTC offset for the country associated with the rate center of the phone number when the device was activated. For U.S. phone numbers, this parameter returns the same result as utc_offset_min.'
utc_offset_min:
type: string
example: '-6'
description: 'For international phone numbers, this parameter returns the minimum UTC offset for the country associated with the rate center of the phone number when the device was activated. For U.S. phone numbers, this parameter returns the UTC offset associated with the rate center of the phone number when the device was activated. '
coordinates:
type: object
description: Contains properties with details about the geographical coordinates of the location where the phone number is registered.
properties:
latitude:
type: number
description: Latitude specifies the North-South position of a point on the Earthâs surface. It is an angular measurement that ranges from 0° at the Equator, to 90° at the North Pole (and -90° at the South Pole). It is returned here as a value indicating the number of degrees of latitude of the location associated with the phone number, expressed in seven decimal digits, with five decimal places.
example: 31.8466
format: float
longitude:
type: number
example: -102.36778
description: Longitude specifies the East-West position of a point on the Earthâs surface. It is an angle measured East or West from the [prime meridian](https://en.wikipedia.org/wiki/Prime_meridian) âranging from 0° at the prime meridian, to +180° Eastward and -180° Westward. It is returned here as a value indicating the number of degrees of longitude of the location associated with the phone number, expressed in eight decimal digits, with five decimal places.
format: float
metro_code:
type: string
example: '36220'
description: A 4-digit string indicating the Primary Metropolitan Statistical Area (PMSA) code for the location associated with the rate center of the phone number when the device was activated (U.S. only). PMSA Codes are governed by the [US Census Bureau](http://www.census.gov/). This information is useful for large metropolitan areas that comprise several smaller cities. For example, the PMSA for Long Beach, California is Los Angeles County, which gives Long Beach the PMSA Code 4480.
Numbering:
title: Numbering
type: object
description: Contains properties related to the numbering attributes of the specified phone number.
properties:
original:
type: object
description: Contains details about the original phone number included in the request.
properties:
phone_number:
type: string
description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
example: '1234567890'
complete_phone_number:
type: string
description: The base phone number prefixed with the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
example: '11234567890'
country_code:
type: string
description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for the United Kingdom is `44`.
example: '1'
cleansing:
type: object
description: Contains details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.
properties:
call:
type: object
description: Contains cleansing details for the phone number if it is enabled to receive voice calls.
properties:
cleansed_code:
type: integer
description: One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.
example: 100
country_code:
type: string
description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.
example: '1'
max_length:
type: integer
description: The maximum number of digits allowed for phone numbers with this country dialing code.
example: 10
min_length:
type: integer
description: The minimum number of digits allowed for phone numbers with this country dialing code.
example: 10
phone_number:
type: string
description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
example: '1234567890'
sms:
type: object
description: Contains cleansing details for the phone number if it is enabled to receive SMS.
properties:
cleansed_code:
type: integer
description: One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.
example: 100
country_code:
type: string
description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.
example: '1'
max_length:
type: integer
description: The maximum number of digits allowed for phone numbers with this country dialing code.
example: 10
min_length:
type: integer
description: The minimum number of digits allowed for phone numbers with this country dialing code.
example: 10
phone_number:
type: string
description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
example: '1234567890'
RiskInsights:
title: RiskInsights
type: object
description: "Contains reason code properties with additional info related to the risk recommendation.\n
*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of these reason codes."
properties:
status:
type: integer
description: "The processing status of the risk insights package for this request.\n\nPossible values are:\n\n| Value | Meaning |\n|-------|---------|\n| 800 | **Success.**
All fields successfully returned and available for use. | \n| 801 | **Partial Success.**
No value available for category, but other data is available. | \n| 803 | **Error.**
An error occurred; no data returned in this response. | \n\n"
enum:
- 800
- 801
- 803
example: 800
category:
type: array
description: "Reason codes related to the category of the phone number.\n
*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned."
items:
type: integer
example: 10002
a2p:
type: array
description: "Reason codes specific to application-to-person communication (A2P). These are automated communications sent to a human, like verification codes, appointment reminders, etc.\n
*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned."
items:
type: integer
example: 20001
p2p:
type: array
description: "Reason codes specific to person-to-person communication (P2P). This is two-way communication between two humans, like one friend texting another.\n
*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned."
items:
type: integer
example: 30201
number_type:
type: array
description: "Reason codes related to the phone numberâs type.\n
*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned."
items:
type: integer
example: 40005
ip:
type: array
description: "Reason codes related to activity of the IP you provided for this phone number.\n
*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned."
items:
type: integer
example: 50001
email:
type: array
description: "Reason codes related to activity of the email address you provided for this phone number.\n
*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned."
items:
type: integer
example: 60003
Blocklisting:
title: Blocklisting
type: object
description: 'Contains details about whether the number was blocked and who requested the block. Contact our [Customer Support Team](mailto:support@telesign.com) to include this package in your response.
'
properties:
block_code:
type: integer
description: A code indicating whether the number is blocked, and who blocked it. `0` for not blocked, `1` for blocked by TeleSign, `2` for block requested by your organization, `3` for block requested by your account or set by TeleSign on behalf of your account, and `4` if the block state is unknown.
example: 0
block_description:
type: string
example: Not blocked
description: Text explaining the block status.
blocked:
type: boolean
description: If `true`, this number is blocked. If `false`, this number is not blocked.
errorObject:
title: errorObject
type: object
properties:
reference_id:
type:
- string
- 'null'
example: 0123456789ABCDEF0123456789ABCDEF
description: A unique identifier assigned by Telesign for this transaction.
external_id:
type:
- string
- 'null'
description: A customer-generated ID for this transaction. The response simply echoes the value provided for this parameter.
example: CustomExternalID7349
status:
type: object
description: Contains properties related to the processing status of this request.
properties:
updated_on:
type: string
description: The date-time when the processing status of this transaction was last updated.
example: '2024-02-01T00:33:34.860418Z'
code:
type: integer
description: A numeric code indicating the processing status of this transaction.
description:
type: string
description: Text explaining the meaning of the status code returned.
postScoreResponse:
title: postScoreResponse
type: object
properties:
reference_id:
type: string
description: A 32-digit hex value used to identify the web service request. 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.
example: CFMJ6FTL09O22UE1KC5NBD7ZMWKTMJB8
external_id:
type:
- string
- 'null'
description: The customer-generated ID for this transaction that was provided in the request. If the `external_id` parameter was not included in the request, the value here is `null`.
example: CustomExternalID7349
status:
type: object
description: 'An object containing details about the request status. '
properties:
code:
type: integer
description: One of the status codes or error codes. You should code against these and not HTTP response
example: 300
description:
type: string
description: Text describing the transaction status.
example: Transaction successfully completed
updated_on:
type: string
description: An [RFC 3339](http://www.ietf.org/rfc/rfc3339.txt) timestamp indicating when the transaction status was updated.
example: '2024-10-06T21:25:03.420503Z'
location:
$ref: '#/components/schemas/Location'
numbering:
$ref: '#/components/schemas/Numbering'
phone_type:
$ref: '#/components/schemas/PhoneType'
blocklisting:
$ref: '#/components/schemas/Blocklisting'
carrier:
$ref: '#/components/schemas/Carrier'
risk:
$ref: '#/components/schemas/Risk'
risk_insights:
$ref: '#/components/schemas/RiskInsights'
PhoneType:
title: PhoneType
type: object
properties:
code:
type: string
description: One of the [phone type codes](/enterprise/docs/codes-languages-and-time-zones#phone-type-codes).
example: '1'
override_reason:
type: string
example: Non SMS-enabled Phone Number
description: Text describing the [phone type override](/enterprise/docs/codes-languages-and-time-zones#phone-type-override-reason-codes) status of this phone number. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response.
description:
type: string
description: Text describing the phone type.
example: FIXED_LINE
override_reason_id:
type: integer
example: 11
description: A numeric code specifying the [phone type override](/enterprise/docs/codes-languages-and-time-zones#phone-type-override-reason-codes) status of this phone number. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response.
Risk_2:
title: Risk
type: object
description: Contains properties related to the risk recommendation for the specified phone number.
properties:
level:
type: string
example: high
description: The severity of the risk. [Risk Recommendation Scale](/enterprise/docs/intelligence-get-started#risk-recommendation-scale) provides a table.
recommendation:
type: string
example: block
enum:
- allow
- flag
- block
description: The action that Telesign recommends that you take based on the risk recommendation.
score:
type: integer
example: 959
description: A measure of the transaction risk involved with conducting an online business transaction at the current time for this phone number. The scale ranges from zero to 1000, with a higher value indicating a higher risk.
Carrier_2:
title: Carrier
type: object
description: Contains details about the company that provides telecommunications services for this phone number. Behavior of this property, including information returned for ported phone numbers, can vary depending on the country of the phone number. See [How does carrier data vary by country?](https://support.telesign.com/s/article/How-does-carrier-data-vary-by-country) for more details.
properties:
carrier_id:
type: integer
example: 309
description: Six-character identifier for the provider associated with the phone number by prefix that can be used for billing purposes (carrier ID, operator ID). Might be incorrect in countries where MNP is possible, since the carrier information is provided by the prefix of the phone number, and not from the carrier itself. Not included in response by default - depends on the âCarrier ID Enabledâ customer feature. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response.
name:
type: string
example: AT&T Wireless
description: Name of the provider associated with the phone number by prefix. Might be incorrect in countries where MNP is possible, since the carrier information is provided by the prefix of the phone number, and not from the carrier itself.
Location_2:
title: Location
type: object
description: Contains geographical location information associated with the rate center of the phone number when the device was activated. Null is returned when data for a field isn't available for a specific market or country.
properties:
city:
type: string
example: Odessa
description: The city associated with the rate center of the phone number when the device was activated.
county:
type: string
example: Ector
description: The county (or parish) associated with the rate center of the phone number when the device was activated (U.S. only).
state:
type: string
description: The two-letter [state abbreviation code](http://pe.usps.com/text/pub28/28apb.htm) of the state (province, district, or territory) associated with the rate center of the phone number when the device was activated (North America only).
example: TX
zip:
type: string
example: '79758'
description: The five-digit United States Postal Service [ZIP Code](https://www.usps.com/nationalpremieraccounts/findzipcodes.htm) associated with the rate center of the phone number when the device was activated (U.S. only).
country:
type: object
description: Contains properties related to the country associated with the rate center of the phone number when the device was activated.
properties:
iso2:
type: string
example: US
description: The ISO 3166-1 2-letter [country code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the rate center of the phone number when the device was activated.
iso3:
type: string
example: USA
description: ' The ISO 3166-1 3-letter country code associated with the rate center of the phone number when the device was activated.'
name:
type: string
example: United States
description: The [country name](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the rate center of the phone number when the device was activated.
time_zone:
type: object
description: Contains properties related to the time zone associated with the rate center of the phone number when the device was activated. For maximum and minimum UTC offsets, they are specified in units of hours, and range from -12 to +14. For positive numbers, the plus sign (+) may not be returned. Additional offsets due to Daylight Savings Time or Summer Time are not considered. For example, Russia, which spans 11 time zones, has a minimum UTC offset of +2, and a maximum of +12.
properties:
name:
type: string
example: America/Chicago
description: The time zone associated with the rate center of the phone number when the device was activated (U.S. only).
utc_offset_min:
type: string
example: '-6'
description: 'For international phone numbers, this parameter returns the minimum UTC offset for the country associated with the rate center of the phone number when the device was activated. For U.S. phone numbers, this parameter returns the UTC offset associated with the rate center of the phone number when the device was activated. '
utc_offset_max:
type: string
example: '-6'
description: ' For international phone numbers, this parameter returns the maximum UTC offset for the country associated with the rate center of the phone number when the device was activated. For U.S. phone numbers, this parameter returns the same result as utc_offset_min.'
coordinates:
type: object
description: Contains properties with details about the geographical coordinates of the location where the phone number is registered.
properties:
latitude:
type: number
description: Latitude specifies the North-South position of a point on the Earthâs surface. It is an angular measurement that ranges from 0° at the Equator, to 90° at the North Pole (and -90° at the South Pole). It is returned here as a value indicating the number of degrees of latitude of the location associated with the phone number, expressed in seven decimal digits, with five decimal places.
example: 31.8466
format: float
longitude:
type: number
example: -102.36778
description: Longitude specifies the East-West position of a point on the Earthâs surface. It is an angle measured East or West from the [prime meridian](https://en.wikipedia.org/wiki/Prime_meridian) âranging from 0° at the prime meridian, to +180° Eastward and -180° Westward. It is returned here as a value indicating the number of degrees of longitude of the location associated with the phone number, expressed in eight decimal digits, with five decimal places.
format: float
metro_code:
type: string
example: '36220'
description: 'A 4-digit string indicating the Primary Metropolitan Statistical Area (PMSA) code for the location associated with the rate center of the phone number when the device was activated (U.S. only). '
Numbering_2:
title: Numbering
type: object
description: Contains properties related to the numbering attributes of the specified phone number.
properties:
original:
type: object
description: Contains details about the original phone number included in the request.
properties:
phone_number:
type: string
example: '1234567890'
description: Input phone number before any transformation, returned as is, with all special characters, if any.
complete_phone_number:
type: string
example: '11234567890'
description: Input phone number after splitting country code from complete phone number, with special characters removed.
country_code:
type: string
example: '1'
description: The input country calling code after splitting the country code from the complete phone number, with special characters removed. It is the 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for the United Kingdom is `44`.
cleansing:
type: object
description: Contains details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.
properties:
call:
type: object
description: Contains cleansing details for the phone number if it is enabled to receive voice calls.
properties:
cleansed_code:
type: integer
example: 100
description: "One of the following values: \n
\nâ˘\t100 - Exact match found using original number.
\nâ˘\t101 - Match found by applying changes to the original number.
\nâ˘\t102 - Restricted number.
\nâ˘\t103 - No match found.
\nâ˘\t104 - Country code and/or phone number are invalid.
\nâ˘\t105 - No change but the match was either too long or too short.
"
country_code:
type: string
description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.
example: '1'
max_length:
type: integer
example: 10
description: The maximum number of dialing digits allowed for phone numbers with this county dialing code, excluding the country code.
min_length:
type: integer
example: 10
description: The minimum number of dialing digits allowed for phone numbers with this county dialing code, excluding the country code.
phone_number:
type: string
example: '1234567890'
description: Phone number after all cleansing transformation rules (for the Voice request type) have been applied.
sms:
type: object
description: Contains cleansing details for the phone number if it is enabled to receive SMS.
properties:
cleansed_code:
type: integer
description: "One of the following values: \n
\nâ˘\t100 - Exact match found using original number.
\nâ˘\t101 - Match found by applying changes to the original number.
\nâ˘\t102 - Restricted number.
\nâ˘\t103 - No match found.
\nâ˘\t104 - Country code and/or phone number are invalid.
\nâ˘\t105 - No change but the match was either too long or too short.
"
example: 100
country_code:
type: string
description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.
example: '1'
min_length:
type: integer
example: 10
description: The minimum number of dialing digits allowed for phone numbers with this county dialing code, excluding the country code.
max_length:
type: integer
description: The maximum number of dialing digits allowed for phone numbers with this county dialing code, excluding the country code.
example: 10
phone_number:
type: string
description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
example: '1234567890'
RiskInsights_2:
title: RiskInsights
type: object
description: "Contains reason code properties with additional info related to the risk recommendation.\n
[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings) provides the meaning of these reason codes."
properties:
status:
type: integer
description: "The processing status of the risk insights package for this request.\n\nPossible values are:\n\n| Value | Meaning |\n|-------|---------|\n| 800 | **Success.**
All fields successfully returned and available for use. | \n| 801 | **Partial Success.**
No value available for category, but other data is available. | \n| 803 | **Error.**
An error occurred; no data returned in this response. | \n\n"
enum:
- 800
- 801
- 803
example: 800
category:
type: array
description: "Reason codes related to the category of the phone number.\n
[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings) provides the meaning of the codes returned."
items:
type: integer
example: 10002
a2p:
type: array
description: "Reason codes specific to application-to-person communication (A2P). These are automated communications sent to a human, like verification codes, appointment reminders, etc.\n
[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings) provides the meaning of the codes returned."
items:
type: integer
example: 20001
p2p:
type: array
description: "Reason codes specific to person-to-person communication (P2P). This is two-way communication between two humans, like one friend texting another.\n
[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings) provides the meaning of the codes returned."
items:
type: integer
example: 30201
number_type:
type: array
description: "Reason codes related to the phone numberâs type.\n
[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings) provides the meaning of the codes returned."
items:
type: integer
example: 40005
ip:
type: array
description: "Reason codes related to activity of the IP you provided for this phone number.\n
[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings) provides the meaning of the codes returned. "
items:
type: integer
example: 50001
email:
type: array
description: "Reason codes related to activity of the email address you provided for this phone number.\n
[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings) provides the meaning of the codes returned."
items:
type: integer
example: 60003
Blocklisting_2:
title: Blocklisting
type: object
description: 'Contains details about whether the number was blocked and who requested the block. Contact our [Customer Support Team](mailto:support@telesign.com) to include this package in your response.
'
properties:
block_code:
type: integer
example: 0
description: 'A code indicating whether the number is blocked, and who blocked it.
* `0` - Not blocked
* `1`- Blocked by Telesign
* `2` - Block requested by your organization
* `3` - Block requested by your account or set by Telesign on behalf of your account
* `4` - Block state is unknown.
'
block_description:
type: string
example: Not blocked
description: Text explaining the block status.
blocked:
type: boolean
description: If `true`, this number is blocked. If `false`, this number is not blocked.
postScoreResponse_2:
title: postScoreResponse
type: object
properties:
reference_id:
type: string
description: A 32-digit hex value used to identify the web service request. 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.
example: CFMJ6FTL09O22UE1KC5NBD7ZMWKTMJB8
external_id:
type:
- string
- 'null'
description: The customer-generated ID for this transaction that was provided in the request. If the `external_id` parameter was not included in the request, the value here is `null`.
example: CustomExternalID7349
status:
type: object
description: 'An object containing details about the request status. '
properties:
code:
type: integer
example: 300
description: "Transaction status code. Successful transactions can be assigned one of the following values:
\n\tâ˘\t300 - successful transaction
\n\tâ˘\t301 - partially successful transaction"
description:
type: string
description: Text describing the transaction status.
example: Transaction successfully completed
updated_on:
type: string
description: An [RFC 3339](http://www.ietf.org/rfc/rfc3339.txt) timestamp indicating when the transaction status was updated.
example: '2024-10-06T21:25:03.420503Z'
location:
$ref: '#/components/schemas/Location_2'
numbering:
$ref: '#/components/schemas/Numbering_2'
phone_type:
$ref: '#/components/schemas/PhoneType_2'
blocklisting:
$ref: '#/components/schemas/Blocklisting_2'
carrier:
$ref: '#/components/schemas/Carrier_2'
risk:
$ref: '#/components/schemas/Risk_2'
risk_insights:
$ref: '#/components/schemas/RiskInsights_2'
PhoneType_2:
title: PhoneType
type: object
properties:
code:
type: string
example: '1'
description: "Type of service based on dial plan data (numbering_plan.dial_plan). \n\n| Code | Type |\n| :--- | :--- |\n| **1** | Fixed line |\n| **2** | Mobile |\n| **3** | PrePaid Mobile |\n| **4** | Toll Free |\n| **5** | VOIP |\n| **6** | Pager |\n| **7** | Payphone |\n| **9** | Restricted/Premium Rate |\n| **10** | Personal |\n| **11** | Voicemail |\n| **20** | Other |\n| **30** | Email |\n\nOR \n\n`null`\n\n"
description:
type: string
example: FIXED_LINE
description: 'Description of the phone type, an enumerated value from the list of codes for `code`, which identifies the phone type. '
override_reason:
type: string
example: Non SMS-enabled Phone Number
description: 'Text describing the [phone type override](/enterprise/docs/codes-languages-and-time-zones#phone-type-override-reason-codes) status of this phone number. Not included in response by default - depends on the âPhone Type Overrides Enabledâ customer feature.
Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response.
'
override_reason_id:
type: integer
example: 11
description: 'A numeric code specifying the [phone type override](/enterprise/docs/codes-languages-and-time-zones#phone-type-override-reason-codes) status of this phone number. Not included in response by default - depends on the âPhone Type Overrides Enabledâ customer feature. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response.
'
securitySchemes:
Basic:
type: http
description: Easiest to implement. See [Basic Authentication](/enterprise/docs/authentication#basic-authentication) for more details.
scheme: basic
Digest:
name: Authorization
type: apiKey
in: header
description: See [Digest Authentication](/enterprise/docs/authentication#basic-authentication) for more details.
x-refined-from:
- telesign-detect-api-openapi.json
- telesign-intelligence-cloud-api-openapi.json
x-readme:
explorer-enabled: true
proxy-enabled: true
samples-enabled: true