Update a phone number | Dial — Communication Stack for AI Agents

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.

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.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Path parameters

idstringRequired

Request

This endpoint expects an object.

inboundInstructionstringOptional

New inbound voice-agent system prompt for this number.

inboundVoiceGenderenumOptional

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.

Allowed values:

inboundLanguagestring or nullOptional

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.

nicknamestring or nullOptional

Human-readable label for the number. Trimmed; at most 100 characters. Send null or an empty string to clear it.

firstNamestring or nullOptional

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.

lastNamestring or nullOptional

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.

avatarUrlstringOptionalformat: "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.

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.

maxCallDurationSecondsinteger or nullOptional60-3600

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.

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

Updated.

numberobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

413

Content Too Large Error

502

Bad Gateway Error

$	curl -X PATCH https://api.getdial.ai/api/v1/numbers/id \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'

1	{
2	"number": {
3	"id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
4	"number": "+14155550123",
5	"nickname": "Support line",
6	"firstName": "Maya",
7	"lastName": "Chen",
8	"avatarUrl": "https://getdial.ai/public-media/9f2c47a1b8d3e6f0a1b2c3d4.png",
9	"country": "US",
10	"capabilities": [
11	"sms",
12	"call"
13	],
14	"setupStatus": "ready",
15	"setupError": "",
16	"inboundInstruction": "You are Dial's receptionist. Greet the caller and find out what they need.",
17	"inboundVoiceGender": "female",
18	"inboundLanguage": "es-ES",
19	"accountId": "acc_9876543210abcdef",
20	"createdAt": "2024-01-15T09:30:00Z",
21	"maxCallDurationSeconds": 300,
22	"tenDlc": {
23	"status": "in_review",
24	"kind": "business",
25	"submittedAt": "2024-01-15T09:30:00Z",
26	"reviewedAt": "2024-01-20T15:45:00Z",
27	"reason": "The message flow describes a checkout page rather than the SMS consent step. Say where the consent wording and the checkbox appear, and that the box starts unchecked."
28	}
29	}
30	}