Update an organization phone number

Partial update of link target, number, capabilities, label, routing (deep-merged), AI binding, status, number type and org-default flag. A numberType change re-checks the number for the new type: a change to shortcode needs 5 or 6 digits, and a change from shortcode to longcode or tollfree needs a valid E.164 number, so send the new phoneNumber with the type change. grants, when present, REPLACES the whole grant list ([] removes every grant); when absent, stored grants are left untouched. A grant that is unchanged keeps its original grantedBy/grantedAt; new or changed grants are stamped with the calling admin. Admin or SuperAdmin.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

organizationId*string

The organization that owns the phone numbers.

phoneNumberId*string

_id of the PhoneNumber resource.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Partial update. Only fields present change; null on a link field clears it (both null unlinks the number).

provider?string

Value in

"sinch"
"twilio"
"bland"
"textgrid"

phoneNumber?string

numberType?string

The kind of number. A shortcode is a 5 or 6 digit SMS-only sender stored as its plain digits (no +); it must have capabilities: ["sms"] (the default when a short code is created without capabilities), no AI or call routing, no forward number, no ElevenLabs id or AI agent, and cannot be the org default. A missing value on a stored line means longcode.

Default"longcode"

Value in

"longcode"
"tollfree"
"shortcode"

capabilities?array<>

label?string|null

routing?

Per-leg routing policy. Every field is optional; on update only the fields sent change.

aiAgentId?string|null

elevenlabsPhoneNumberId?string|null

status?string

Value in

"active"
"inactive"
"released"

isOrgDefault?boolean

linkedUserId?string|null

linkedGroupId?string|null

grants?array<>

Who else may send from and/or read this number, beyond its link. The link stays the inbound destination and always implies send (never read) for the linked user (or linked group members); reading the number's conversations beyond what assignment shows needs an explicit read grant, for the linked user too. Each principal is a user, a user group or a department of this organization, and may appear once. key, grantedBy and grantedAt are set by the server and ignored if sent. A send grant on the org default number is rejected (everyone can already send from it); read grants on it are allowed. Replaces the whole list; omit to leave grants unchanged.

Itemsitems <= 200

[key: string]?any

Response Body

`application/json`

curl -X PUT "https://example.com/api/organizations/string/phone-numbers/string" \  -H "Content-Type: application/json" \  -d '{    "grants": [      {        "principalType": "user",        "principalId": "6650a1b2c3d4e5f6a7b8c9d4",        "verbs": [          "send",          "read"        ]      }    ]  }'

{  "success": true,  "phoneNumber": {    "_id": "string",    "organizationId": "string",    "provider": "string",    "phoneNumber": "string",    "isOrgDefault": true,    "linkedType": "user",    "linkedUserId": "string",    "linkedGroupId": "string",    "grants": [      {        "principalType": "group",        "principalId": "6650a1b2c3d4e5f6a7b8c9d2",        "key": "group:6650a1b2c3d4e5f6a7b8c9d2",        "verbs": [          "send",          "read"        ],        "grantedBy": {          "type": "user",          "userId": "6650a1b2c3d4e5f6a7b8c9d0"        },        "grantedAt": "2026-09-30T12:00:00.000Z"      }    ]  }}

Update an organization phone number

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

403application/json

404application/json

409application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`