Skip to main content
Telnyx toll-free verification now supports Business Registration Number (BRN) fields to strengthen business verification and compliance. Starting January 1, 2026, three BRN fields will be required for all new toll-free verification submissions.

​
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 (January 1, 2026)

​
businessRegistrationNumber

The official government-issued business registration identifier.
PropertyValue
TypeString
Max Length500 characters
RequiredJanuary 1, 2026
NullableCurrently yes, no after Jan 2026
Examples by Country:
CountryTypeExample Format
United StatesEIN12-3456789 or 123456789
CanadaBusiness Number123456789RC0001
United KingdomCompanies House12345678
AustraliaABN51824753556
GermanyVATDE123456789
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.
PropertyValue
TypeString
Max Length500 characters
RequiredJanuary 1, 2026
NullableCurrently yes, no after Jan 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.
PropertyValue
TypeString
LengthExactly 2 characters
FormatISO 3166-1 alpha-2
RequiredJanuary 1, 2026
NullableCurrently yes, no after Jan 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.
PropertyValue
TypeString
Max Length500 characters
RequiredNo
Example: Legal name “Acme Corporation Inc.”, DBA “Acme Services”

​
entityType

Legal business entity classification.
PropertyValue
TypeEnum
RequiredNo
Allowed ValuesSOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT
Value Descriptions:
ValueDescription
SOLE_PROPRIETORIndividual or sole proprietorship
PRIVATE_PROFITPrivate for-profit corporation (most common)
PUBLIC_PROFITPublicly traded for-profit company
NON_PROFIT501(c) or charitable organization
GOVERNMENTGovernment entity or agency

​
optInConfirmationResponse

Message sent to subscribers confirming their opt-in.
PropertyValue
TypeString
Max Length500 characters
RequiredNo
Example: "You are now subscribed to Acme alerts. Reply STOP to unsubscribe. Msg&data rates may apply."

​
helpMessageResponse

Automated response when subscribers text HELP.
PropertyValue
TypeString
Max Length500 characters
RequiredNo
Example: "Acme Support: Call 1-800-555-0123 or email [email protected]. Reply STOP to unsubscribe."

​
privacyPolicyURL

URL to your business privacy policy.
PropertyValue
TypeString
Max Length500 characters
RequiredNo
Example: "https://www.acme.com/privacy"

​
termsAndConditionURL

URL to your business terms and conditions.
PropertyValue
TypeString
Max Length500 characters
RequiredNo
Example: "https://www.acme.com/terms"

​
ageGatedContent

Indicates if messaging content requires age verification (18+ or 21+).
PropertyValue
TypeBoolean
Defaultfalse
RequiredNo
Set to true for alcohol, tobacco, cannabis, or other age-restricted content.

​
optInKeywords

Keywords subscribers use to opt-in to your messaging program.
PropertyValue
TypeString
Max Length500 characters
RequiredNo
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 protected]",
  "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: [email protected]",
  "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": "[email protected]",
    "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 Jan 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 Jan 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: "[email protected]",
  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 January 2026)

Response: 
{
  "errors": [
    {
      "field": "businessRegistrationNumber",
      "message": "This field is required as of January 2026"
    },
    {
      "field": "businessRegistrationType",
      "message": "This field is required as of January 2026"
    },
    {
      "field": "businessRegistrationCountry",
      "message": "This field is required as of January 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

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

​
Migration Guide

​
Timeline

PeriodStatusAction
Now - Dec 2025OptionalBRN fields can be included but not required
Jan 1, 2026MandatoryAll 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 January 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 January 1, 2026:
  • Requests without BRN fields continue to work
  • No breaking changes to existing integrations
  • BRN fields default to null if not provided
After January 1, 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?

January 1, 2026. All new verification requests must include businessRegistrationNumber, businessRegistrationType, and businessRegistrationCountry.

​
Do I need to resubmit existing verifications?

No. Approved verifications before January 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

​
Additional Resources

​
Support

Need help with toll-free verification?
Last Updated: October 2025 API Version: v2