Telnyx

This guide covers common toll-free verification failures, rejection reasons, resubmission best practices, and messaging issues with toll-free numbers. Use it to diagnose problems and get your verification approved faster.

Quick links: Rejection reasons · Resubmission guide · Delivery issues · Status tracking · Diagnostic checklist

Verification lifecycle

Understanding where your verification can fail helps target the right fix:

Stage	Timeline	What happens
Submission	Instant	API validates fields, returns 201 or error
Under review	1–2 weeks	Carriers review business identity and messaging use case
Decision	—	Approved (full throughput) or rejected (with reason)
Resubmission	Instant	Fix issues and resubmit — no limit on attempts

Verification rejection reasons

Rejections come from carrier review. Each has specific causes and fixes.

Business information issues

Business name mismatch

Rejection reason: Business name does not match public records.Root cause: The businessName you submitted doesn’t match what’s on file with the Secretary of State, IRS, or similar authority for your registration number.Fix:

Look up your exact legal name on your state’s Secretary of State website
Cross-reference with your EIN confirmation letter from the IRS
Include suffixes exactly: “Inc.”, “LLC”, “Corp.” — these matter
Resubmit with the corrected name

curl

curl -X PATCH https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Acme Corporation Inc."
  }'

Common mistakes:

Using a DBA/trade name instead of the legal entity name
Missing “LLC”, “Inc.”, etc.
Using an old company name after a legal name change

Business registration number (BRN) cannot be verified

Rejection reason: Unable to verify business registration information.Root cause: The EIN, ABN, VAT number, or other registration number doesn’t match the business name or doesn’t exist in public records.Fix:

Verify your EIN at IRS.gov or on your SS-4 confirmation letter
Ensure the businessRegistrationType matches the number format (e.g., “EIN” for US tax IDs)
Confirm businessRegistrationCountry is correct (ISO alpha-2)
For sole proprietors using SSN, ensure the name matches exactly

curl

curl -X PATCH https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessRegistrationNumber": "12-3456789",
    "businessRegistrationType": "EIN",
    "businessRegistrationCountry": "US"
  }'

Website unreachable or doesn't match

Rejection reason: Corporate website could not be verified or does not match the business.Root cause: Carriers check that the website is live, matches the business name, and has content relevant to the declared use case.Fix:

Ensure the URL is accessible (no authentication required, no redirects to a different domain)
The website must show the company name prominently
Website content should relate to the messaging use case
HTTPS is strongly preferred
Under construction / parking pages will cause rejection

Before resubmitting, verify:

# Check website is accessible
curl -sI https://yourbusiness.com | head -5

# Check it resolves to expected domain
curl -sL -o /dev/null -w '%{url_effective}' https://yourbusiness.com

Contact information invalid

Rejection reason: Contact information could not be verified.Root cause: The phone number or email provided doesn’t match public records for the business, or isn’t reachable.Fix:

Use a phone number that’s publicly associated with the business (Google listing, website, etc.)
Use a business email domain (not gmail.com, yahoo.com for corporations)
Ensure the contact person is authorized to represent the business

Entity type mismatch

Rejection reason: Entity type does not match business records.Root cause: You selected PRIVATE_PROFIT but the business is registered as a nonprofit, or vice versa.Fix: Choose the correct entity type based on your actual business registration:

Entity Type	Use for
`SOLE_PROPRIETOR`	Individual / sole proprietorship
`PRIVATE_PROFIT`	Private corporation (most common)
`PUBLIC_PROFIT`	Publicly traded company
`NON_PROFIT`	501(c)(3) or charitable organization
`GOVERNMENT`	Government entity at any level

Messaging use case issues

Sample messages don't match declared use case

Rejection reason: Message samples are inconsistent with the stated use case.Root cause: Your useCaseSummary says one thing (e.g., “appointment reminders”) but your sample messages show something different (e.g., marketing promotions).Fix:

Ensure every sample message directly relates to your declared use case
Include realistic content — not placeholder text
Show the full message including opt-out language
If you have multiple use cases, describe all of them in useCaseSummary

Good sample:

Hi Sarah, this is Dr. Smith's office. Your appointment is confirmed
for March 15 at 2:00 PM. Reply STOP to opt out of reminders.

Bad sample:

Test message for verification purposes.

Missing or inadequate opt-out language

Rejection reason: Sample messages must include opt-out instructions.Root cause: At least one sample message is missing STOP/opt-out language, or the opt-out mechanism isn’t clear.Fix:

Include “Reply STOP to unsubscribe” (or similar) in every sample
The opt-out instruction should be natural, not buried
STOP, CANCEL, UNSUBSCRIBE, QUIT, END should all work

Required format examples:

“Reply STOP to opt out.”
“Text STOP to unsubscribe.”
“Reply STOP to end messages. Msg & data rates may apply.”

Message volume inconsistent with use case

Rejection reason: Declared message volume does not align with the use case.Root cause: Claiming a very high volume for a use case that typically doesn’t generate it, or vice versa.Fix:

