The Twilio Lookup API allows developers to query information about phone numbers to enable trusted interactions with users. It provides phone number validation, formatting, line type intelligence, carrier information, SIM swap detection, caller name lookup, identity matching, and SMS pumping risk assessment. The API helps businesses verify users, prevent fraud, improve message deliverability, and ensure compliance with regulations like TCPA.
openapi: 3.1.0
info:
title: Twilio Lookup API
description: >-
Query phone number information for validation, carrier details, line type
intelligence, caller identity, SIM swap detection, and fraud risk
assessment. Lookup v2 provides comprehensive phone number intelligence
for trusted customer interactions.
version: '2.0'
contact:
name: Twilio Support
url: https://support.twilio.com
email: [email protected]
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: https://www.twilio.com/legal/tos
externalDocs:
description: Twilio Lookup API Documentation
url: https://www.twilio.com/docs/lookup
servers:
- url: https://lookups.twilio.com/v2
description: Twilio Lookup API v2
tags:
- name: Phone Numbers
description: Query phone number data and intelligence
security:
- accountSid_authToken: []
paths:
/PhoneNumbers/{PhoneNumber}:
get:
operationId: fetchPhoneNumber
summary: Twilio Look up a Phone Number
description: >-
Query information about a phone number. Specify which data packages
to include using the Fields parameter. Available packages include
validation, line type intelligence, caller name, SIM swap, identity
match, SMS pumping risk, and more.
tags:
- Phone Numbers
parameters:
- name: PhoneNumber
in: path
required: true
description: Phone number to look up in E.164 format
schema:
type: string
- name: Fields
in: query
required: false
description: >-
Comma-separated list of data packages to return. Available
fields include validation, line_type_intelligence,
caller_name, sim_swap, identity_match, sms_pumping_risk,
phone_number_quality_score, reassigned_number, line_status
schema:
type: string
examples:
validation:
value: validation
multiple:
value: line_type_intelligence,caller_name,sim_swap
- name: CountryCode
in: query
description: >-
ISO 3166-1 alpha-2 country code for national format numbers
schema:
type: string
minLength: 2
maxLength: 2
- name: FirstName
in: query
description: First name for identity match
schema:
type: string
- name: LastName
in: query
description: Last name for identity match
schema:
type: string
- name: AddressLine1
in: query
description: Address line 1 for identity match
schema:
type: string
- name: AddressLine2
in: query
description: Address line 2 for identity match
schema:
type: string
- name: City
in: query
description: City for identity match
schema:
type: string
- name: State
in: query
description: State or province for identity match
schema:
type: string
- name: PostalCode
in: query
description: Postal code for identity match
schema:
type: string
- name: AddressCountryCode
in: query
description: ISO country code for identity match address
schema:
type: string
- name: NationalId
in: query
description: National ID for identity match
schema:
type: string
- name: DateOfBirth
in: query
description: Date of birth for identity match (YYYYMMDD)
schema:
type: string
responses:
'200':
description: Phone number lookup results
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberLookup'
'400':
description: Invalid phone number format
'401':
description: Unauthorized
'404':
description: Phone number not found
'429':
description: Rate limit exceeded
components:
securitySchemes:
accountSid_authToken:
type: http
scheme: basic
description: >-
Use your Twilio Account SID as the username and Auth Token as the
password for HTTP Basic authentication.
schemas:
PhoneNumberLookup:
type: object
properties:
phone_number:
type: string
description: Phone number in E.164 format
country_code:
type: string
description: ISO 3166-1 alpha-2 country code
national_format:
type: string
description: Phone number in national format
calling_country_code:
type: string
description: International dialing country code
valid:
type: boolean
description: Whether the phone number is valid
validation_errors:
type: array
items:
type: string
enum:
- TOO_SHORT
- TOO_LONG
- INVALID_BUT_POSSIBLE
- INVALID_COUNTRY_CODE
- INVALID_LENGTH
- NOT_A_NUMBER
description: Validation error codes if the number is invalid
caller_name:
type: object
description: Caller name (CNAM) information
properties:
caller_name:
type: string
description: Registered caller name
caller_type:
type: string
enum:
- CONSUMER
- BUSINESS
description: Type of caller
error_code:
type: integer
line_type_intelligence:
type: object
description: Line type and carrier information
properties:
type:
type: string
enum:
- landline
- mobile
- fixedVoip
- nonFixedVoip
- personal
- tollFree
- premium
- sharedCost
- uan
- voicemail
- pager
- unknown
description: Type of phone line
carrier_name:
type: string
description: Name of the carrier
mobile_country_code:
type: string
description: Mobile country code (MCC)
mobile_network_code:
type: string
description: Mobile network code (MNC)
error_code:
type: integer
sim_swap:
type: object
description: SIM swap detection results
properties:
last_sim_swap:
type: object
properties:
last_sim_swap_date:
type: string
format: date-time
description: Date of the last SIM swap
swapped_period:
type: string
description: Time period classification of the swap
swapped_in_period:
type: boolean
description: Whether a swap occurred in the check period
carrier_name:
type: string
mobile_country_code:
type: string
mobile_network_code:
type: string
error_code:
type: integer
identity_match:
type: object
description: Identity match verification results
properties:
first_name_match:
type: string
enum:
- exact_match
- high_partial_match
- partial_match
- no_match
- no_data_available
description: How well the first name matches
last_name_match:
type: string
enum:
- exact_match
- high_partial_match
- partial_match
- no_match
- no_data_available
address_lines_match:
type: string
enum:
- exact_match
- high_partial_match
- partial_match
- no_match
- no_data_available
city_match:
type: string
state_match:
type: string
postal_code_match:
type: string
country_code_match:
type: string
national_id_match:
type: string
date_of_birth_match:
type: string
summary_score:
type: integer
description: Overall identity match score (0-100)
error_code:
type: integer
sms_pumping_risk:
type: object
description: SMS pumping fraud risk assessment
properties:
carrier_risk_category:
type: string
enum:
- low
- medium
- high
description: Risk category based on carrier
carrier_risk_score:
type: integer
description: Numeric risk score (0-100)
number_blocked:
type: boolean
description: Whether the number is blocked
number_blocked_date:
type: string
format: date-time
sms_pumping_risk_score:
type: integer
description: Overall SMS pumping risk score (0-100)
error_code:
type: integer
phone_number_quality_score:
type: object
description: Phone number quality assessment
properties:
quality_score:
type: integer
description: Quality score (0-100)
error_code:
type: integer
reassigned_number:
type: object
description: Number reassignment detection
properties:
last_verified_date:
type: string
format: date
is_reassigned:
type: string
enum:
- 'yes'
- 'no'
- cannot_determine
- no_data_available
error_code:
type: integer
line_status:
type: object
description: Current line status
properties:
status:
type: string
enum:
- active
- inactive
- no_data_available
error_code:
type: integer
url:
type: string
format: uri
description: URL of this resource