> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.jelliu.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.jelliu.co/_mcp/server.

# Retrieve forwarding instructions

GET https://api.jelliu.co/api/phone-numbers/{id}/forwarding-instructions

For a business with a plain mobile line and no SIP trunk: the Jelliu number to forward to and the GSM codes to dial, so calls to the business's own number land on this number and the bound agent answers. Forwarding itself is configured on the customer's carrier; Jelliu cannot see whether it is active.

Refused (400) when the number is a WhatsApp-only line, has no agent bound (a forward into nothing rings into nothing), or is inactive. Outbound calls still show the Jelliu number as caller ID; to call from the business's own number use `POST /api/phone-numbers/connect-sip`.

`notes` are written in Spanish when `Accept-Language` starts with `es`, in English otherwise. Codes and shape are identical in both.

**Idempotency.** Read-only; safe to retry.

**Access**
- **Required scope:** `read` (or `write`).
- **Rate limit:** General API — per plan: 120 to 600 requests/min per workspace. See [Rate limits](/rate-limits).
- **Plan:** Available on every plan.


Reference: https://developer.jelliu.co/api-reference/phone-numbers/get-phone-number-forwarding-instructions

## Authentication

- `Authorization` header (bearer token, required) — 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).

## Request

### Path parameters

- `id` (string, required) — The phone number's id (not the E.164 number). Must be a UUID (400 otherwise).

### Headers

- `Accept-Language` (string, optional) — Language of `notes`: any value starting with `es` gives Spanish; anything else, or no header, gives English.

## Response

### 200

Instructions.

- `data` (object, required) — How to forward a plain mobile line to a Jelliu number. Returned by `GET /api/phone-numbers/{id}/forwarding-instructions`.
  - `forwardTo` (string, required) — The Jelliu number (E.164) to forward the business's line to.
  - `agentName` (string, required, nullable) — Name of the agent that answers forwarded calls.
  - `codes` (object, required) — GSM supplementary-service codes, dialed from the mobile phone the line is on. Fixed lines and PBXs use their own menus.
    - `activateAll` (string, required) — Forward every call unconditionally.
    - `activateWhenBusy` (string, required) — Forward only when the line is busy.
    - `activateWhenUnanswered` (string, required) — Forward only when nobody answers.
    - `activateWhenUnreachable` (string, required) — Forward only when the phone is off or out of coverage.
    - `deactivateAll` (string, required) — Cancel every forwarding rule.
    - `check` (string, required) — Check whether unconditional forwarding is on.
  - `notes` (list of string, required) — Plain-language caveats for the person setting it up, in Spanish or English depending on `Accept-Language`.

## Errors

### 400 Bad Request Error

Invalid `id`, or the number cannot receive forwarded calls.

- `error` (object, required) — The error object. Always has `code` and `message`.
  - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors).
  - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice.
  - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields).
    - Field map
      - `formErrors` (list of string, optional)
      - `fieldErrors` (map from string to list of string, optional)
  - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates).

### 401 Unauthorized Error

No usable credential. Either the `Authorization` header is missing or is not a well-formed `Bearer jl_…` key, or the key is unknown, revoked or expired. Do not retry with the same key. See [Authentication](/authentication#401-unauthorized).

- `error` (object, required) — The error object. Always has `code` and `message`.
  - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors).
  - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice.
  - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields).
    - Field map
      - `formErrors` (list of string, optional)
      - `fieldErrors` (map from string to list of string, optional)
  - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates).

### 403 Forbidden Error

The API key has neither the `read` nor the `write` scope, or the workspace is suspended.

- `error` (object, required) — The error object. Always has `code` and `message`.
  - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors).
  - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice.
  - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields).
    - Field map
      - `formErrors` (list of string, optional)
      - `fieldErrors` (map from string to list of string, optional)
  - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates).

### 404 Not Found Error

The number does not exist, was deleted, or belongs to another workspace.