Be honest about expected volumes — carriers cross-reference similar businesses
If volume is high, explain why (large customer base, time-sensitive notifications)
Start conservative and increase as your messaging matures

Opt-in mechanism not described

Rejection reason: Opt-in process is unclear or not documented.Root cause: You didn’t adequately describe how recipients consent to receive messages.Fix: Describe the full opt-in flow in your messageFlow field:

Where users sign up (website form, checkout flow, in-app)
What consent language they see
Whether it’s single or double opt-in
How consent records are maintained

Good example:

Customers opt in during checkout at acme.com/checkout by checking
"I agree to receive order updates and shipping notifications via SMS."
Consent is recorded with timestamp and IP address. Customers can
opt out at any time by replying STOP.

Bad example:

Users sign up on our website.

Prohibited or restricted content detected

Rejection reason: Message content contains prohibited or restricted material.Root cause: Sample messages or use case involves content types that carriers restrict:

Cannabis/CBD
Adult content
Gambling (without proper licensing documentation)
High-risk financial services (payday loans, crypto trading signals)
Third-party lead generation

Fix:

If your content is genuinely prohibited, toll-free may not be the right channel
For regulated industries (gambling, financial services), include licensing documentation
Remove any references to restricted content from samples
Contact Telnyx support for guidance on restricted use cases

Resubmission process

After a rejection, you can fix the issues and resubmit. There’s no limit on resubmission attempts.

Read the rejection reason carefully

Check your verification status via API or the Telnyx portal. The rejection reason tells you exactly what to fix.

curl -s https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" | python3 -m json.tool

Fix the identified issues

Update only the fields that caused the rejection. Use PATCH to update specific fields:

curl -X PATCH https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Corrected Legal Name LLC",
    "messageVolume": "10000",
    "useCaseSummary": "Updated description of our messaging use case...",
    "sampleMessage1": "Updated sample with opt-out. Reply STOP to unsubscribe.",
    "sampleMessage2": "Another realistic sample. Reply STOP to opt out."
  }'

Resubmit for review

After updating, the verification automatically enters the review queue again. No separate “submit” action is needed — the PATCH triggers re-review.

Monitor status via webhooks

Set up webhooks to get notified when the review completes:

Python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/toll-free", methods=["POST"])
def handle_toll_free_webhook():
    event = request.json
    event_type = event.get("data", {}).get("event_type", "")

    if event_type == "toll_free_verification.status_update":
        payload = event["data"]["payload"]
        status = payload["status"]
        request_id = payload["id"]

        if status == "verified":
            print(f"✅ Verification {request_id} approved!")
            # Enable full messaging for this number
        elif status == "rejected":
            reason = payload.get("rejectionReason", "No reason provided")
            print(f"❌ Verification {request_id} rejected: {reason}")
            # Alert team, prepare resubmission

    return jsonify({"status": "ok"}), 200

Resubmission tips

Do	Don’t
Fix only the cited rejection reason	Change everything at once
Use exact legal business name	Use informal names or abbreviations
Provide realistic sample messages	Use generic placeholder text
Include opt-out in every sample	Assume opt-out is implied
Wait for the full review cycle	Submit multiple times in rapid succession

Delivery issues after verification

Even after successful verification, you may experience delivery problems.

Throughput limitations

Verification status	Throughput	Notes
Unverified	~0.25 MPS	Heavy carrier filtering, low reliability
Pending review	~1 MPS	Some filtering may apply
Verified	Up to 20 MPS	Full throughput, minimal filtering

Sending above your throughput tier results in message queuing and eventual 40014 (Expired in queue) errors. If you need more than 20 MPS from toll-free numbers, consider using short codes or 10DLC with number pools.

Common delivery errors

40002 — Blocked as spam (even after verification)

Cause: Message content triggered carrier-level content filters, independent of verification status.Fix:

Review message content for spam trigger words (FREE, WINNER, ACT NOW)
Avoid URL shorteners (bit.ly, tinyurl) — use full URLs or Telnyx URL shortening
Don’t send identical messages to many recipients in rapid succession
Check if recipient has previously opted out
Review the error code reference for specific guidance

40005 — Destination number unreachable

Cause: The recipient number is invalid, deactivated, or not SMS-capable.Fix:

Validate numbers before sending (use Number Lookup API)
Remove landlines and VoIP numbers that don’t support SMS
Check for typos in the recipient number

40011 — Rate limit exceeded

Cause: Sending faster than your verified throughput allows.Fix:

Implement client-side rate limiting (see Rate Limiting guide)
Spread traffic across multiple toll-free numbers if needed
Use a messaging profile with number pooling for high-volume use cases

40014 — Message expired in queue

Cause: Message sat in the queue too long, usually due to throughput congestion.Fix:

Reduce sending rate to stay within throughput limits
Check if a carrier outage is causing delivery backlog
For time-sensitive messages, set a shorter validity period

