# Update an allocated number

`PATCH /v1/numbers/{number_id}`

Updates the name and reference for a number allocated to your workspace. Omit a field to keep its current value, or send null to clear it. Leading and trailing whitespace is removed. References need not be unique.

## Code samples

**TypeScript**

```ts
const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);
```

Examples: [TypeScript](/docs/api/reference/update-workspace-number.ts.md) · [Python](/docs/api/reference/update-workspace-number.py.md) · [Go](/docs/api/reference/update-workspace-number.go.md) · [PHP](/docs/api/reference/update-workspace-number.php.md) · [CLI](/docs/api/reference/update-workspace-number.cli.md) · [MCP](/docs/api/reference/update-workspace-number.mcp.md) · [cURL](/docs/api/reference/update-workspace-number.curl.md)

## Example response `200`

```json
{
  "id": "nda_01krdgeqcxet5s7t44vh8rt9mg",
  "kind": "dedicated",
  "country_code": "US",
  "number_type": "mobile",
  "capabilities": [
    "sms"
  ],
  "status": "active",
  "ownership": {
    "submission_id": "csb_01krdgeqcxet5s7t44vh8rt9mg",
    "status": "needs_input",
    "next": [
      {
        "kind": "operation"
      }
    ]
  }
}
```

## Path parameters

- `number_id` (string): Identifier returned by the allocated-number list.

## Request body

- `name` (nullable string): A name for this number in your workspace, such as Support line. Send null to clear it, or omit it to keep the current name.
- `reference` (nullable string): Your own reference for this number, such as an identifier from your records. References need not be unique. Send null to clear it, or omit it to keep the current reference.

## Response body

- `name` (nullable string, required): The name you gave this number in your workspace. Null when no name is set.
- `reference` (nullable string, required): Your own reference for this number in your workspace. Null when no reference is set.
- `id` (string, required): Identifier of this allocated number. Pass it as `number_id` to read this number, or to release it when kind is dedicated.
- `kind` (string, required)

  How this number is allocated. `dedicated` belongs to your workspace and is billed as a subscription. `shared` is provided through Bird-managed shared infrastructure and is not owned or billed as a workspace subscription.

  Possible values: `dedicated`, `shared`
- `number` (string, required): Phone number in E.164 format.
- `country_code` (string, required)
- `number_type` (string, required): Physical type of this phone number.
- `capabilities` (array of string, required): Capabilities supported by this number.
- `status` (string, required)

  The allocation and ownership-approval status of this number.

  - `active` means this number is allocated to your workspace and usable.
  - `pending_ownership_registration` means this number is allocated to your workspace and billed,
    but outbound SMS and both inbound and outbound voice calls are blocked until ownership registration
    is approved and activation completes, or the ownership requirement is withdrawn.
    This ownership status does not gate inbound SMS or WhatsApp.
    Read `ownership.status` and `ownership.next` for the current decision and remaining work.
  - `released` means this number is no longer allocated to your workspace.

  An allocated number is not always enough to send from it: some destination
  countries also require an approved registration for the sender.

  Possible values: `active`, `pending_ownership_registration`, `released`
- `allocated_at` (string, required): When this number was allocated to your workspace.
- `released_at` (nullable string): When this number was released. `null` while it is still allocated to your workspace.
- `ownership` (nullable object): Ownership paperwork and activation progress. `null` when no ownership requirements, recorded block, or recorded decision apply, or when requirements or progress cannot be read and no ownership block or decision has been recorded. A recorded block still returns an ownership object with `status: unknown` when progress cannot be read; retry the read. We manage the paperwork for shared short codes, so this field is always `null` for them. Other sending requirements can apply even when ownership registration is complete.
- `ownership.submission_id` (string): The most recent ownership submission for this number, including after approval. Users with compliance read access can view the filed answers and their review status from the number's details in the dashboard. This may be a newer filing than the one that cleared the number for use. Absent when no submission was found or submission progress could not be read.
- `ownership.satisfied` (boolean, required): Whether the ownership paperwork is accepted or is no longer required. This can remain true while an external verifier asks for a correction or activation is pending. Read `status` and `next` for the current step, and `blocked_at` for the ownership block on outbound SMS and inbound and outbound voice.
- `ownership.status` (string, required)

  Current ownership registration approval status. Operational activation is separate:
  `blocked_at` records the ownership block on number use, and `next` describes remaining work.

  - `needs_input` means ownership details or a submission correction are needed.
  - `under_review` means your current answers are being reviewed.
  - `approval_pending` means your paperwork is accepted but registration approval is still pending.
  - `approved` means ownership registration is approved. Number activation can still be pending while `blocked_at` is non-null.
  - `not_required` means no active ownership requirement applies, including after a requirement is withdrawn.
  - `rejected` means the submission was closed or the verifier correction deadline passed. Corrections are no longer accepted for this submission.
  - `unknown` means current approval status could not be determined. Read `blocked_at` for any recorded ownership block. Retry the read.

  Possible values: `needs_input`, `under_review`, `approval_pending`, `approved`, `not_required`, `rejected`, `unknown`
- `ownership.blocked_at` (nullable string): When ownership requirements began blocking outbound SMS and inbound and outbound voice calls. Null when that block is clear. Accepted paperwork can still await activation with a block in place. A number bought before ownership requirements were introduced can have outstanding paperwork without a block.
- `ownership.next` (array of object, required): Actions that advance ownership registration or activation, in order. Empty when neither needs further action. A `wait` step means no customer action is needed now, including while accepted paperwork awaits activation. Read this list again after each change.
- `ownership.next.kind` (string, required)

  What you do about this step.

  - `operation`: call the operation named in `operation`, then
    read again.
  - `external`: act somewhere this API does not reach, then read
    again.
  - `wait`: nothing is asked of you, so read again later.
  - `terminal`: nothing you do resolves this, so stop retrying.

  Tolerate a value you do not recognize: show the `description` and
  offer no action.

  Possible values (may grow over time): `operation`, `external`, `wait`, `terminal`
- `ownership.next.description` (string, required): A short, human-readable label for the step, suitable for display.
- `ownership.next.operation` (string): The operationId to call. Present only when `kind` is `operation`. The operation's own schema says how to call it; this says only which one, and what to address it with.
- `ownership.next.params` (object): The parameters that address the operation, by name: `{"sender_id": "…"}` for an operation on `/v1/sms/senders/{sender_id}/requirements`. A parameter the operation takes in its query string is given the same way, so an operation addressed as `?subject_id=` carries `{"subject_id": "…"}`. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when `kind` is `operation` and the operation names a subject. A request body, when the operation takes one, is described by the operation's own schema and never appears here.
- `ownership.next.url` (string): A URL to open. Present only when `kind` is `external`, and only when the step has one. An external step whose `description` says to go and do something with no URL to open is normal.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)