- `error` (object, required) — The error object. Always has `code` and `message`.
  - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors).
  - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice.
  - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields).
    - Field map
      - `formErrors` (list of string, optional)
      - `fieldErrors` (map from string to list of string, optional)
  - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates).

### 429 Too Many Requests Error

Rate limit exceeded for the current 60-second window (`RATE_LIMIT_EXCEEDED`). Wait `Retry-After` seconds, then retry. The `message` differs per limiter; the code does not. See [Rate limits](/rate-limits).

- `error` (object, required) — The error object. Always has `code` and `message`.
  - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors).
  - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice.
  - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields).
    - Field map
      - `formErrors` (list of string, optional)
      - `fieldErrors` (map from string to list of string, optional)
  - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates).

## Examples

**Response**

```json
{
  "data": {
    "forwardTo": "+13055550142",
    "agentName": "Sofía - Agendamiento",
    "codes": {
      "activateAll": "**21*+13055550142#",
      "activateWhenBusy": "**67*+13055550142#",
      "activateWhenUnanswered": "**61*+13055550142#",
      "activateWhenUnreachable": "**62*+13055550142#",
      "deactivateAll": "##002#",
      "check": "*#21#"
    },
    "notes": [
      "Marca el código desde el teléfono donde está la línea y pulsa llamar. La operadora confirma en pantalla.",
      "Desde ese momento, toda llamada a tu número cae en +13055550142, donde contesta Sofía - Agendamiento. Tus clientes siguen marcando el número de siempre.",
      "El desvío es un servicio de TU operadora: algunas bloquean el desvío a un número extranjero, y el tramo desviado lo factura ella a su tarifa. Si rechaza el código, consúltalo con la operadora.",
      "Esto cubre las llamadas ENTRANTES. Las que haga el agente siguen mostrando el número de Jelliu como identificador; para que salga tu número al llamar hace falta una troncal SIP (Conectar mi número) o portar el número.",
      "Las líneas fijas y las centralitas tienen sus propios menús de desvío: los códigos de arriba son para líneas móviles."
    ]
  }
}
```

**SDK Code**

```python Phone Numbers_getPhoneNumberForwardingInstructions_example
import requests

url = "https://api.jelliu.co/api/phone-numbers/7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e/forwarding-instructions"

headers = {
    "Accept-Language": "es-CO",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Phone Numbers_getPhoneNumberForwardingInstructions_example
const url = 'https://api.jelliu.co/api/phone-numbers/7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e/forwarding-instructions';
const options = {
  method: 'GET',
  headers: {'Accept-Language': 'es-CO', Authorization: 'Bearer <token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Phone Numbers_getPhoneNumberForwardingInstructions_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.jelliu.co/api/phone-numbers/7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e/forwarding-instructions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept-Language", "es-CO")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Phone Numbers_getPhoneNumberForwardingInstructions_example
require 'uri'
require 'net/http'

url = URI("https://api.jelliu.co/api/phone-numbers/7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e/forwarding-instructions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept-Language"] = 'es-CO'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Phone Numbers_getPhoneNumberForwardingInstructions_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.jelliu.co/api/phone-numbers/7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e/forwarding-instructions")
  .header("Accept-Language", "es-CO")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Phone Numbers_getPhoneNumberForwardingInstructions_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.jelliu.co/api/phone-numbers/7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e/forwarding-instructions', [
  'headers' => [
    'Accept-Language' => 'es-CO',
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Phone Numbers_getPhoneNumberForwardingInstructions_example
using RestSharp;

var client = new RestClient("https://api.jelliu.co/api/phone-numbers/7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e/forwarding-instructions");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept-Language", "es-CO");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Phone Numbers_getPhoneNumberForwardingInstructions_example
import Foundation

let headers = [
  "Accept-Language": "es-CO",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.jelliu.co/api/phone-numbers/7b1e9a3c-2d4f-4a8b-9c6e-1f0a2b3c4d5e/forwarding-instructions")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```