---
title: "Update a phone number"
method: PATCH
path: "/api/v1/numbers/{id}"
tags: ["phoneNumbers"]
---

# Update a phone number

`PATCH /api/v1/numbers/{id}`

Update a number's properties. Send any subset of the fields below —
at least one is required; omitted fields are left unchanged.
A new `inboundInstruction` takes effect on the next inbound call;
in-progress calls are unaffected.

**iMessage display identity.** On numbers with the `imessage`
capability, `firstName`, `lastName`, and an avatar photo set the
identity shown beside the number's messages in recipients' Messages
apps. Sending any of these fields for a number without the `imessage`
capability is rejected with `400`.

**The avatar photo** is set either by uploading a file (the `avatar`
part, `multipart/form-data` only) or by passing a publicly reachable
image URL (`avatarUrl`, JSON or multipart) that Dial downloads
server-side. Accepted types: jpeg, png, gif, webp; max 5 MB. A square
image of 512×512 or larger is recommended — it is shown as a circle.
Dial mirrors the photo into its own storage and serves it from the
stable public URL returned as `avatarUrl`. The photo can be
**replaced but not removed** — `avatarUrl: null` is rejected with
`400`. Identity changes can take a few minutes to propagate to
recipients' devices.

## Path parameters

- `id` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `inboundInstruction` string — New inbound voice-agent system prompt for this number.
  - `inboundVoiceGender` 'male' | 'female' — Voice gender for the AI agent on inbound calls to this number. Send null to clear it (the voice reverts to the default, female). Takes effect on the next inbound call.
  - `inboundLanguage` string, nullable — BCP-47 language tag for the AI voice agent on inbound calls to this number. Send null to clear it — the language is then detected from the caller's country prefix on each call, with the agent handling both that language and `en-US`. Takes effect on the next inbound call.
  - `nickname` string, nullable — Human-readable label for the number. Trimmed; at most 100 characters. Send null or an empty string to clear it.
  - `firstName` string, nullable — iMessage display first name shown beside this number's messages in recipients' Messages apps. Trimmed; at most 30 characters. Send null or an empty string to clear it. Only valid on numbers with the `imessage` capability — rejected with `400` otherwise.
  - `lastName` string, nullable — iMessage display last name. Trimmed; at most 30 characters. Send null or an empty string to clear it. Only valid on numbers with the `imessage` capability — rejected with `400` otherwise.
  - `avatarUrl` string, uri — Publicly reachable http(s) URL of an image to set as the number's iMessage avatar photo. Dial downloads it server-side, mirrors it into its own storage, and serves it from the `avatarUrl` returned on the number. jpeg, png, gif, or webp; max 5 MB. The photo can be replaced but not removed — null is rejected with `400`. Only valid on numbers with the `imessage` capability.
  - `maxCallDurationSeconds` integer, nullable — Cap on the length of calls on this number, in seconds, for both inbound calls to the number and outbound calls placed from it. The effective cap on a call is the first one set in priority order — the per-call cap, then this number cap, then the account cap — falling back to the global default. This number cap overrides the account cap (raising or lowering the limit) but is itself overridden by a per-call cap. Must be between 60 and 3600 seconds (1 minute to 1 hour); a value outside that range returns 400. Send null to clear it (falls back to the account cap or global default). Free accounts — accounts that have never added credit and never subscribed — are capped at 300 seconds (5 minutes), reported as `limits.maxCallDurationSeconds` on the account: a higher value sent here returns 400, and a cap inherited from another level is clamped to 300. When a cap is active, Dial automatically injects a warning to the agent ~40 seconds before the hard cut, prompting it to wrap up naturally.

## Response `200`

Updated.

