Trillet AI logo

List Phone Numbers

Retrieve every phone number in your workspace.

GEThttps://api.trillet.ai/v1/api/twilio/user-phone-numbers

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-idstringrequired

Workspace identifier for the API.

Response

A JSON array of phone number objects (not wrapped in an object). An empty workspace returns [].

_idstring

The phone number's ID. Use it as phoneNumberId in Get and Update Phone Number Configuration.

sidstring

The provider's ID for the number. Use it as phoneNumberSid in Release Phone Number.

phoneNumberstring

The number in E.164 format.

providerstring

twilio, sip, telnyx, commschannel or whatsapp.

typestring

The number type as stored, for example local or mobile, or external for a number you brought yourself.

isExternalboolean

true for a number you brought yourself.

countrystring

Country code, for example US or AU.

statusstring

ready (no call agent bound yet), active, reserved or error.

flowTypestring

What the number is bound to: call, message, both, or undefined (nothing).

agentIdobject | null

The bound call agent as a full object, or null.

pathwayIdobject | null

The bound call flow as a full object, or null.

messagePathwayIdobject | null

The bound message flow as a full object, or null.

omniFlowAgentIdobject | null

The bound message agent as a full object, or null.

recordingEnabledboolean

Whether calls on this number are recorded.

officeHoursobject

enabled, start, end, timezone, allowedDays and blockedDates. See Update Phone Number Configuration.

transferCallerIdModestring

from-transferee or from-transferor.

metadataTagsobject

Key/value tags on the number.

labelstring | null

Optional label.

monthlyPricenumber

What the number costs per month. 0 for numbers you brought yourself.

isFreeFromPlanboolean

true when the number came from your plan's free allowance.

scheduledReleaseAtstring | null

When a paid number whose renewal you cancelled will be removed (ISO 8601), or null.

cancelAtPeriodEndboolean

true when the number's subscription is set to end at the end of the current period.

subscriptionStatusstring | null

Status of the number's subscription, or null if it has none.

subscriptionExpiresAtstring | null

When the subscription expires, or null.

workspaceIdstring

The workspace the number belongs to.

createdAtstring

When the number was added (ISO 8601). updatedAt is also returned.

Errors

StatusBodyWhen
400{"error": "Workspace ID is required."}No x-workspace-id
Trimmed
[
  {
    "_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