> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pinnacle.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server.

# Toll-Free Campaigns

> Register toll-free messaging use cases and keep them carrier compliant.

Follow the sequence below to enable high-throughput toll-free messaging across the US.

⏱️ **Approval time:** Less than 10 minutes

## Prerequisites

* An approved `brandId` ([register one here](/guides/brands))
* Documented opt-in evidence
* Sample outbound message and contact details

## Step 1: Create or update the campaign

* Call [`POST /campaigns/toll-free`](/api-reference/campaigns/toll-free/upsert) with the brand, use case, consent flow, and compliance metadata.

> **Optional helpers**
>
> * [`POST /campaigns/toll-free/autofill`](/api-reference/campaigns/toll-free/autofill) fills in the campaign information based on the existing information for a campaign and its brand.
>
> * [`POST /campaigns/toll-free/validate`](/api-reference/campaigns/toll-free/validate) surfaces
>   formatting and campaign issues. Treat the response as guidance only; it never
>   blocks campaign submission but is intended to guide you.

## Step 2: Submit for carrier review

* Call [`POST /campaigns/toll-free/submit/{campaignId}`](/api-reference/campaigns/toll-free/submit) to submit the campaign for carrier review.

## Step 3: Watch review progress

* Pull the full record and its status with [`GET /campaigns/toll-free/{campaignId}`](/api-reference/campaigns/toll-free/get).
* Force a status refresh using [`GET /status/toll-free-campaign/{campaignId}`](/api-reference/status/toll-free-campaign).

## Step 4: Attach numbers and start sending messages

> **Note**
>
> If you don't have a number yet, follow our [phone numbers guide](/guides/purchase-phone-numbers) to purchase one.

Attach owned numbers to the campaign via [`POST /phone-numbers/attach-campaign`](/api-reference/phone-numbers/attach-campaign). Note that each toll-free number is carrier reviewed and thus takes more time.
In some cases, a number may fail to be attached to the campaign and you'll be asked to update the campaign and reattach the number.

* Processing time: 1-3 business days
* Status check: [`GET /status/toll-free-campaign/{campaignId}`](/api-reference/status/toll-free-campaign)

### Send messages

Start messaging with [`POST /messages/send/sms`](/api-reference/messages/send-sms) or [`POST /messages/send/mms`](/api-reference/messages/send-mms). While waiting for approval, you'll also be able to send test messages with our sandbox numbers. See our [sending messages guide](/guides/messages/sending#sending-from-a-number) for detailed instructions on sending messages.