---
title: "Update Phone Number Configuration"
api: "PUT /v1/api/twilio/phone-numbers/{phoneNumberId}/config"
description: "Bind a call agent to a phone number and change its recording, office hours, transfer caller ID, tags and label."
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.

Every field is optional. A field you leave out keeps its current value, so you can send only what you want to change. To unassign the agent, send `"agentId": null`.

Binding an agent attaches the number to that agent's live call flow and sets the number's `status` to `active`. If the agent has no call flow yet, the number is saved with `status` `ready` and goes live when you create the agent's call flow. An agent whose call flows are all archived or inactive is refused (see Errors).

<Note>
Your role needs the `phone_number:edit` 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>

## Request Body

<ParamField body="agentId" type="string | null">
The call agent to bind to this number. `null` unassigns the current agent.
</ParamField>

<ParamField body="recordingEnabled" type="boolean">
Whether calls on this number are recorded.
</ParamField>

<ParamField body="officeHours" type="object | null">
Office hours for the number. The object you send replaces the stored one, so send every field you want to keep. `null` clears it.

<Expandable title="properties">

<ParamField body="enabled" type="boolean">
Whether office hours are enforced. Default `false`.
</ParamField>

<ParamField body="start" type="string">
Opening time, `HH:MM` (24-hour). Default `09:00`.
</ParamField>

<ParamField body="end" type="string">
Closing time, `HH:MM` (24-hour). Default `17:00`.
</ParamField>

<ParamField body="timezone" type="string">
IANA timezone, for example `America/New_York`. Default `UTC`.
</ParamField>

<ParamField body="allowedDays" type="string[]">
Days the hours apply to, as `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun`. Default Monday to Friday.
</ParamField>

<ParamField body="blockedDates" type="string[]">
Dates when the number is closed all day.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="transferCallerIdMode" type="string">
Caller ID shown on transferred calls: `from-transferee` (default, the original caller's number) or `from-transferor` (your Trillet number).
</ParamField>

<ParamField body="metadataTags" type="object">
Key/value tags as an object of strings, for example `{"location": "Downtown"}`. Replaces all existing tags.
</ParamField>

<ParamField body="secretBindings" type="object">
Map of alias to workspace secret name, for example `{"crm_key": "acme-crm"}`. Aliases and names use lowercase letters, numbers, hyphens and underscores. Every name must be an existing secret in this workspace, otherwise the request fails with `400`. Replaces all existing bindings.
</ParamField>

<ParamField body="label" type="string">
A label for the number.
</ParamField>

<Note>
Maximum call duration is not a phone number setting. It belongs to the call flow (`settings.callSetting.maxCallDuration`), and a `maxCallDuration` sent here is ignored.
</Note>

## Response

The updated phone number, in the same shape as an item from [List Phone Numbers](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/phone-numbers/list). `agentId` and `pathwayId` are returned as full objects, or `null`.

## Errors

| Status | Body | When |
| --- | --- | --- |
| `400` | `{"error": "Workspace ID is required."}` | No `x-workspace-id` |
| `400` | `{"error": "..."}` | `secretBindings` is malformed or names a secret that doesn't exist |
| `404` | `{"error": "Phone number not found"}` | No number with that ID in this workspace (also for a malformed ID) |
| `404` | `{"message", "code": "AGENT_NOT_FOUND", "error"}` | `agentId` isn't an agent in this workspace |
| `409` | `{"message", "code": "CALL_FLOW_ARCHIVED", "error"}` | Every call flow of the agent is archived or inactive. Restore or turn one on first |
| `500` | `{"error": "Failed to update phone number configuration", "message": "..."}` | Server error |

When a request is refused, nothing is changed.

<RequestExample>
```json
{
  "agentId": "a5a5a5a5a5a5a5a5a5a5a5a5",
  "recordingEnabled": true,
  "officeHours": {
    "enabled": true,
    "start": "09:00",
    "end": "17:00",
    "timezone": "America/New_York",
    "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
    "blockedDates": []
  },
  "transferCallerIdMode": "from-transferee",
  "metadataTags": {
    "location": "Downtown"
  },
  "label": "Front desk"
}
```
</RequestExample>

<ResponseExample>
```json Trimmed
{
  "_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
  "phoneNumber": "+14155550123",
  "sid": "1293384261075731499",
  "provider": "telnyx",
  "status": "active",
  "flowType": "call",
  "agentId": {
    "_id": "a5a5a5a5a5a5a5a5a5a5a5a5",
    "name": "Front Desk"
  },
  "pathwayId": {
    "_id": "a6a6a6a6a6a6a6a6a6a6a6a6",
    "name": "Front Desk Call Flow"
  },
  "recordingEnabled": true,
  "officeHours": {
    "enabled": true,
    "start": "09:00",
    "end": "17:00",
    "timezone": "America/New_York",
    "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
    "blockedDates": []
  },
  "transferCallerIdMode": "from-transferee",
  "metadataTags": {
    "location": "Downtown"
  },
  "label": "Front desk",
  "workspaceId": "a1a1a1a1a1a1a1a1a1a1a1a1"
}
```
</ResponseExample>


---

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