List Phone Numbers
Retrieve every phone number in your workspace.
Returns all phone numbers in the workspace: numbers bought through Trillet and numbers you brought yourself.
Your role needs the phone_number:view permission. Otherwise the request fails with 403 {"error": "Insufficient permissions"}.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Response
A JSON array of phone number objects (not wrapped in an object). An empty workspace returns [].
_idstringThe phone number's ID. Use it as phoneNumberId in Get and Update Phone Number Configuration.
sidstringThe provider's ID for the number. Use it as phoneNumberSid in Release Phone Number.
phoneNumberstringThe number in E.164 format.
providerstringtwilio, sip, telnyx, commschannel or whatsapp.
typestringThe number type as stored, for example local or mobile, or external for a number you brought yourself.
isExternalbooleantrue for a number you brought yourself.
countrystringCountry code, for example US or AU.
statusstringready (no call agent bound yet), active, reserved or error.
flowTypestringWhat the number is bound to: call, message, both, or undefined (nothing).
agentIdobject | nullThe bound call agent as a full object, or null.
pathwayIdobject | nullThe bound call flow as a full object, or null.
messagePathwayIdobject | nullThe bound message flow as a full object, or null.
omniFlowAgentIdobject | nullThe bound message agent as a full object, or null.
recordingEnabledbooleanWhether calls on this number are recorded.
officeHoursobjectenabled, start, end, timezone, allowedDays and blockedDates. See Update Phone Number Configuration.
transferCallerIdModestringfrom-transferee or from-transferor.
metadataTagsobjectKey/value tags on the number.
labelstring | nullOptional label.
monthlyPricenumberWhat the number costs per month. 0 for numbers you brought yourself.
isFreeFromPlanbooleantrue when the number came from your plan's free allowance.
scheduledReleaseAtstring | nullWhen a paid number whose renewal you cancelled will be removed (ISO 8601), or null.
cancelAtPeriodEndbooleantrue when the number's subscription is set to end at the end of the current period.
subscriptionStatusstring | nullStatus of the number's subscription, or null if it has none.
subscriptionExpiresAtstring | nullWhen the subscription expires, or null.
workspaceIdstringThe workspace the number belongs to.
createdAtstringWhen the number was added (ISO 8601). updatedAt is also returned.
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "Workspace ID is required."} | No x-workspace-id |
[
{
"_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
"sid": "1293384261075731499",
"phoneNumber": "+14155550123",
"provider": "telnyx",
"type": "local",
"isExternal": false,
"country": "US",
"status": "active",
"flowType": "call",
"agentId": {
"_id": "a5a5a5a5a5a5a5a5a5a5a5a5",
"name": "Front Desk"
},
"pathwayId": {
"_id": "a6a6a6a6a6a6a6a6a6a6a6a6",
"name": "Front Desk Call Flow"
},
"messagePathwayId": null,
"omniFlowAgentId": null,
"recordingEnabled": true,
"transferCallerIdMode": "from-transferee",
"metadataTags": {},
"label": "Front desk",
"monthlyPrice": 6.79,
"isFreeFromPlan": false,
"scheduledReleaseAt": null,
"cancelAtPeriodEnd": false,
"subscriptionStatus": "active",
"subscriptionExpiresAt": null,
"workspaceId": "a1a1a1a1a1a1a1a1a1a1a1a1",
"createdAt": "2026-10-01T14:22:05.000Z",
"updatedAt": "2026-10-20T09:03:41.000Z"
}
]Last updated on