Toll-Free Verification with Business Registration Fields

Telnyx toll-free verification now supports Business Registration Number (BRN) fields to strengthen business verification and compliance. Starting February 17th, 2026, three BRN fields will be required for all new toll-free verification submissions.

The following fields are required for all new toll-free verification requests:

businessRegistrationNumber
businessRegistrationType
businessRegistrationCountry

Submissions missing these fields will be rejected.

Why This Matters

U.S. wireless carriers require toll-free numbers (800, 888, 877, 866, 855, 844, 833) used for SMS/MMS to complete verification. The new BRN fields provide carriers with verified business identity information, helping to:

Reduce verification processing time
Improve approval rates
Ensure compliance with carrier policies
Prevent fraudulent messaging

New Business Registration Fields

Required Fields (February 17th, 2026)

businessRegistrationNumber

The official government-issued business registration identifier.

Property	Value
Type	String
Max Length	500 characters
Required	February 17th, 2026
Nullable	Currently yes, no after Feb 2026

Examples by Country:

Country	Type	Example Format
United States	EIN	`12-3456789` or `123456789`
Canada	Business Number	`123456789RC0001`
United Kingdom	Companies House	`12345678`
Australia	ABN	`51824753556`
Germany	VAT	`DE123456789`

Where to Find:

US: IRS EIN Lookup - Check your EIN confirmation letter or SS-4 form
Canada: CRA Business Number from your registration documents
UK: Companies House registration certificate
Australia: ABN Lookup
EU: VAT registration certificate from your national tax authority

businessRegistrationType

The type or classification of your business registration.

Property	Value
Type	String
Max Length	500 characters
Required	February 17, 2026
Nullable	Currently yes, no after Feb 2026

Common Values:

EIN - U.S. Employer Identification Number
CRA - Canadian Revenue Agency Business Number
Companies House - UK company registration
ABN - Australian Business Number
VAT - European Union VAT registration
SSN - For U.S. sole proprietors without EIN

businessRegistrationCountry

ISO 3166-1 alpha-2 country code of the authority that issued the registration.

Property	Value
Type	String
Length	Exactly 2 characters
Format	ISO 3166-1 alpha-2
Required	February 17, 2026
Nullable	Currently yes, no after Feb 2026

Validation:

Must be exactly 2 letters
Only alphabetic characters (A-Z)
Automatically converted to uppercase ("us" → "US")
Returns HTTP 400 if invalid

Example Values: US, CA, GB, AU, DE, FR, JP See complete list: ISO 3166-1 country codes

Optional Fields

These fields are optional but recommended for faster verification processing.

doingBusinessAs

DBA, trade name, or brand name if different from your legal business name.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: Legal name “Acme Corporation Inc.”, DBA “Acme Services”

entityType

Legal business entity classification.

Property	Value
Type	Enum
Required	No
Allowed Values	`SOLE_PROPRIETOR`, `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`

Value Descriptions:

Value	Description
`SOLE_PROPRIETOR`	Individual or sole proprietorship
`PRIVATE_PROFIT`	Private for-profit corporation (most common)
`PUBLIC_PROFIT`	Publicly traded for-profit company
`NON_PROFIT`	501(c) or charitable organization
`GOVERNMENT`	Government entity or agency

optInConfirmationResponse

Message sent to subscribers confirming their opt-in.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "You are now subscribed to Acme alerts. Reply STOP to unsubscribe. Msg&data rates may apply."

helpMessageResponse

Automated response when subscribers text HELP.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "Acme Support: Call 1-800-555-0123 or email help@acme.com. Reply STOP to unsubscribe."

privacyPolicyURL

URL to your business privacy policy.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "https://www.acme.com/privacy"

termsAndConditionURL

URL to your business terms and conditions.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "https://www.acme.com/terms"

ageGatedContent

Indicates if messaging content requires age verification (18+ or 21+).

Property	Value
Type	Boolean
Default	`false`
Required	No

Set to true for alcohol, tobacco, cannabis, or other age-restricted content.

optInKeywords

Keywords subscribers use to opt-in to your messaging program.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "START, YES, SUBSCRIBE, JOIN"

API Usage

Create Verification Request with BRN Fields

Endpoint: POST /public/api/v2/requests Request with BRN Fields:

