# Submit a toll-free verification request (/docs/api/routing/toll-free-verification/submitTfvRequest)

> For the complete documentation index, see [llms.txt](https://docs.tandemcx.ai/llms.txt). Any page on this site can be fetched as Markdown by appending `.md` to its URL.

`POST /v1/sms-registration/tfv`

Submit a toll-free verification request

Submit one business profile for up to 10 toll-free numbers at once. Every number must belong to your organization and be toll-free (NPA 800, 833, 844, 855, 866, 877, or 888); a local number, an unknown number, or a number already on a request is rejected. A number denied on an earlier request moves forward by resubmitting that request while the carrier takes it back. Once it won't (the number's resubmitAllowed is false, or 7 days have passed since its deniedAt), the number can go in a new submission instead: its old verification is withdrawn at the carrier first, and the number is taken off its old request. Until the carrier decides, each number's status is pending and its smsCapability stays pending.
A 400 with code TFV_REJECTED means the carrier refused the submission; its message gives the carrier's reasons, field by field where it names them.

## Request

**Base URL:** `https://api.tandemcx.ai`

**Authentication:** `Authorization: Bearer <token>` — A Tandem bearer token. Requests are scoped to the organization the token belongs to; no organization header is required.

### Body (`application/json`) — required

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `numberIds` | array of string | Yes | The toll-free numbers to submit together, up to 10. Each must belong to your organization and be toll-free. |
| `profile` | object | Yes | The business information a toll-free verification request carries. One profile applies to every number in the same request. |
| `profile.businessName` | string | Yes | The business's legal name. |
| `profile.businessDba` | string | No | Doing-business-as name, if different. |
| `profile.businessEntityType` | enum: `SOLE_PROPRIETOR` \| `PRIVATE_PROFIT` \| `PUBLIC_PROFIT` \| `NON_PROFIT` \| `GOVERNMENT` | Yes | The submitting business's legal structure. |
| `profile.businessRegistrationNumber` | string | No | e.g. an EIN. Required, with businessRegistrationType and businessRegistrationIssuingCountry, for every entity type except SOLE_PROPRIETOR. A SOLE_PROPRIETOR's three are not sent to the carrier. |
| `profile.businessRegistrationType` | enum (18 values): `EIN`, `CBN`, `NEQ`, `PROVINCIAL_NUMBER`, `CRN`, `VAT`, `ACN`, `ABN`, `BRN`, `SIREN`, `SIRET`, `NZBN`, … | No | What kind of number businessRegistrationNumber is. |
| `profile.businessRegistrationIssuingCountry` | string | No | The country that issued businessRegistrationNumber, as an ISO-3166-1 alpha-3 code such as USA. |
| `profile.businessAddress` | object | Yes | — |
| `profile.businessAddress.addressLine1` | string | Yes | — |
| `profile.businessAddress.addressLine2` | string | No | — |
| `profile.businessAddress.city` | string | Yes | — |
| `profile.businessAddress.state` | string | Yes | — |
| `profile.businessAddress.zip` | string | Yes | — |
| `profile.businessAddress.websiteUrl` | string | Yes | — |
| `profile.businessContact` | object | Yes | — |
| `profile.businessContact.firstName` | string | Yes | — |
| `profile.businessContact.lastName` | string | Yes | — |
| `profile.businessContact.email` | string | Yes | — |
| `profile.businessContact.phone` | string | Yes | E.164 format. |
| `profile.useCase` | string | Yes | One of the values GET /v1/sms-registration/use-cases returns. |
| `profile.useCaseSummary` | string | Yes | A sentence or two describing what these messages are for. |
| `profile.productionMessageContent` | string | Yes | A representative message customers actually receive. |
| `profile.estimatedMonthlyVolume` | integer | Yes | — |
| `profile.optIn` | object | Yes | — |
| `profile.optIn.description` | string | Yes | How customers agree to receive these messages. |
| `profile.optIn.images` | array of one of: object \| object | Yes | Screenshots showing where and how customers opt in. |
| `profile.optIn.confirmationResponse` | string | No | The confirmation message sent back after a customer opts in. |
| `profile.privacyPolicyUrl` | string | No | — |
| `profile.termsUrl` | string | No | — |
| `profile.additionalInformation` | string | No | — |

## Responses

### 201 — The created toll-free verification request.

