Phone numbers

A phone number is the voice line your agents answer and call from. Each number belongs to exactly one workspace and is bound to one agent: calls to the number reach that agent, and calls the agent places show that number as caller ID. You can get a number three ways: buy one through Jelliu, connect a number you already own over your SIP trunk, or keep your existing line and forward its calls to a Jelliu number.

The Phone Numbers API lets you browse available inventory, provision numbers, connect your own, change which agent answers, configure a phone menu, and get the dialing codes to forward a line.

How it works

Getting a number

Inbound calls. The number you call is the routing key: it identifies the workspace and the agent. Before an agent answers, Jelliu checks that the workspace is not suspended, that a trialing workspace still has trial minutes, and that a concurrent-call slot is free. If the workspace is suspended or out of trial minutes, the caller hears a short message and the call ends; if every slot is busy, the caller is told that all agents are busy.

• If the number has an agent, that agent answers. If that agent is paused, the call is not handed to a different agent.
• If the phone menu is enabled, the caller hears the greeting and the options, and has 10 seconds to press one digit. The option’s agent answers; if it is unavailable, Jelliu tries the option’s department, then another agent in the workspace.

Outbound calls. When an agent places a call, the caller ID is the workspace’s active number bound to that agent, or otherwise its most recently updated active number. See Calls.

The phone number object

Returned by every endpoint on this page except GET /available and GET /{id}/forwarding-instructions.

{
  "data": {
    "id": "3f6a2c1e-8b4d-4e7a-9c2f-5d1b0a9e8c77",
    "phoneNumber": "+13055550142",
    "label": "Miami front desk",
    "isActive": true,
    "agentId": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
    "agentName": "Recepción",
    "agentProvisioned": true,
    "ivrEnabled": false,
    "ivrGreeting": null,
    "ivrOptions": [],
    "channels": ["voice"],
    "whatsappStatus": null,
    "provider": "twilio",
    "sipHost": null,
    "createdAt": "2026-09-01T14:03:22.114Z",
    "updatedAt": "2026-09-10T09:41:05.870Z"
  }
}

Endpoints

GET /api/phone-numbers returns every number in the workspace, oldest first, in { "data": [ ... ] }. It takes no paging parameters.

Common tasks

Buy a number

curl -sS "https://api.jelliu.co/api/phone-numbers/available?country=US&type=local&areaCode=305&limit=5" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{
  "data": [
    {
      "phoneNumber": "+13055550142",
      "friendlyName": "(305) 555-0142",
      "locality": "Miami",
      "region": "FL",
      "isoCountry": "US",
      "type": "local",
      "capabilities": { "voice": true, "sms": true },
      "addressRequired": false
    }
  ]
}

curl -sS -X POST "https://api.jelliu.co/api/phone-numbers/provision" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
    "country": "US",
    "phoneNumber": "+13055550142",
    "label": "Miami front desk"
  }'

Assign or change the agent

Send only the fields you want to change. null clears a nullable field; an omitted field is left untouched.

curl -sS -X PATCH "https://api.jelliu.co/api/phone-numbers/3f6a2c1e-8b4d-4e7a-9c2f-5d1b0a9e8c77" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "b2e4d6f8-1a3c-4e5f-8a9b-0c1d2e3f4a5b", "label": "Soporte Bogotá" }'

The response is 200 with the updated number in data. Changes apply to the next call.

Numbers bought as plan add-ons arrive with agentId: null. Assigning an agent is what registers them for voice, so do it before you rely on the number.

Configure a phone menu

A phone menu lets callers choose where their call goes. Each option routes to a specific agent or to a department; when a department is given, the oldest available agent in that department answers.

curl -sS -X PATCH "https://api.jelliu.co/api/phone-numbers/3f6a2c1e-8b4d-4e7a-9c2f-5d1b0a9e8c77" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ivrEnabled": true,
    "ivrGreeting": "Gracias por llamar a Clínica Aurora.",
    "ivrOptions": [
      { "digit": "1", "label": "citas", "agentId": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4" },
      { "digit": "2", "label": "facturación", "department": "billing" }
    ]
  }'

Each option in ivrOptions:

Connect a number you already own