curl --request POST \
  --url https://api.telnyx.com/v2/messaging_tollfree/verification/requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "businessName": "Telnyx LLC",
  "corporateWebsite": "http://example.com",
  "businessAddr1": "600 Congress Avenue",
  "businessAddr2": "14th Floor",
  "businessCity": "Austin",
  "businessState": "Texas",
  "businessZip": "78701",
  "businessContactFirstName": "John",
  "businessContactLastName": "Doe",
  "businessContactEmail": "email@example.com",
  "businessContactPhone": "+18005550100",
  "messageVolume": "100,000",
  "phoneNumbers": [
    {
      "phoneNumber": "+18773554398"
    },
    {
      "phoneNumber": "+18773554399"
    }
  ],
  "useCase": "2FA",
  "useCaseSummary": "This is a use case where Telnyx sends out 2FA codes to portal users to verify their identity in order to sign into the portal",
  "productionMessageContent": "Your Telnyx OTP is XXXX",
  "optInWorkflow": "User signs into the Telnyx portal, enters a number and is prompted to select whether they want to use 2FA verification for security purposes. If they'\''ve opted in a confirmation message is sent out to the handset",
  "optInWorkflowImageURLs": [
    {
      "url": "https://telnyx.com/sign-up"
    },
    {
      "url": "https://telnyx.com/company/data-privacy"
    }
  ],
  "additionalInformation": "<string>",
  "isvReseller": "Yes",
  "webhookUrl": "http://example-webhook.com",
  "businessRegistrationNumber": "12-3456789",
  "businessRegistrationType": "EIN",
  "businessRegistrationCountry": "US",
  "doingBusinessAs": "Acme Services",
  "entityType": "SOLE_PROPRIETOR",
  "optInConfirmationResponse": "You have successfully opted in to receive messages from Acme Corp",
  "helpMessageResponse": "Reply HELP for assistance or STOP to unsubscribe. Contact: support@example.com",
  "privacyPolicyURL": "https://example.com/privacy",
  "termsAndConditionURL": "https://example.com/terms",
  "ageGatedContent": false,
  "optInKeywords": "START, YES, SUBSCRIBE"
}'

Response (HTTP 201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verificationRequestId": "TFV-ABC123",
  "verificationStatus": "Pending",
  "businessName": "Acme Corporation",
  "businessRegistrationNumber": "12-3456789",
  "businessRegistrationType": "EIN",
  "businessRegistrationCountry": "US",
  "entityType": "PRIVATE_PROFIT",
  "createdAt": "2025-10-13T12:00:00Z"
}

Retrieve Verification with BRN Fields

Endpoint: GET /public/api/v2/requests/{id}

curl -X GET https://api.telnyx.com/public/api/v2/requests/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (HTTP 200):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verificationRequestId": "TFV-ABC123",
  "verificationStatus": "Approved",
  "businessName": "Acme Corporation",
  "businessRegistrationNumber": "12-3456789",
  "businessRegistrationType": "EIN",
  "businessRegistrationCountry": "US",
  "entityType": "PRIVATE_PROFIT",
  "phoneNumbers": [{"phoneNumber": "+18773554398"}],
  "createdAt": "2025-10-13T12:00:00Z",
  "updatedAt": "2025-10-15T09:30:00Z"
}

Update BRN Fields

Endpoint: PATCH /public/api/v2/requests/{id}

curl -X PATCH https://api.telnyx.com/public/api/v2/requests/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessRegistrationNumber": "98-7654321",
    "businessRegistrationCountry": "US"
  }'

Code Examples

Python

import requests

# Create verification with BRN fields
payload = {
    "businessName": "Acme Corporation",
    "corporateWebsite": "https://www.acme.com",
    "businessAddr1": "123 Main Street",
    "businessCity": "Chicago",
    "businessState": "Illinois",
    "businessZip": "60601",
    "businessContactFirstName": "John",
    "businessContactLastName": "Doe",
    "businessContactEmail": "compliance@acme.com",
    "businessContactPhone": "+18005551234",
    "messageVolume": "100,000",
    "phoneNumbers": [{"phoneNumber": "+18773554398"}],
    "useCase": "Account Notifications",
    "useCaseSummary": "Security alerts and account updates",
    "productionMessageContent": "Your Acme security code is: 123456",
    "optInWorkflow": "Users opt-in during registration",
    "optInWorkflowImageURLs": [{"url": "https://www.acme.com/opt-in.png"}],
    "additionalInformation": "Messages to verified numbers only",
    "isvReseller": "Yes",

    # BRN Fields (required Feb 2026)
    "businessRegistrationNumber": "12-3456789",
    "businessRegistrationType": "EIN",
    "businessRegistrationCountry": "US",
    "entityType": "PRIVATE_PROFIT"
}