Messages delivering but not received by all carriers

Cause: Some carriers may still filter your toll-free traffic even after verification, especially for:

New verifications (carrier trust builds over time)
Content that resembles spam patterns
High complaint rates from recipients

Fix:

Start with lower volumes and ramp up gradually over 1–2 weeks
Monitor delivery rates per carrier using MDRs
Ensure opt-out is working properly (high complaint rates trigger filtering)
Contact Telnyx support if specific carriers consistently filter your traffic

Checking verification status

Via API

# Get status of a specific verification
curl -s https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
print(f\"Status: {data['status']}\")
print(f\"Phone numbers: {', '.join(data.get('phoneNumbers', []))}\")
if data.get('rejectionReason'):
    print(f\"Rejection reason: {data['rejectionReason']}\")
"

# List all verifications
curl -s "https://api.telnyx.com/v2/tollFreeVerification/requests?page[size]=25" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
for req in data:
    numbers = ', '.join(req.get('phoneNumbers', []))
    print(f\"{req['id']} | {req['status']:12} | {numbers}\")
"

Via Portal

Log in to the Telnyx Portal
Navigate to Messaging → Toll-Free Verification
View status, rejection reasons, and submission details for each verification

Status reference

Status	Meaning	Action needed
`draft`	Created but not yet submitted	Complete required fields and submit
`pending`	Under carrier review	Wait (1–2 weeks typical)
`verified`	Approved ✅	None — full throughput unlocked
`rejected`	Carrier rejected ❌	Fix issues and resubmit

Diagnostic checklist

Use this checklist when troubleshooting verification issues:

Before submitting

After rejection

Read the rejection reason completely
Cross-reference with the rejection reasons above
Fix only the specific issue cited
Double-check all information against official business records
Resubmit via PATCH (don’t create a new request)
Set up webhooks to track the new review

After verification (delivery issues)

Verify toll-free number is on an active messaging profile
Check sending rate isn’t exceeding throughput tier
Review message content for spam trigger words
Confirm opt-out keywords are being processed
Check MDRs for carrier-specific delivery rates
Monitor error codes for patterns

Timeline expectations

Stage	Typical duration
Initial submission to review start	1–3 business days
Carrier review	5–10 business days
Total (first submission)	1–2 weeks
Resubmission review	5–10 business days
Multiple resubmissions	Each adds ~1 week

Expedited review is not available for toll-free verification. The review timeline is set by carriers, not Telnyx. Ensure your first submission is complete and accurate to avoid resubmission delays.

Toll-free vs. 10DLC: when to use which

Factor	Toll-Free	10DLC
Setup time	1–2 weeks	Days (brand + campaign registration)
Throughput	Up to 20 MPS	Varies by vetting score (up to 240 MPS with enhanced)
Cost	Per-message only	Per-message + campaign fees ($10/mo)
Number appearance	800/888/877/etc.	Local area code
Registration	Toll-free verification	TCR brand + campaign
MMS	✅ Supported	✅ Supported
Best for	Customer service, national reach	Local presence, high volume A2P

Many businesses use both: toll-free for customer service and support lines, 10DLC for marketing and transactional messages with local presence.

Sending Messages

Messaging Profiles

Short Code

RCS

Hosted Numbers

Opt Outs

Phone Numbers

Toll Free Verification

10 DLC

Toll-Free Verification Troubleshooting

Verification lifecycle

Verification rejection reasons

Business information issues

Messaging use case issues

Resubmission process

Resubmission tips

Delivery issues after verification

Throughput limitations

Common delivery errors

Checking verification status

Via API

Via Portal

Status reference

Diagnostic checklist

Before submitting

After rejection

After verification (delivery issues)

Timeline expectations

Toll-free vs. 10DLC: when to use which

Next steps

Toll-Free Verification

Error Code Reference

10DLC Troubleshooting

Rate Limiting

Sending Messages

Messaging Profiles

Short Code

RCS

Hosted Numbers

Opt Outs

Phone Numbers

Toll Free Verification

10 DLC

​Verification lifecycle

​Verification rejection reasons

​Business information issues

​Messaging use case issues

​Resubmission process

​Resubmission tips

​Delivery issues after verification

​Throughput limitations

​Common delivery errors

​Checking verification status

​Via API

​Via Portal

​Status reference

​Diagnostic checklist

​Before submitting

​After rejection

​After verification (delivery issues)

​Timeline expectations

​Toll-free vs. 10DLC: when to use which

​Next steps

Toll-Free Verification

Error Code Reference

10DLC Troubleshooting

Rate Limiting

Verification lifecycle

Verification rejection reasons

Business information issues

Messaging use case issues

Resubmission process

Resubmission tips

Delivery issues after verification

Throughput limitations

Common delivery errors

Checking verification status

Via API

Via Portal

Status reference

Diagnostic checklist

Before submitting

After rejection

After verification (delivery issues)

Timeline expectations

Toll-free vs. 10DLC: when to use which

Next steps