- PhoneNumbersUpdateNumberResponse200
  - `number` PhoneNumber
    - `id` string
    - `number` string — The number in E.164 format.
    - `nickname` string, nullable — Optional human-readable label for the number, e.g. "Support line". Free text, at most 100 characters, not required to be unique. Null when unset. Set and cleared with Update a phone number.
    - `firstName` string, nullable — iMessage display first name — with `lastName` and the avatar photo, the identity shown beside this number's messages in recipients' Messages apps. At most 30 characters. Null when unset, and always null on numbers without the `imessage` capability. Set and cleared with Update a phone number.
    - `lastName` string, nullable — iMessage display last name. At most 30 characters. Null when unset, and always null on numbers without the `imessage` capability. Set and cleared with Update a phone number.
    - `avatarUrl` string, nullable — Public URL of the number's current iMessage avatar photo, hosted by Dial. Null when no photo has been set, and always null on numbers without the `imessage` capability. Set with Update a phone number; the photo can be replaced but not removed.
    - `country` string — ISO-3166-1 alpha-2 country code of the number. Always `US` — only US numbers can be provisioned at this time.
    - `capabilities` PhoneNumberCapabilitiesItems[] — Channels the number supports. `["sms","call"]` for a standard number; `["sms","call","imessage"]` for an iMessage number (which sends iMessage with automatic fallback to RCS/SMS). Mirrors the `capabilities` accepted when provisioning.
    - `setupStatus` 'provisioning' | 'ready' | 'failed' — Whether the number is ready to use. An SMS/call number is always `ready`. An `imessage` number is `provisioning` while it's being set up and only becomes usable for sending or calling once `ready` (`failed` on a setup error). Poll List phone numbers to await `ready`.
    - `setupError` string, nullable — Human-readable reason when `setupStatus` is `failed`; null otherwise.
    - `inboundInstruction` string, nullable — System prompt the AI voice agent uses on inbound calls to this number. Set at provisioning time and changeable with Update a phone number. Null for numbers provisioned before this field existed — those reject inbound calls until an instruction is set.
    - `inboundVoiceGender` 'male' | 'female' — Voice gender the AI agent uses on inbound calls to this number. Null when unset — the voice then uses the default, female. Set and cleared with Update a phone number.
    - `inboundLanguage` string, nullable — BCP-47 language tag the AI voice agent uses on inbound calls to this number. Null when unset — the language is then detected from the caller's country prefix on each call, with the agent handling both that language and `en-US`. Set and cleared with Update a phone number.
    - `accountId` string
    - `createdAt` string, date-time
    - `maxCallDurationSeconds` integer, nullable — Call-length cap in seconds; the effective cap on a call is the first one set in priority order — per-call, then number, then account — falling back to the global default. A higher-priority level overrides a lower one. Null means this level sets no cap. Free accounts (never added credit, never subscribed) are additionally hard-capped at 300 seconds regardless of any configured cap.
    - `tenDlc` PhoneNumberTenDlc — US 10DLC carrier registration for this number. Null when 10DLC does not apply to it — a non-US number, a number with the `imessage` capability (those send over Apple Messages for Business, not carrier SMS), or a number on an account that isn't pay-as-you-go and has no registration yet. Otherwise an object whose `status` says where the registration stands, starting at `not_registered`. US carriers block outbound SMS and MMS sent from an unregistered 10-digit number to US phone numbers. Registering lifts that block for this number. Inbound texts, voice calls in either direction, and messaging to numbers outside the US are unaffected.
      - `status` 'not_registered' | 'in_review' | 'with_carrier' | 'approved' | 'rejected', required — Where this number's registration stands. - `not_registered` — 10DLC applies to this number but nothing has been submitted. Outbound US SMS/MMS is blocked by carriers. - `in_review` — submitted; Dial is checking the details before filing them with the carrier registry. - `with_carrier` — filed with the carrier registry; a decision usually lands within 3–5 business days. - `approved` — registered. The number can send outbound SMS and MMS to US phone numbers. - `rejected` — changes are needed before it can be registered. See `reason`, then resubmit (no additional fee). The brand and the campaign are vetted separately, and this is the combined outcome: `approved` means both cleared, and `rejected` means either was turned down.
      - `kind` 'sole_proprietor' | 'business', required — Who the number was registered as. Null while `status` is `not_registered`.
      - `submittedAt` string, date-time, nullable, required — When the current submission was sent. Null while `status` is `not_registered`. A resubmission after a rejection updates this.
      - `reviewedAt` string, date-time, nullable, required — When the registration was approved or rejected. Null until then.
      - `reason` string, nullable, required — What needs to change, verbatim as shown to the account owner. Non-null only when `status` is `rejected`.

## Other responses

- `400` — The request body failed validation.
- `401` — Missing or invalid API key.
- `404` — The requested resource was not found on this account.
- `413` — Request body too large — the avatar exceeds the 5 MB limit.
- `502` — The display-identity update couldn't be completed upstream — nothing was changed. Safe to retry.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/versions/cfa621230237/schema)