A toll-free verification submission. status is derived from numbers: verified once every number on the request is verified, denied as soon as any one is, pending otherwise.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The request's unique ID. |
| `numbers` | array of object | Yes | — |
| `numbers[].numberId` | string | Yes | The phone number's ID. |
| `numbers[].phoneNumber` | string | Yes | The number in E.164 format. |
| `numbers[].status` | enum: `pending` \| `verified` \| `denied` | Yes | Where a toll-free verification is in carrier review. pending until the carrier decides; verified sets the number's smsCapability to enabled; denied sets it to disabled and makes the request eligible for resubmission. |
| `numbers[].denialReason` | string | No | Present only when status is denied. |
| `numbers[].resubmitAllowed` | boolean | No | Set on a denial when the carrier says whether this number can be resubmitted. false means a resubmit skips it. |
| `numbers[].deniedAt` | string (date-time) | No | When the carrier denied this number. A resubmit skips it 7 days after this. |
| `profile` | object | Yes | The business information a toll-free verification request carries. One profile applies to every number in the same request. |
| `profile.businessName` | string | Yes | The business's legal name. |
| `profile.businessDba` | string | No | Doing-business-as name, if different. |
| `profile.businessEntityType` | enum: `SOLE_PROPRIETOR` \| `PRIVATE_PROFIT` \| `PUBLIC_PROFIT` \| `NON_PROFIT` \| `GOVERNMENT` | Yes | The submitting business's legal structure. |
| `profile.businessRegistrationNumber` | string | No | e.g. an EIN. Required, with businessRegistrationType and businessRegistrationIssuingCountry, for every entity type except SOLE_PROPRIETOR. A SOLE_PROPRIETOR's three are not sent to the carrier. |
| `profile.businessRegistrationType` | enum (18 values): `EIN`, `CBN`, `NEQ`, `PROVINCIAL_NUMBER`, `CRN`, `VAT`, `ACN`, `ABN`, `BRN`, `SIREN`, `SIRET`, `NZBN`, … | No | What kind of number businessRegistrationNumber is. |
| `profile.businessRegistrationIssuingCountry` | string | No | The country that issued businessRegistrationNumber, as an ISO-3166-1 alpha-3 code such as USA. |
| `profile.businessAddress` | object | Yes | — |
| `profile.businessAddress.addressLine1` | string | Yes | — |
| `profile.businessAddress.addressLine2` | string | No | — |
| `profile.businessAddress.city` | string | Yes | — |
| `profile.businessAddress.state` | string | Yes | — |
| `profile.businessAddress.zip` | string | Yes | — |
| `profile.businessAddress.websiteUrl` | string | Yes | — |
| `profile.businessContact` | object | Yes | — |
| `profile.businessContact.firstName` | string | Yes | — |
| `profile.businessContact.lastName` | string | Yes | — |
| `profile.businessContact.email` | string | Yes | — |
| `profile.businessContact.phone` | string | Yes | E.164 format. |
| `profile.useCase` | string | Yes | One of the values GET /v1/sms-registration/use-cases returns. |
| `profile.useCaseSummary` | string | Yes | A sentence or two describing what these messages are for. |
| `profile.productionMessageContent` | string | Yes | A representative message customers actually receive. |
| `profile.estimatedMonthlyVolume` | integer | Yes | — |
| `profile.optIn` | object | Yes | — |
| `profile.optIn.description` | string | Yes | How customers agree to receive these messages. |
| `profile.optIn.images` | array of one of: object \| object | Yes | Screenshots showing where and how customers opt in. |
| `profile.optIn.confirmationResponse` | string | No | The confirmation message sent back after a customer opts in. |
| `profile.privacyPolicyUrl` | string | No | — |
| `profile.termsUrl` | string | No | — |
| `profile.additionalInformation` | string | No | — |
| `status` | enum: `pending` \| `verified` \| `denied` | Yes | Where a toll-free verification is in carrier review. pending until the carrier decides; verified sets the number's smsCapability to enabled; denied sets it to disabled and makes the request eligible for resubmission. |
| `createdAt` | string (date-time) | Yes | — |
| `updatedAt` | string (date-time) | Yes | — |

### 400 — The request was malformed.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | No | — |
| `error.code` | string | No | — |
| `error.message` | string | No | — |

### 401 — Missing, malformed, or expired bearer token.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | No | — |
| `error.code` | string | No | — |
| `error.message` | string | No | — |

### 409 — The request conflicts with the resource's current state — for example, a number is already on a toll-free verification request, or a resubmit was sent for a request that isn't denied.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | No | — |
| `error.code` | string | No | — |
| `error.message` | string | No | — |