How to Use the Twilio Lookup API to Get Phone Number Info in Zapier

A practical field guide from Automation Ace.

How to Use the Twilio Lookup API to Get Phone Number Info in Zapier

When a phone number arrives in a Zapier workflow — from a form submission, a CRM record, a Calendly booking, or a webhook payload — it often needs validation and enrichment before it is useful. Is the number valid? Is it a mobile line (eligible for SMS) or a landline (not eligible for SMS)? Which carrier is it on? What country is it from? The Twilio Lookup API answers all of these questions with a single API call. This guide covers how to call Twilio Lookup inside a Zap using Webhooks by Zapier, what data it returns, and how to use that data to make routing decisions.

What the Twilio Lookup API Returns

The Twilio Lookup API (https://lookups.twilio.com/v1/PhoneNumbers/{phone_number}) validates a phone number and optionally returns enrichment data. The base lookup (no extra packages) returns:

• phone_number — the number in E.164 format (e.g., +14155551234) — useful for normalizing inconsistently formatted inputs
• national_format — the number formatted for its country (e.g., (415) 555-1234)
• country_code — the ISO 3166-1 alpha-2 country code (e.g., US)
• url — the canonical Lookup API URL for this number

With the Type=carrier query parameter added, the API also returns:

• carrier.name — the carrier name (e.g., "AT&T", "Verizon", "Google Voice")
• carrier.type — line type: mobile, landline, or voip
• carrier.mobile_country_code and carrier.mobile_network_code — MCC/MNC identifiers

If the phone number is invalid or cannot be found, the API returns a 404 error — which you can catch with a Filter step to stop the Zap or route to an error handling branch. Note that carrier lookups have a per-lookup cost in Twilio — check Twilio's current pricing for the Lookup API before enabling carrier enrichment on high-volume workflows.

Prerequisites

• A Twilio account (free trial is sufficient for testing)
• Your Twilio Account SID and Auth Token — available in the Twilio Console dashboard
• A phone number to look up, available as a field in your Zap

Step-by-Step: Calling Twilio Lookup in a Zap

Step 1: Add a Webhooks by Zapier GET action

1. In your Zap, after the step that provides the phone number, add a Webhooks by Zapier action step.
2. Select GET as the action event.

Step 2: Configure the URL

Build the Lookup API URL using the phone number from the previous Zap step. The phone number must be URL-encoded — the + in E.164 format must be encoded as %2B. If your input phone number is already in E.164 format, use Formatter by Zapier to encode it first, or use the URL encoding handled automatically by the Webhooks action.

Set the URL field to:

https://lookups.twilio.com/v1/PhoneNumbers/[phone_number_from_previous_step]?Type=carrier

Map the phone number dynamic field from your trigger or earlier action into the URL. If the number is not in E.164 format (e.g., it is 4155551234 without the country code), prefix it with the country calling code: +1[number] for US numbers.

Step 3: Configure Basic Auth with your Twilio credentials

The Twilio Lookup API authenticates with HTTP Basic Auth — your Twilio Account SID as the username and your Auth Token as the password.

1. In the Webhooks by Zapier action, find the Basic Auth fields.
2. Enter your Account SID as the username.
3. Enter your Auth Token as the password.

Do not put these credentials in the URL or headers manually — use the dedicated Basic Auth fields so Zapier handles the encoding correctly. For more on API authentication patterns in Zapier, see API authentication for automation.

Step 4: Test the action

Run a test with a known phone number. A successful response returns a JSON object. Zapier parses the top-level fields automatically — the carrier sub-object fields appear as Carrier Name, Carrier Type, etc. in the step output.

If you get a 404 error, the number is invalid or unsupported. If you get a 401, check your Account SID and Auth Token.

Step 5: Use the Lookup results in downstream steps

The Lookup API response fields are now available as Zap output fields:

• Map Phone Number (the E.164 normalized version) into your CRM or database to standardize storage format
• Map National Format for display in email templates or Slack notifications
• Add a Filter by Zapier step after the Lookup: only continue if Carrier Type equals mobile — so SMS messages are only sent to mobile numbers
• Map Country Code to route leads by geography or apply country-specific compliance logic
• Map Carrier Name into an Airtable record for lead qualification tracking

Handling Invalid Numbers

When Twilio returns a 404 for an invalid number, Zapier's Webhooks action will mark the step as errored and halt the Zap by default. To handle invalid numbers gracefully:

1. In the Webhooks action settings, enable Unflatten off and note the response body.
2. Alternatively, use a Code step instead of Webhooks to call the Lookup API with a try/catch — returning a valid: false field if the API returns an error, rather than halting the Zap.

Using Twilio Lookup with SMS Compliance

The carrier type check — filtering for mobile before sending an SMS — is important for both deliverability and A2P 10DLC compliance. Sending application-to-person SMS to landline numbers wastes tasks and can trigger carrier filtering. The Lookup validation step adds a small per-lookup cost but prevents failed SMS sends. For a deeper look at A2P compliance in Zapier SMS workflows, see A2P 10DLC registration for SMS in Zapier and Twilio.

If you don't already have an account, Twilio's signup is here — the free trial credit is enough to test Lookup calls before wiring the step into a production Zap. For help designing the validation and routing logic around it, talk to Automation Ace.

The Twilio Lookup API is one of the most practical enrichment calls to add to any workflow that collects phone numbers from users. A single API call validates the number, normalizes it to E.164, identifies the line type, and returns the carrier — all of which improve downstream deliverability and data quality. The cost per lookup is low compared to the cost of routing to an SMS workflow that fails because the number was a landline.

For more on using external APIs in Zapier, see how to use APIs in Zapier steps. For help building a phone validation and enrichment workflow, talk to Automation Ace.