Jelliu API documentation

curl -X PATCH https://api.jelliu.co/api/phone-numbers/7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "agentId": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b"
}'

{
  "data": {
    "id": "7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e",
    "phoneNumber": "+13055550142",
    "label": "Recepción",
    "isActive": true,
    "agentId": "2f2d8b4d-aa6f-41e0-9d3e-4d61e1b07a11",
    "agentName": "Sofía - Agendamiento",
    "agentProvisioned": true,
    "ivrEnabled": true,
    "ivrGreeting": "Gracias por llamar a Clínica Dental Sonrisas. Para agendar marque 1, para soporte marque 2.",
    "ivrOptions": [
      {
        "digit": "1",
        "label": "Agendar",
        "agentId": "2f2d8b4d-aa6f-41e0-9d3e-4d61e1b07a11",
        "department": null
      },
      {
        "digit": "2",
        "label": "Soporte",
        "agentId": null,
        "department": "soporte"
      }
    ],
    "channels": [
      "voice"
    ],
    "whatsappStatus": null,
    "provider": "twilio",
    "sipHost": null,
    "createdAt": "2026-09-01T14:20:00.000Z",
    "updatedAt": "2026-09-14T17:12:00.000Z"
  }
}

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. Changes apply to the next inbound call.

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 agentId must 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. 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 (best effort). Toggling IVR re-points the carrier number’s inbound routing between Jelliu’s menu and the voice provider. Writes an audit entry.

Idempotency. Safe to retry: sending the same values again converges on the same state.

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.

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. Changes apply to the next inbound call. 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 `agentId` must 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. 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 (best effort). Toggling IVR re-points the carrier number's inbound routing between Jelliu's menu and the voice provider. Writes an audit entry. **Idempotency.** Safe to retry: sending the same values again converges on the same state. **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](/rate-limits). - **Plan:** Available on every plan.

Authentication

AuthorizationBearer

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.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

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.

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. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | 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](/authentication).

Path parameters

idstringRequiredformat: "uuid"

The phone number’s id (not the E.164 number). Must be a UUID (400 otherwise).

Request

This endpoint expects an object.

agentIdstring or nullOptionalformat: "uuid"

Agent that answers the number. null unbinds it (inbound calls then follow the workspace’s fallback routing).

labelstring or nullOptional<=120 characters

Display name, trimmed. null clears it.

isActivebooleanOptional

false stops using the number as caller ID and for forwarding; it stays in the list.

ivrEnabledbooleanOptional

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.

ivrGreetingstring or nullOptional<=1000 characters

What the menu says before the options. Trimmed; null clears it.

ivrOptionslist of objectsOptional

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.

dataobject

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.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

502

Bad Gateway Error

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 agentId must 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.

Idempotency. Safe to retry: sending the same values again converges on the same state.

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.