# Refresh a toll-free verification request's status (/docs/api/routing/toll-free-verification/refreshTfvRequest)

> 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/refresh/{tfvRequestId}`

Refresh a toll-free verification request's status

Ask the carrier for this request's current status and write it back immediately, rather than waiting for the periodic check Tandem already runs on every pending request. Each pending number's smsCapability updates to match: enabled once verified, disabled if denied.

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

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tfvRequestId` | string | Yes | The toll-free verification request's unique ID. |

## Responses

### 200 — The request, with its latest status.

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 | — |

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

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

### 404 — The resource does not exist.

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