---
title: "Update an SMS brand"
description: "Edit a brand: only the fields sent change (null clears an optional one), or send { archived } alone to archive or restore it. `PATCH /api/v1/sms/brands/{id}`"
url: https://www.unitpost.com/docs/sms/patch-sms-brands-id
section: "SMS API reference"
updated: 2026-10-13
---
# Update an SMS brand

`PATCH /api/v1/sms/brands/{id}`

Edit a brand: only the fields sent change (`null` clears an optional one), or send `{ archived }` alone to archive or restore it. A brand carriers are reviewing or have approved, or with numbers attached, refuses carrier-field edits (`409 brand_locked`, `details` names each field) except those a correction request opened. Renaming the Sender ID while it is enabled in several countries is a `409 sender_id_in_use`. Archiving a brand with numbers or open registrations is a `409 resource_in_use`. Requires the `sms:manage` capability.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | — |

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | no | 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 | — |
| `archived` | boolean | no | Archive (`true`) or restore (`false`) the brand; send it alone. |

## Response fields (200)

| 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 |
| --- | --- |
| 200 | The brand. |
| 400 | The body isn't JSON. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope. |
| 404 | Brand not found, or SMS is not enabled. |
| 409 | The brand is locked, archived, its Sender ID in use, or another brand uses the domain. |
| 422 | A field the carriers would refuse, `archived` with other fields, `tax_id: null`, nothing to change, 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 PATCH 'https://www.unitpost.com/api/v1/sms/brands/sms_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
```

## Example response (200)

```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/patch-sms-brands-id
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json