Skip to main content
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.

Verification lifecycle

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

Verification rejection reasons

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

Business information issues

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:
  1. Look up your exact legal name on your state’s Secretary of State website
  2. Cross-reference with your EIN confirmation letter from the IRS
  3. Include suffixes exactly: “Inc.”, “LLC”, “Corp.” — these matter
  4. Resubmit with the corrected name
curl
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
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:
  1. Verify your EIN at IRS.gov or on your SS-4 confirmation letter
  2. Ensure the businessRegistrationType matches the number format (e.g., “EIN” for US tax IDs)
  3. Confirm businessRegistrationCountry is correct (ISO alpha-2)
  4. For sole proprietors using SSN, ensure the name matches exactly
curl
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:
  1. Ensure the URL is accessible (no authentication required, no redirects to a different domain)
  2. The website must show the company name prominently
  3. Website content should relate to the messaging use case
  4. HTTPS is strongly preferred
  5. Under construction / parking pages will cause rejection
Before resubmitting, verify:
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:
  1. Use a phone number that’s publicly associated with the business (Google listing, website, etc.)
  2. Use a business email domain (not gmail.com, yahoo.com for corporations)
  3. Ensure the contact person is authorized to represent the business
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:

Messaging use case issues

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:
  1. Ensure every sample message directly relates to your declared use case
  2. Include realistic content — not placeholder text
  3. Show the full message including opt-out language
  4. If you have multiple use cases, describe all of them in useCaseSummary
Good sample:
Bad sample:
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:
  1. Include “Reply STOP to unsubscribe” (or similar) in every sample
  2. The opt-out instruction should be natural, not buried
  3. 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.”
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:
  1. Be honest about expected volumes — carriers cross-reference similar businesses
  2. If volume is high, explain why (large customer base, time-sensitive notifications)
  3. Start conservative and increase as your messaging matures
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:
Bad example:
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:
  1. If your content is genuinely prohibited, toll-free may not be the right channel
  2. For regulated industries (gambling, financial services), include licensing documentation
  3. Remove any references to restricted content from samples
  4. 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.
1

Read the rejection reason carefully

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

Fix the identified issues

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

Resubmit for review

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

Monitor status via webhooks

Set up webhooks to get notified when the review completes:
Python

Resubmission tips


Delivery issues after verification

Even after successful verification, you may experience delivery problems.

Throughput limitations

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

Cause: Message content triggered carrier-level content filters, independent of verification status.Fix:
  1. Review message content for spam trigger words (FREE, WINNER, ACT NOW)
  2. Avoid URL shorteners (bit.ly, tinyurl) — use full URLs or Telnyx URL shortening
  3. Don’t send identical messages to many recipients in rapid succession
  4. Check if recipient has previously opted out
  5. Review the error code reference for specific guidance
Cause: The recipient number is invalid, deactivated, or not SMS-capable.Fix:
  1. Validate numbers before sending (use Number Lookup API)
  2. Remove landlines and VoIP numbers that don’t support SMS
  3. Check for typos in the recipient number
Cause: Sending faster than your verified throughput allows.Fix:
  1. Implement client-side rate limiting (see Rate Limiting guide)
  2. Spread traffic across multiple toll-free numbers if needed
  3. Use a messaging profile with number pooling for high-volume use cases
Cause: Message sat in the queue too long, usually due to throughput congestion.Fix:
  1. Reduce sending rate to stay within throughput limits
  2. Check if a carrier outage is causing delivery backlog
  3. For time-sensitive messages, set a shorter validity period
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:
  1. Start with lower volumes and ramp up gradually over 1–2 weeks
  2. Monitor delivery rates per carrier using MDRs
  3. Ensure opt-out is working properly (high complaint rates trigger filtering)
  4. Contact Telnyx support if specific carriers consistently filter your traffic

Checking verification status

Via API

Via Portal

  1. Log in to the Telnyx Portal
  2. Navigate to MessagingToll-Free Verification
  3. View status, rejection reasons, and submission details for each verification

Status reference


Diagnostic checklist

Use this checklist when troubleshooting verification issues:

Before submitting

  • Business name matches exact legal name (including Inc./LLC/etc.)
  • EIN/BRN is correct and matches the business name
  • Website is live, accessible, and shows the business name
  • Contact phone and email are valid and publicly associated with the business
  • Entity type matches business registration
  • Use case summary clearly describes messaging purpose
  • Sample messages are realistic (not placeholder text)
  • Every sample includes opt-out language (“Reply STOP to unsubscribe”)
  • Message flow describes how users consent to receive messages
  • Volume estimate is reasonable for the use case

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

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

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

Next steps

Toll-Free Verification

Main verification guide with BRN fields and API reference.

Error Code Reference

Understand delivery error codes and resolution steps.

10DLC Troubleshooting

Similar troubleshooting guide for 10DLC registration issues.

Rate Limiting

Implement client-side rate limiting to avoid throughput errors.