OpenAPI Marketplace · Messaging & SMS

Twilio Lookup (phone validation)

Name: Twilio Lookup (phone validation)
Author: vx.ai

v1.0.0 · 5 endpoints · 0 connections · shared by vx.ai

Lets an agent check whether a phone number is real and correctly formatted, convert it to E.164, and look up its line type (mobile, landline, VoIP), carrier and registered caller name before sending messages or calling. Curated from Twilio's official OpenAPI specification.

Connect this API to an AI agent Browse all specs

What you can do with Twilio Lookup (phone validation) via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

Method	Path	Operation	Description
GET	`/v2/PhoneNumbers/{PhoneNumber}`	lookupPhoneNumber	Validate and format a phone number, with optional line type and caller name
POST	`/v2/batch/query`	bulkLookupPhoneNumbers	Look up several phone numbers in one request
GET	`/v2/RateLimits`	getRateLimits	Show the lookup rate limits set on the account
GET	`/v2/RateLimits/Fields/{Field}/Bucket/{Bucket}`	getFieldRateLimit	Show the rate limit for one data package and bucket
GET	`/v2/PhoneNumbers/{PhoneNumber}/Overrides/{Field}`	getPhoneNumberOverride	Show a manual override saved for a number's lookup result

Authentication

accountSid_authToken

HTTP Basic

HTTP Basic auth: username = Account SID (AC...) or API key SID (SK...), password = Auth Token or API key secret.

How to get a credential

Sign in to the Twilio Console.
Copy the Account SID and Auth Token from the Account Info panel on the home page, or
(Recommended) go to Account > API keys & tokens, click Create API key (type Standard), and copy the key SID (SK...) and secret. The secret is shown once.
Basic validation is free; data packages such as line_type_intelligence and caller_name are billed per lookup (see Twilio's Lookup pricing). Some packages (identity match, SIM swap) need approval from Twilio first.

Permissions used

Credential	Operations
Account SID + Auth Token, or Standard API key	`lookupPhoneNumber`, `bulkLookupPhoneNumbers`, `getRateLimits`, `getFieldRateLimit`, `getPhoneNumberOverride`

Twilio has no per-endpoint scopes; a Standard API key can call all of these.

Common errors

401 (error 20003): wrong SID/secret pair. Re-copy both values.
403 (e.g. 60600/60607): the requested data package is not enabled for your account or country. Remove it from Fields or ask Twilio to enable it.
400: malformed request, e.g. an unknown value in Fields. An invalid number is not an error: it returns valid: false.
404: the number cannot be found in any format; check CountryCode for national-format numbers.
429 (20429): too many requests; back off and retry.

Store the SID and secret as a VX Agents Basic credential; they are never shown to the model.

Usage guide

Setup

Credential: Basic auth with Account SID + Auth Token, or a Standard API key SID + secret (Twilio Console > Account > API keys & tokens).
If most numbers you handle are national format from one country, pin CountryCode (ISO-2, e.g. GB, VN) as a preset; otherwise the default is US.
Decide which paid data packages the agent may use and pin Fields (e.g. line_type_intelligence) to keep costs predictable.

Validate a phone number

lookupPhoneNumber with PhoneNumber (E.164 like +14155550100, or national format plus CountryCode). With no Fields you get free basic validation:
- valid (true/false), validation_errors (e.g. TOO_SHORT, INVALID_COUNTRY_CODE),
- phone_number in E.164, national_format, country_code, calling_country_code.
Add Fields for more (comma-separated, each billed):
- line_type_intelligence: type = mobile, landline, fixedVoip, nonFixedVoip, tollFree..., plus carrier name.
- caller_name: registered CNAM name and caller_type (BUSINESS/CONSUMER), US numbers only.
- sms_pumping_risk, line_status, reassigned_number: fraud and deliverability signals (some need Twilio approval).
Use the result: store the E.164 form, and only send SMS to mobile lines.
Many numbers at once: bulkLookupPhoneNumbers with {"phone_numbers": [{"correlation_id": "1", "phone_number": "+1...", "fields": ["line_type_intelligence"]}]}. Match results by correlation_id.
getRateLimits / getFieldRateLimit show limits configured on the account; getPhoneNumberOverride shows a manual correction saved for a number.

Confirm before spending: every paid Fields package is billed per number. Before a lookup with paid packages on more than a handful of numbers, tell the user how many numbers and which packages and get a yes. Never send identity-match personal data (name, address, national id, date of birth) unless the user provided it for that purpose.

Good to know

An invalid number returns HTTP 200 with valid: false, not an error.
PhoneNumber in the path must be URL-encoded (+ becomes %2B).
Caller name works only for US numbers; line type works worldwide.
Results are a point-in-time snapshot; ported numbers change carrier.

How to use this spec

Create a free VX Agents account (sandbox tools included).
Open the marketplace and connect “Twilio Lookup (phone validation)” to an agent.
Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.