---
title: "Get Phone Number Configuration"
api: "GET /v1/api/twilio/phone-numbers/{phoneNumberId}/config"
description: "Retrieve the agent, call flow and settings bound to a phone number."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

The fields returned depend on what the number is used for (`flowType`):

- `call`: the call agent, recording, office hours, transfer caller ID and the other call fields below.
- `message`: the message agent and message flow. No recording or office hours.
- Anything else (`both`, or nothing bound yet): only `phoneNumberId`, `status`, `metadataTags`, `recordingPublic` and `officeHours`.

<Note>
Your role needs the `phone_number:view` permission. Otherwise the request fails with `403 {"error": "Insufficient permissions"}`.
</Note>

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="phoneNumberId" type="string" required>
The number's `_id` from [List Phone Numbers](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/phone-numbers/list).
</ParamField>

## Response Fields

<ResponseField name="phoneNumberId" type="string">
The phone number's `_id`.
</ResponseField>

<ResponseField name="agentId" type="object | null">
The bound agent as a full object (with `_id`, `name` and the agent's settings), or `null`. For a `message` number, this is the message agent.
</ResponseField>

<ResponseField name="agentName" type="string | null">
The bound agent's name. `call` and `message` numbers only.
</ResponseField>

<ResponseField name="flowType" type="string | null">
`call` or `message`. Not returned for other numbers.
</ResponseField>

<ResponseField name="pathwayName" type="string | null">
Name of the bound call flow (`call`) or message flow (`message`).
</ResponseField>

<ResponseField name="direction" type="string | null">
The call flow's direction: `inbound`, `outbound` or `bidirectional`. `call` numbers only.
</ResponseField>

<ResponseField name="messageChannel" type="string | null">
The message flow's channel. `message` numbers only.
</ResponseField>

<ResponseField name="status" type="string">
The number's status: `ready` (no call agent bound yet), `active` (bound to an agent with a call flow), `reserved` or `error`.
</ResponseField>

<ResponseField name="recording" type="boolean">
Whether call recording is on for this number. `call` numbers only.
</ResponseField>

<ResponseField name="recordingPublic" type="boolean">
Whether recordings for this number are publicly reachable.
</ResponseField>

<ResponseField name="officeHours" type="object | null">
Office hours: `enabled`, `start` and `end` (`HH:MM`), `timezone` (IANA), `allowedDays` (for example `["Mon","Tue"]`) and `blockedDates`.
</ResponseField>

<ResponseField name="transferCallerIdMode" type="string">
Caller ID shown on transferred calls: `from-transferee` (default, the original caller's number) or `from-transferor` (your Trillet number). `call` numbers only.
</ResponseField>

<ResponseField name="metadataTags" type="object">
Key/value tags on the number, as an object of strings.
</ResponseField>

<ResponseField name="secretBindings" type="object">
Map of alias to workspace secret name. Names only, never secret values. `call` numbers only.
</ResponseField>

## Errors

| Status | Body | When |
| --- | --- | --- |
| `400` | `{"error": "Workspace ID is required."}` | No `x-workspace-id` |
| `403` | `{"error": "Unauthorized access to the phone number"}` | The number belongs to another workspace |
| `404` | `{"error": "Phone number not found"}` | No number with that ID |

<ResponseExample>
```json
{
  "phoneNumberId": "a4a4a4a4a4a4a4a4a4a4a4a4",
  "agentId": {
    "_id": "a5a5a5a5a5a5a5a5a5a5a5a5",
    "name": "Front Desk"
  },
  "flowType": "call",
  "direction": "bidirectional",
  "pathwayName": "Front Desk Call Flow",
  "status": "active",
  "recording": true,
  "agentName": "Front Desk",
  "recordingPublic": false,
  "officeHours": {
    "enabled": true,
    "start": "09:00",
    "end": "17:00",
    "timezone": "America/New_York",
    "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
    "blockedDates": []
  },
  "metadataTags": {
    "location": "Downtown"
  },
  "secretBindings": {},
  "transferCallerIdMode": "from-transferee"
}
```
</ResponseExample>


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://trillet-ai.jamdesk.app/api-specs.zip
