Toll-Free Verification
Submit and track Toll-Free Verification for US/CA toll-free phone numbers to enable SMS messaging.
Toll-Free Verification (TFV) is required by US and Canadian carriers before a toll-free phone number can send SMS. Each toll-free phone number can have one active verification at a time.
TFV is a separate compliance workflow from other trust and regulatory processes. It has its own submission process, review lifecycle, and status tracking.
Verification Lifecycle
Submit - POST creates a verification in
pending-reviewstatus.Review - The carrier reviews the submission. Status moves to
in-review.Decision - The carrier approves (
twilio-approved, terminal) or rejects (twilio-rejected).Resubmit (if rejected) - POST again with corrected information. The system handles whether to update the existing submission or replace it based on the edit window.
Expiry (if rejected and edit window closes) - The expired record is cleaned up automatically so the next POST starts fresh.
Statuses
pending-review
Submitted, awaiting carrier review
No (409)
Yes
in-review
Carrier is actively reviewing
No (409)
No (409)
twilio-approved
Approved (terminal)
No (409)
Yes
twilio-rejected
Rejected by carrier
Yes
Yes
Endpoints
Submit Toll-Free Verification
Creates a new verification or resubmits after rejection. Returns 422 if the phone number is not a US or CA toll-free number.
Path parameters:
setup_id
UUID
Twilio setup identifier
phone_number_id
UUID
Phone number identifier
Request body:
business_name
string
Yes
Legal business name (max 256 chars)
business_website
string (URL)
Yes
Public business website
use_case_summary
string
Yes
How messaging is used (max 4096 chars)
production_message_sample
string
Yes
Example message (max 2048 chars)
opt_in_image_urls
array of strings (URLs)
Yes
URLs to opt-in workflow images, 1-10 items
opt_in_type
string
Yes
Opt-in method: VERBAL, WEB_FORM, PAPER_FORM, VIA_TEXT, MOBILE_QR_CODE
business_street_address
string
Yes
Street address (max 256 chars)
business_street_address2
string
No
Address line 2 (max 256 chars)
business_city
string
Yes
City (max 128 chars)
business_state_province_region
string
Yes
State/province/region (max 128 chars)
business_postal_code
string
Yes
Postal code (max 32 chars)
business_country
string
Yes
ISO 3166-1 alpha-2 country code (e.g., US)
business_contact_first_name
string
Yes
Contact first name (max 128 chars)
business_contact_last_name
string
Yes
Contact last name (max 128 chars)
business_contact_email
string (email)
Yes
Contact email
business_contact_phone
string (E.164)
Yes
Contact phone (e.g., +14155551234)
additional_information
string
No
Context for reviewers (max 4096 chars)
Response: TollfreeVerificationResponse (see below)
Error responses:
404
Setup or phone number not found
409
Verification exists and is not in rejected state
422
Phone number is not US or CA toll-free
Get Toll-Free Verification
Returns the current verification state. 404 if no verification exists.
Path parameters:
setup_id
UUID
Twilio setup identifier
phone_number_id
UUID
Phone number identifier
Response: TollfreeVerificationResponse
Error responses:
404
Setup, phone number, or verification not found
Response Model
TollfreeVerificationResponse
phone_number_id
string (UUID)
Phone number this verification is attached to
verification_sid
string
Verification identifier
status
string
pending-review, in-review, twilio-approved, or twilio-rejected
business_name
string
Submitted business name
business_website
string
Submitted business website
use_case_categories
array of strings
Submitted use case categories
use_case_summary
string
Submitted use case summary
production_message_sample
string
Submitted message sample
opt_in_image_urls
array of strings
Submitted opt-in image URLs
opt_in_type
string
Submitted opt-in type
message_volume
string
Submitted message volume
business_street_address
string
Submitted street address
business_street_address2
string or null
Submitted address line 2
business_city
string
Submitted city
business_state_province_region
string
Submitted state/province/region
business_postal_code
string
Submitted postal code
business_country
string
Submitted country code
business_contact_first_name
string
Submitted contact first name
business_contact_last_name
string
Submitted contact last name
business_contact_email
string
Submitted contact email
business_contact_phone
string
Submitted contact phone
additional_information
string or null
Submitted additional information
rejection_reasons
array of objects or null
When rejected: array of {code, description} entries from the carrier
edit_allowed
boolean or null
When rejected: whether the submission can be updated in place vs. replaced
created_at
string (datetime)
Creation timestamp
updated_at
string (datetime)
Last update timestamp
Use Case Categories
The following traffic categories are accepted:
2FA, App Notifications, Appointments, Auctions, Auto Repair Services, Bank Transfers, Billing, Booking Confirmations, Business Updates, Career Training, Chatbot, Conversational / Alerts, Courier Services & Deliveries, COVID-19 Alerts, Emergency Alerts, Events & Planning, Financial Services, Fraud Alerts, Fundraising, General Marketing, General School Updates, HR / Staffing, Healthcare Alerts, Housing Community Updates, Insurance Services, Job Dispatch, Legal Services, Mixed, Motivational Reminders, Notary Notifications, Order Notifications, Political, Public Works, Real Estate Services, Religious Services, Repair and Diagnostics Alerts, Rewards Program, Surveys, System Alerts, Voting Reminders, Waitlist Alerts, Webinar Reminders, Workshop Alerts
Message Volumes
Accepted monthly volume buckets:
10, 100, 1,000, 10,000, 100,000, 250,000, 500,000, 750,000, 1,000,000, 5,000,000+
Phone Number Deletion Behavior
When deleting a phone number that has an associated toll-free verification:
In-review - Deletion is blocked (409). Wait for the review to complete.
Any other status - The phone number and its verification are deleted together.
Last updated
Was this helpful?