---
title: "Create an SMS brand"
description: "Create a brand: the business identity carriers register before they approve a number. `POST /api/v1/sms/brands`"
url: https://www.unitpost.com/docs/sms/post-sms-brands
section: "SMS API reference"
updated: 2026-10-13
---
# Create an SMS brand

`POST /api/v1/sms/brands`

Create a brand: the business identity carriers register before they approve a number. A draft may be partial (only `name` is required); `missing` says what is still needed. Free, with no carrier call; one brand per website domain (`409`). The tax id is write-only (stored encrypted, read back as `tax_id_on_file`). Registering the brand with carriers is a paid order (an SMS quote, then its confirm). Pass an `Idempotency-Key` so a retry never makes a second brand. Requires the `sms:manage` capability.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Any unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`. |

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The brand name recipients see. |
| `website` | string \| null | no | The brand's website; a bare host gets https://. |
| `contact_email` | string \| null | no | An address on the website's domain (carriers check). |
| `sender_id_name` | string \| null | no | The one Sender ID the brand sends under abroad: 1–11 letters, digits or hyphens, with a letter. |
| `vertical` | string \| null | no | The industry, in the carriers' words (e.g. `RETAIL`). |
| `legal_name` | string \| null | no | The exact registered legal name. |
| `dba_name` | string \| null | no | — |
| `legal_organization_type` | string \| null | no | `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, … |
| `tax_id` | string | no | The company tax id (EIN in the US). Write-only: stored encrypted, read back as `tax_id_on_file`; it can be replaced, not removed. |
| `registration_number_type` | string \| null | no | — |
| `tax_country` | string \| null | no | Two-letter ISO country code. |
| `stock_symbol` | string \| null | no | — |
| `stock_exchange` | string \| null | no | — |
| `contact` | object | no | — |
| `address` | object | no | — |

## Response fields (201)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | — |
| `id` | string | yes | Prefixed brand id, e.g. `sbrand_…`. |
| `name` | string | yes | Public-facing brand name. |
| `legal_name` | string | yes | Registered legal entity name. |
| `website` | string \| null | yes | Brand website URL. |
| `domain` | string \| null | yes | Registrable domain derived from the website. The brand contact email must be on this domain. |
| `contact_email` | string \| null | yes | — |
| `status` | enum | yes | `incomplete` and `action_required` need the customer to act in the dashboard; `pending` is waiting on the carrier. One of: `incomplete`, `ready`, `pending`, `action_required`, `verified`, `rejected`, `archived`. |
| `missing` | string[] | yes | Human-readable list of what is still required before this brand can back a number. Empty when nothing is missing. |
| `ten_dlc_verified` | boolean | yes | True when the 10DLC brand registration is approved. |
| `tax_id_on_file` | boolean | yes | — |
| `number_count` | integer | yes | Non-released senders on this brand (phone numbers and Sender ID countries, any status). |
| `editable` | boolean | yes | False once the brand is locked: carriers approved or are reviewing its 10DLC registration, or senders are registered with its details. Locked brands are corrected only when carriers ask. |
| `dba_name` | string \| null | no | The name the business trades under, when it isn't the legal name. |
| `sender_id_name` | string \| null | no | The one Sender ID the brand sends under abroad (1–11 characters). |
| `vertical` | string \| null | no | The brand's industry, in the carriers' words (e.g. `RETAIL`). |
| `legal_organization_type` | string \| null | no | `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, … |
| `registration_number_type` | string \| null | no | — |
| `tax_country` | string \| null | no | — |
| `stock_symbol` | string \| null | no | — |
| `stock_exchange` | string \| null | no | — |
| `contact` | object | no | Who carriers reach about the brand (the email is `contact_email`). |
| `address` | object | no | The registered business address. |
| `revision` | integer | no | Moves on every material change; a registration keeps the revision it was submitted with. |
| `archived_at` | string \| null | no | — |
| `created_at` | string | yes | — |

## Responses

| Status | Description |
| --- | --- |
| 201 | The brand. |
| 400 | The body isn't JSON, or the `Idempotency-Key` header is not 1–256 characters. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope, or SMS is not on this plan (`limit_reached`). |
| 404 | SMS is not enabled for this workspace. |
| 409 | Another brand uses that website's domain, or the `Idempotency-Key` is in use. |
| 422 | A field the carriers would refuse (named in `details`), no `name`, or an unknown key. |
| 429 | Too many brand changes; honor Retry-After. |
| 503 | A tax id can't be stored on this deployment yet (no encryption key); nothing was saved. |

## Example request

```bash
curl -X POST 'https://www.unitpost.com/api/v1/sms/brands' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
```

## Example response (201)

```json
{
  "object": "sms_brand",
  "id": "id_123",
  "name": "Example",
  "legal_name": "string",
  "website": "string",
  "domain": "string",
  "contact_email": "string",
  "status": "incomplete",
  "missing": [
    "string"
  ],
  "ten_dlc_verified": false,
  "tax_id_on_file": false,
  "number_count": 1,
  "editable": false,
  "dba_name": "string",
  "sender_id_name": "string",
  "vertical": "string",
  "legal_organization_type": "string",
  "registration_number_type": "string",
  "tax_country": "string",
  "stock_symbol": "string",
  "stock_exchange": "string",
  "contact": {
    "first_name": "string",
    "last_name": "string",
    "phone": "string"
  },
  "address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "zip_code": "string",
    "iso_country_code": "string"
  },
  "revision": 0,
  "archived_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z"
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/sms/post-sms-brands
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json