Bring your number over your SIP trunk. Give inbound so the agent answers calls on the number, outbound so it can call from it, or both.

curl -sS -X POST "https://api.jelliu.co/api/phone-numbers/connect-sip" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
    "phoneNumber": "+576015550199",
    "label": "Línea principal",
    "inbound": {
      "allowedAddresses": ["203.0.113.10/32"],
      "mediaEncryption": "allowed"
    },
    "outbound": {
      "address": "sip.carrier.example.com:5061",
      "transport": "tls",
      "credentials": { "username": "jelliu-trunk", "password": "s3cr3t-trunk-pass" },
      "enabledCodecs": ["PCMU/8000", "PCMA/8000"]
    }
  }'

The response is 201 Created with the number in data, provider: "sip_trunk" and sipHost set to the outbound address.

Top-level fields

inbound: must include allowedAddresses or credentials, so the trunk does not accept calls from anyone.

outbound

Unknown fields in the body are ignored rather than rejected. Double-check field names such as allowedAddresses and enabledCodecs: a misspelled one is dropped silently.

Forward an existing line

If your business line cannot connect over SIP, forward it to a Jelliu number. Fetch the dialing codes for that number; they are standard mobile call-forwarding codes, dialed from the phone the line is on.

curl -sS "https://api.jelliu.co/api/phone-numbers/3f6a2c1e-8b4d-4e7a-9c2f-5d1b0a9e8c77/forwarding-instructions" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Accept-Language: en"

{
  "data": {
    "forwardTo": "+13055550142",
    "agentName": "Recepción",
    "codes": {
      "activateAll": "**21*+13055550142#",
      "activateWhenBusy": "**67*+13055550142#",
      "activateWhenUnanswered": "**61*+13055550142#",
      "activateWhenUnreachable": "**62*+13055550142#",
      "deactivateAll": "##002#",
      "check": "*#21#"
    },
    "notes": [
      "Dial the code from the phone the line is on, then press call. The carrier confirms on screen.",
      "Every call to your number then lands on +13055550142, where Recepción answers. Your customers keep dialling the number they always have.",
      "Forwarding is a service of YOUR carrier: some block forwarding to a number abroad, and the forwarded leg is billed by them at their rate. Check with the carrier if the code is refused.",
      "This covers INCOMING calls. Calls the agent places still show the Jelliu number as caller ID; showing your own number on outbound needs a SIP trunk (Connect own number) or porting.",
      "Fixed lines and PBXs use their own forwarding menus — the codes above are for mobile lines."
    ]
  }
}

notes is written for the person dialing the code: in Spanish when Accept-Language starts with es, in English otherwise. The codes are the same in both.

The number must be a voice number, have an agent assigned and be active; otherwise the request returns 400 VALIDATION_FAILED.

Countries

Numbers can be searched and bought in these countries:

Any other country code returns 400 VALIDATION_FAILED with the list of available countries in the message.

• Plan-included number (POST /provision): US and CA only.
• Add-on numbers (dashboard, Settings → Plan): any country above, priced by country.
• Connected numbers (POST /connect-sip): not limited by this list; any E.164 number your trunk carries.

Some countries sell mostly mobile numbers, which is why provisioning without type falls back from local to mobile.

Errors

Every error uses the standard error envelope. Validation failures on these endpoints return details as a field map (formErrors, fieldErrors).

Limits

Rate limits. All /api/phone-numbers routes use the general API limit for your plan.

Scopes. Reads need a read key, PATCH needs write, and provision and connect-sip need full because they spend money or register numbers. See Authentication.

Numbers per plan. The limit counts active voice numbers: purchased and connected numbers alike. Inactive numbers and WhatsApp-only lines do not count.

On Starter, Growth and Business, the plan includes one number. Each additional purchased number is a paid add-on, so POST /provision can only buy a number while the workspace holds fewer than 1 plus its paid add-ons. On Enterprise the plan limit applies directly. Connecting your own number over SIP needs no add-on: it is limited only by the plan’s number limit.

Webhooks

There are no phone-number events. Calls answered on or placed from your numbers are reported with the call events, call.completed and call.failed. See Webhooks and Calls.

Related