> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Toll-Free Verification with Business Registration Fields

> New Business Registration Number (BRN) fields for toll-free SMS/MMS verification, including mandatory requirements starting February 2026.

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.

<Warning>
  The following fields are **required** for all new toll-free verification requests:

  * `businessRegistrationNumber`
  * `businessRegistrationType`
  * `businessRegistrationCountry`

  Submissions missing these fields will be rejected.
</Warning>

## 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](https://www.irs.gov/) - Check your EIN confirmation letter or SS-4 form
* **Canada**: CRA Business Number from your registration documents
* **UK**: [Companies House](https://www.gov.uk/get-information-about-a-company) registration certificate
* **Australia**: [ABN Lookup](https://abr.business.gov.au/)
* **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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

### 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"`

<info>
  URL format validation is not enforced. Provide a publicly accessible URL.
</info>

#### 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**:

```bash theme={null}
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):

```json theme={null}
{
  "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}`

```bash theme={null}
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):

```json theme={null}
{
  "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}`

```bash theme={null}
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

```python theme={null}
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

```typescript theme={null}
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**:

```json theme={null}
{
  "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

```json theme={null}
{
  "detail": "businessRegistrationCountry must be a 2-character ISO 3166-1 alpha-2 country code"
}
```

#### Invalid Entity Type

```json theme={null}
{
  "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:

```diff theme={null}
  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:

```javascript theme={null}
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](https://www.irs.gov/)
* **Canada**: CRA Business Number registration documents
* **UK**: [Companies House](https://www.gov.uk/get-information-about-a-company) certificate
* **Australia**: [ABN Lookup](https://abr.business.gov.au/)
* **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      |

## Related resources

<CardGroup cols={2}>
  <Card title="Toll-Free Verification API" icon="code" href="/api-reference/verification-requests/list-verification-requests">
    API reference for managing toll-free verification requests.
  </Card>

  <Card title="Messaging API" icon="paper-plane" href="/api-reference/messages/send-a-message">
    Send messages from your verified toll-free numbers.
  </Card>

  <Card title="10DLC Registration" icon="signal" href="/docs/messaging/10dlc/quickstart/index">
    Alternative registration path for local 10-digit numbers.
  </Card>

  <Card title="Advanced Opt-In/Out" icon="toggle-on" href="/docs/messaging/messages/advanced-opt-in-out/index">
    Configure opt-in/out behavior including toll-free specific handling.
  </Card>
</CardGroup>

## Support

Need help with toll-free verification?

* **Support Portal**: [support.telnyx.com](https://support.telnyx.com)
* **Email**: [support@telnyx.com](mailto:support@telnyx.com)
* **Developer Community**: Join discussions and get help from other developers