Update a phone number
Binds or unbinds the agent, renames the number, activates or deactivates it, and configures the IVR menu. Every field is optional but at least one known field must be present (No fields to update; unknown fields are ignored). null clears a nullable field, an omitted field is left untouched, and ivrOptions: [] clears the menu. Routing changes commit first and remain pending until confirmed by the carriers. Poll the returned Location with GET; do not repeat PATCH while pending.
Rules checked against the stored state:
- the bound agent must exist (404), be provisioned (409) and serve every channel the number answers on (400);
- every IVR option’s
agentIdmust belong to this workspace (404); - IVR cannot be enabled without at least one option (400), and cannot be switched on for a SIP-trunk number or a WhatsApp line (400): the menu only runs on numbers bought through Jelliu;
- a number currently answered by an agent configured directly in the voice engine that no Jelliu workspace manages cannot be re-bound (409); clear the agent first with
agentId: null.
An inactive number (isActive: false) is not used as outbound caller ID, is refused by GET /api/phone-numbers/{id}/forwarding-instructions, and does not count toward the plan’s number cap unless it is a pending acquisition reservation. Deactivating does not release a carrier number or stop its rent.
Side effects. Binding an agent registers the number with the voice engine if needed and points it at the agent; agentId: null unbinds it there too through a durable retry. Toggling IVR re-points the carrier number’s inbound routing between Jelliu’s menu and the voice provider. Writes an audit entry.
Idempotency. A pending routing intent blocks a second binding or IVR edit with 409. Unrelated label and active-state edits remain allowed. GET and list include routingSync; synced confirms completion, verified awaits a stability readback, pending retries automatically, and operator_review requires support.
Access
- Required scope:
write. Signed-in users need the admin or member role (viewers are refused). - Rate limit: General API — per plan: 120 to 600 requests/min per workspace. See Rate limits.
- Plan: Available on every plan.
Authentication
Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the
dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once,
at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.
Operations restricted to admins or owners reject keys without the full scope with 403, and say so in
their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret —
that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds.
See Authentication.
Path parameters
The phone number’s id (not the E.164 number). Must be a UUID (400 otherwise).
Request
Agent that answers the number. null unbinds it (inbound calls then follow the workspace’s fallback routing).
Display name, trimmed. null clears it.
false stops using the number as caller ID and for forwarding; it stays in the list.
Turns the phone menu on or off. The menu runs on numbers bought through Jelliu only. Enabling it on a number connected over the business’s own SIP trunk, or on a WhatsApp line, is a 400: there is no menu to run there.
What the menu says before the options. Trimmed; null clears it.
The full menu, replacing the stored one. Digits must be unique across options (IVR option digits must be unique); at most 20 options.
Response
The updated number; any requested vendor routing has completed strict readback and event persistence.
One number the workspace holds. channels says what it answers on; provider says where it lives. Field names are camelCase. Returned by every /api/phone-numbers endpoint.