# PATCH /phone/numbers/:phone_number_id

**Resource:** [Phone](./phone.md)  
**MCP tool:** `update_phone_number`  
**Scopes:** `phone:write`  
**Write operation:** yes

Update a phone number: friendly_name, voice-agent routing, the outbound in-app-dialler allowlist, and the "When Busy" no-answer fallback. IMPORTANT: binding an agent here (inbound_voice_agent_id / outbound_voice_agent_id) controls INBOUND answering (who picks up calls TO this number) and is one-agent-per-number. OUTBOUND dialling does NOT use this binding; set the caller-ID number on the agent via create_voice_agent_outbound_config (default_phone_number_id), which lets one number serve many agents. outbound_caller_user_ids restricts which workspace users may present THIS number as caller ID from the in-app dialler ("Call from TrustPager"): pass an array of user IDs to restrict to exactly those people, or [] / null to let anyone with calling permission dial from it (the default). Every ID must be a member of this workspace. Toll-free numbers (1800/1300) cannot dial out at all. WHEN BUSY (Answer-in-TrustPager numbers only): when the number rings staff browsers ("Answer in TrustPager") and nobody answers within ring_timeout_seconds, no_answer_action decides what happens next instead of dropping the call: "voicemail" (record a message; needs voicemail_greeting_text or voicemail_greeting_audio_url, else a default greeting is spoken; the recording is transcribed and attached to the caller's contact), "forward" (ring no_answer_forward_number), "agent" (hand to the AI voice agent no_answer_agent_config_id), or "none"/null to disable the fallback. no_answer_agent_config_id must be a voice agent in this workspace.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `phone_number_id` | path | string | yes |  |
| `friendly_name` | body | string | no |  |
| `inbound_voice_agent_id` | body | string | no |  |
| `outbound_voice_agent_id` | body | string | no |  |
| `outbound_caller_user_ids` | body | array | no | User IDs allowed to dial out from this number via the in-app dialler. [] or null = anyone with calling permission. |
| `ring_timeout_seconds` | body | integer | no | How long (5-120s, default 25) to ring staff browsers before the When Busy fallback fires. Answer-in-TrustPager numbers only. |
| `no_answer_action` | body | string | no | What to do when no one answers an Answer-in-TrustPager call. null/"none" = drop (no fallback). |
| `no_answer_forward_number` | body | string | no | E.164 number to ring when no_answer_action = "forward". |
| `no_answer_agent_config_id` | body | string | no | Voice agent (this workspace) to hand the call to when no_answer_action = "agent". |
| `voicemail_greeting_text` | body | string | no | Spoken greeting for no_answer_action = "voicemail" (max 1000 chars). Ignored if voicemail_greeting_audio_url is set. |
| `voicemail_greeting_audio_url` | body | string | no | http(s) URL of a pre-generated greeting audio to play for voicemail (e.g. from ai_generate_speech). Takes priority over voicemail_greeting_text. |
| `allowed_inbound_country_list` | body | array | no | Restrict which countries may call this number IN. Array of ISO 3166-1 alpha-2 codes (e.g. ["AU"] for Australia only). Calls from any country not listed are rejected before reaching the agent (spam/fraud control). [] or null = allow all countries (the default). |

## Request example

```bash
curl -X PATCH   "https://api.trustpager.com/functions/v1/api/v1/phone/numbers/:phone_number_id"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"friendly_name":"...","inbound_voice_agent_id":"...","outbound_voice_agent_id":"..."}'
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`