response = requests.post(
    "https://api.telnyx.com/public/api/v2/requests",
    json=payload,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 201:
    data = response.json()
    print(f"Verification created: {data['verificationRequestId']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

JavaScript/TypeScript

interface TollFreeVerificationRequest {
  businessName: string;
  corporateWebsite: string;
  businessAddr1: string;
  businessCity: string;
  businessState: string;
  businessZip: string;
  businessContactFirstName: string;
  businessContactLastName: string;
  businessContactEmail: string;
  businessContactPhone: string;
  messageVolume: string;
  phoneNumbers: Array<{ phoneNumber: string }>;
  useCase: string;
  useCaseSummary: string;
  productionMessageContent: string;
  optInWorkflow: string;
  optInWorkflowImageURLs: Array<{ url: string }>;
  additionalInformation?: string;
  isvReseller: string;

  // BRN Fields (required Feb 2026)
  businessRegistrationNumber: string;
  businessRegistrationType: string;
  businessRegistrationCountry: string;
  entityType?: 'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT';
}

async function createVerification(request: TollFreeVerificationRequest, apiKey: string) {
  const response = await fetch('https://api.telnyx.com/public/api/v2/requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(request)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Verification failed: ${JSON.stringify(error)}`);
  }

  return response.json();
}

// Example usage
const request: TollFreeVerificationRequest = {
  businessName: "Acme Corporation",
  corporateWebsite: "https://www.acme.com",
  businessAddr1: "123 Main Street",
  businessCity: "Chicago",
  businessState: "Illinois",
  businessZip: "60601",
  businessContactFirstName: "John",
  businessContactLastName: "Doe",
  businessContactEmail: "compliance@acme.com",
  businessContactPhone: "+18005551234",
  messageVolume: "100,000",
  phoneNumbers: [{ phoneNumber: "+18773554398" }],
  useCase: "Account Notifications",
  useCaseSummary: "Security alerts and account updates",
  productionMessageContent: "Your code is: 123456",
  optInWorkflow: "Users opt-in during registration",
  optInWorkflowImageURLs: [{ url: "https://www.acme.com/opt-in.png" }],
  additionalInformation: "More context";
  isvReseller: "Yes";
  businessRegistrationNumber: "12-3456789",
  businessRegistrationType: "EIN",
  businessRegistrationCountry: "US",
  entityType: "PRIVATE_PROFIT"
};

createVerification(request, 'YOUR_API_KEY')
  .then(result => console.log('Created:', result.verificationRequestId))
  .catch(error => console.error('Error:', error.message));

Error Handling

Validation Errors (HTTP 400)

Missing Required Fields (After February 2026)

Response:

{
  "errors": [
    {
      "field": "businessRegistrationNumber",
      "message": "This field is required as of February 17th 2026"
    },
    {
      "field": "businessRegistrationType",
      "message": "This field is required as of February 17th 2026"
    },
    {
      "field": "businessRegistrationCountry",
      "message": "This field is required as of February 17th 2026"
    }
  ]
}

Invalid Country Code

{
  "detail": "businessRegistrationCountry must be a 2-character ISO 3166-1 alpha-2 country code"
}

Invalid Entity Type

{
  "detail": "entityType must be one of: SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT"
}

Other Status Codes

Code	Description
200	Success (GET, PATCH)
201	Created (POST)
204	Deleted (DELETE)
400	Bad Request - Invalid data
401	Unauthorized - Invalid API key
404	Not Found - Invalid request ID
422	Unprocessable Entity - Invalid format

Migration Guide

Timeline

Period	Status	Action
Now - Dec 2025	Optional	BRN fields can be included but not required
Feb 1, 2026	Mandatory	All 3 required BRN fields must be included

Preparation Steps

1. Gather Business Registration Information Locate your:

Business registration number (EIN, VAT, ABN, etc.)
Registration type identifier
Issuing country code

2. Update Your Integration Add BRN fields to your API requests:

  const request = {
    businessName: "Acme Corp",
    corporateWebsite: "https://acme.com",
    // ... other required fields
+   businessRegistrationNumber: "12-3456789",
+   businessRegistrationType: "EIN",
+   businessRegistrationCountry: "US"
  };

3. Test Your Implementation

Submit test requests with BRN fields
Verify fields are returned in responses
Test validation error handling
Confirm country code uppercase conversion

4. Update Error Handling Prepare for validation errors after February 2026:

try {
  const result = await createVerification(request);
} catch (error) {
  if (error.status === 400) {
    console.error('Validation failed:', error.errors);
    // Handle missing BRN fields
  }
}

Backward Compatibility

Until February 17, 2026:

Requests without BRN fields continue to work
No breaking changes to existing integrations
BRN fields default to null if not provided

After February 17, 2026:

Requests without 3 required BRN fields will be rejected (HTTP 400)
Update your integration before this date

Frequently Asked Questions

When do BRN fields become mandatory?

February 17th, 2026. All new verification requests must include businessRegistrationNumber, businessRegistrationType, and businessRegistrationCountry.

Do I need to resubmit existing verifications?

No. Approved verifications before February 2026 remain valid.

Where do I find my business registration number?

US: IRS EIN confirmation letter or IRS.gov
Canada: CRA Business Number registration documents
UK: Companies House certificate
Australia: ABN Lookup
EU: VAT registration certificate

What if I’m a sole proprietor without an EIN?

U.S. sole proprietors can use their Social Security Number as businessRegistrationNumber with type SSN. Other countries may have similar individual tax identifiers.

Can I update BRN fields after submission?

Yes. Use PATCH /public/api/v2/requests/{id} to update BRN fields.

Why are country codes converted to uppercase?

For consistency. Sending "us" automatically becomes "US" in responses and storage.

Which entity type should I choose?

Choose the type matching your official business registration:

SOLE_PROPRIETOR - Individual or sole proprietorship
PRIVATE_PROFIT - Private corporation (most common)
PUBLIC_PROFIT - Publicly traded company
NON_PROFIT - 501(c) or charitable organization
GOVERNMENT - Government entity

How long does toll-free verification take?

Verification typically takes 1-2 weeks, depending on the carrier review queue and the completeness of your submission. Including accurate BRN fields can speed up the process.

What happens if my verification is rejected?

You’ll receive a webhook notification with the rejection reason. Common causes:

Incomplete or inaccurate business information
Message samples don’t match your declared use case
Missing opt-out language in sample messages
Business couldn’t be verified with the provided registration number

Fix the issues and resubmit — there’s no limit on resubmissions.

Can I send messages before verification is complete?

Unverified toll-free numbers have limited throughput and may experience carrier filtering. Complete verification to unlock full sending capabilities (up to 20 MPS).

What’s the difference between toll-free verification and 10DLC registration?

Aspect	Toll-Free Verification	10DLC Registration
Number type	Toll-free (800, 888, etc.)	Local 10-digit numbers
Timeline	1-2 weeks	Days (plus 1-7 days for vetting)
Registry	Carrier-managed	The Campaign Registry (TCR)
Throughput	Up to 20 MPS	Varies by vetting score
Cost	Per-message	Per-message + campaign fees

Toll-Free Verification API

API reference for managing toll-free verification requests.

Messaging API

Send messages from your verified toll-free numbers.

10DLC Registration

Alternative registration path for local 10-digit numbers.

Advanced Opt-In/Out

Configure opt-in/out behavior including toll-free specific handling.

Support

Need help with toll-free verification?

Support Portal: support.telnyx.com
Email: support@telnyx.com
Developer Community: Join discussions and get help from other developers

​Why This Matters

​New Business Registration Fields

​Required Fields (February 17th, 2026)

​businessRegistrationNumber

​businessRegistrationType

​businessRegistrationCountry

​Optional Fields

​doingBusinessAs

​entityType

​optInConfirmationResponse

​helpMessageResponse

​privacyPolicyURL

​termsAndConditionURL

​ageGatedContent

​optInKeywords

​API Usage

​Create Verification Request with BRN Fields

​Retrieve Verification with BRN Fields

​Update BRN Fields

​Code Examples

​Python

​JavaScript/TypeScript

​Error Handling

​Validation Errors (HTTP 400)

​Missing Required Fields (After February 2026)

​Invalid Country Code

​Invalid Entity Type

​Other Status Codes

​Migration Guide

​Timeline

​Preparation Steps

​Backward Compatibility

​Frequently Asked Questions

​When do BRN fields become mandatory?

​Do I need to resubmit existing verifications?

​Where do I find my business registration number?

​What if I’m a sole proprietor without an EIN?

​Can I update BRN fields after submission?

​Why are country codes converted to uppercase?

​Which entity type should I choose?

​How long does toll-free verification take?

​What happens if my verification is rejected?

​Can I send messages before verification is complete?

​What’s the difference between toll-free verification and 10DLC registration?

​Related resources

Toll-Free Verification API

Messaging API

10DLC Registration

Advanced Opt-In/Out

​Support

Why This Matters

New Business Registration Fields

Required Fields (February 17th, 2026)

businessRegistrationNumber

businessRegistrationType

businessRegistrationCountry

Optional Fields

doingBusinessAs

entityType

optInConfirmationResponse

helpMessageResponse

privacyPolicyURL

termsAndConditionURL

ageGatedContent

optInKeywords

API Usage

Create Verification Request with BRN Fields

Retrieve Verification with BRN Fields

Update BRN Fields

Code Examples

Python

JavaScript/TypeScript

Error Handling

Validation Errors (HTTP 400)

Missing Required Fields (After February 2026)

Invalid Country Code

Invalid Entity Type

Other Status Codes

Migration Guide

Timeline

Preparation Steps

Backward Compatibility

Frequently Asked Questions

When do BRN fields become mandatory?

Do I need to resubmit existing verifications?

Where do I find my business registration number?

What if I’m a sole proprietor without an EIN?

Can I update BRN fields after submission?

Why are country codes converted to uppercase?

Which entity type should I choose?

How long does toll-free verification take?

What happens if my verification is rejected?

Can I send messages before verification is complete?

What’s the difference between toll-free verification and 10DLC registration?

Related resources

Support