Skip to main content

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 January 1, 2026, three BRN fields will be required for all new toll-free verification submissions.

Policy Update: January 1, 2026

Beginning January 1, 2026, 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 (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 help@acme.com. Reply STOP to unsubscribe."

privacyPolicyURL ​

URL to your business privacy policy.

PropertyValue
TypeString
Max Length500 characters
RequiredNo

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

note

URL format validation is not enforced. Provide a publicly accessible URL.

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 -X POST https://api.telnyx.com/public/api/v2/requests \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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": "Account security alerts and transaction confirmations",
    "productionMessageContent": "Acme Alert: Your password was changed on Dec 15.",
    "optInWorkflow": "Users opt-in during account registration",
    "optInWorkflowImageURLs": [{"url": "https://www.acme.com/opt-in.png"}],
    "additionalInformation": "Messages sent to verified phone numbers only",
    "businessRegistrationNumber": "12-3456789",
    "businessRegistrationType": "EIN",
    "businessRegistrationCountry": "US",
    "entityType": "PRIVATE_PROFIT"
  }'

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",

    # 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;

  // 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: "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" }],

  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