---
title: "Buy a toll-free number as an SMS inbox and ask carriers to approve it with the business's details. It receives texts at once and sends once carriers approve, usually within a few days. It texts the US and Canada only."
method: POST
path: "/v1/workspaces/{workspaceId}/mailboxes/sms/numbers"
---

# Buy a toll-free number as an SMS inbox and ask carriers to approve it with the business's details. It receives texts at once and sends once carriers approve, usually within a few days. It texts the US and Canada only.

`POST /v1/workspaces/{workspaceId}/mailboxes/sms/numbers`

## Request

- Base URL: `https://api.bangermail.com`
- URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/mailboxes/sms/numbers`
- Auth: HTTP bearer

## Request body

- object
  - `phone_number` string, required
  - `display_name` string
  - `business` object, required
    - `legal_name` string, required
    - `website` string, required
    - `type` 'private_profit' | 'public_profit' | 'sole_proprietor' | 'non_profit' | 'government', required
    - `registration_number` string: EIN in the US
    - `country` 'US' | 'CA', required
    - `street` string, required
    - `street2` string
    - `city` string, required
    - `region` string, required
    - `postal_code` string, required
    - `contact_first_name` string, required
    - `contact_last_name` string, required
    - `contact_email` string, required
    - `contact_phone` string, required
    - `opt_in_url` string, required: The page where customers find this number.
    - `use_case_summary` string
    - `message_sample` string

## Response `201`

The SMS inbox, pending until carriers approve the number.

- object
  - `data` Mailbox, required
    - `id` string, uuid, required
    - `workspace_id` string, uuid, required
    - `product_id` string, uuid, nullable: The product (project) the mailbox belongs to. Clients group mailboxes and build web-app links with it.
    - `domain_id` string, uuid, nullable
    - `address` string, required: The email address, or for an SMS inbox its phone number in E.164 (+15551234567).
    - `display_name` string, required
    - `provider` 'gmail' | 'smtp' | 'twilio', required
    - `channel` 'email' | 'sms' | 'whatsapp': email; sms for an SMS inbox on Twilio; whatsapp for a WhatsApp inbox, a WhatsApp sender on Twilio for the business's WhatsApp Business account.
    - `sms_verification` object, nullable: A number from Banger, carriers' answer on its toll-free verification. It sends once approved; null for every other mailbox.
      - `status` 'pending_review' | 'in_review' | 'approved' | 'rejected'
      - `reason` string, nullable: Carriers' reason when rejected.
    - `status` 'pending' | 'active' | 'suspended' | 'reconnect_required' | 'disabled', required
    - `status_reason` string, nullable
    - `suspended_at` string, nullable
    - `mailbox_kind` 'domain' | 'starter', required

## Other responses

- `400`: The business details are incomplete
- `402`: A number from Banger comes with a paid plan.
- `409`: Someone else just took that number.
- `503`: Numbers from Banger aren't available yet.

---

[API](https://skmtc.dev/bangermail/apis/banger-api.md) · [All operations](https://skmtc.dev/bangermail/apis/banger-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bangermail/apis/banger-api/revisions/a149909267f9?raw)