twilio '21211 invalid To phone number' - agent dialing malformed numbers from enrichment

TL;DR

Twilio rejects numbers it cannot parse, and the agent keeps feeding it raw enrichment strings with extensions, missing country codes, and formatting junk. Validate every number and normalize it to E.164 format before the dial step, quarantine anything that fails validation for human review, and fix the enrichment mapping that produced the bad numbers in the first place.

The query

twilio '21211 invalid To phone number'  -  agent dialing malformed numbers from enrichment

Steps

1. Capture the failing numbers and find the pattern

Pull the recent 21211 failures from the Twilio logs and look at the raw To values. Common patterns: missing country code, extension glued on with x or ext, or a non-phone string (like a company main line label) in the phone field.

Expected: you can name the two or three malformed patterns causing most failures.

2. Validate and normalize to E.164 before dialing

Add a pre-dial step that parses each number with a phone-number library, using the lead's country as the default region, and formats it to E.164. Numbers that do not parse never reach Twilio.

Expected: only E.164-formatted numbers reach the dial step.

3. Quarantine failures for review instead of dropping them

Send unparseable numbers to a review queue with the lead attached, not to the trash. Many are fixable (wrong field mapped, extension separated) and the lead is still worth calling.

Expected: a review queue of fixable numbers, none silently dropped.

4. Fix the enrichment field mapping

Trace the bad numbers back to the enrichment source: wrong field mapped to phone, personal versus business number confusion, or a provider returning placeholder values. Correct the mapping and add a validation gate on the enrichment ingest itself.

Expected: new enrichment batches arrive with parseable numbers.

Use this when

• Twilio dial attempts fail with 21211 invalid To phone number
• A new enrichment provider or list started feeding the dialer
• Failures cluster around specific number patterns

Not for this skill when

• Calls fail with 13224 (that is the calls-per-second rate limit)
• Twilio accepts the call but the carrier never connects it
• The account cannot dial because of insufficient balance or geo permissions

Variant phrasings

twilio 21211 invalid to phone number

Code-first phrasing. Same validate-normalize-quarantine fix.

twilio rejecting phone numbers from enrichment

Symptom phrasing. The mapping fix in step 4 is usually the root cause.

agent dialing bad numbers twilio 21211

Agent-framed phrasing. The pre-dial validation step is the guardrail.

Why it happens

Enrichment providers return phone data in inconsistent shapes: local formats without country codes, extensions appended in free text, switchboard numbers labeled as direct lines. Twilio's API expects a parseable number, so anything ambiguous gets a 21211 instead of a call. Agents that pass enrichment output straight into the dial step turn every data-quality quirk into a failed call.

Edge cases

• Some valid numbers look invalid without the right default region. Set the region from the lead's country, not from the agent's locale.
• Extensions need separate handling: dial the base number and handle the extension in the call flow, since Twilio does not parse them from the To field.
• A number that parses but belongs to a fax line or premium range wastes dials. Consider a lookup step for high-value call lists.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_F8xjyCezqn-osMQ1GG4ZSw