Add a phone number to the organization

Create a PhoneNumber resource. It may be linked to at most one user or one group of the organization (unlinked numbers are spares; the org default must be unlinked). grants is optional; every principal must belong to the organization and each grant is stamped with the calling admin. A number created here always stores a grant list ([] when none is sent). Setting isOrgDefault demotes the current default for the same provider in the same transaction. Admin or SuperAdmin.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

organizationId*string

The organization that owns the phone numbers.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*string

Value in

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

phoneNumber*string

Stored in canonical E.164 form; a shortcode is stored as its plain 5 or 6 digits and is refused with a leading +.

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

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

Make this the org fallback sending line for its provider. Must be unlinked and open to human outbound.

linkedUserId?|

Inbound destination user. At most one of linkedUserId / linkedGroupId.

linkedGroupId?|

Inbound destination group. At most one of linkedUserId / linkedGroupId.

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.

Itemsitems <= 200

[key: string]?any

Response Body

`application/json`

curl -X POST "https://example.com/api/organizations/string/phone-numbers" \  -H "Content-Type: application/json" \  -d '{    "provider": "twilio",    "phoneNumber": "+14165550102",    "capabilities": [      "sms",      "voice"    ],    "label": "Leasing team line",    "linkedGroupId": "6650a1b2c3d4e5f6a7b8c9d2",    "grants": [      {        "principalType": "department",        "principalId": "6650a1b2c3d4e5f6a7b8c9d3",        "verbs": [          "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"      }    ]  }}

Add a phone number to the organization

Authorization

Path Parameters

Request Body

Response Body

201application/json

400application/json

403application/json

404application/json

409application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`