List the phone numbers this account owns

Returns the phone numbers this account owns, newest first, as a { object: "list", data } array.

Endpoint

GET https://api.dairo.app/v1/phone/numbers

Returns the phone numbers this account owns, newest first, as a { object: "list", data } array. Released numbers are excluded by default; pass includeReleased=true to include soft-deleted rows kept for the audit trail. Each number carries its status (active, pending, or released), capabilities, monthlyCostUsd, setupCostUsd, any regulatory requirements, the inboxId/agentId it is bound to, and its inbound agent settings (inboundInstructions, inboundGreeting, inboundVoice, inboundLanguage). This endpoint is not cursor-paginated — it always returns the most recent 100. Requires the phone:read scope.

Scope: phone:read. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl "https://api.dairo.app/v1/phone/numbers" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Query parameters

Name	Type	Required	Description
`includeReleased`	boolean	no	Include numbers that were released back to the provider pool.

Response

200 Success. Body: application/json, PhoneNumberListResponse.

Field	Type	Required	Description
`object`	`"list"`	yes
`data`	array of PhoneNumber	yes

200

{
  "object": "list",
  "data": [
    {
      "object": "phone_number",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "phoneNumber": "string",
      "countryCode": "string",
      "numberType": "local",
      "capabilities": [
        "string"
      ],
      "status": "pending",
      "inboxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "inboundInstructions": null,
      "inboundGreeting": null,
      "inboundVoice": "marin",
      "inboundLanguage": null,
      "monthlyCostUsd": null,
      "setupCostUsd": null,
      "requirements": {},
      "metadata": {},
      "purchasedAt": "2026-10-19T09:30:00Z",
      "releasedAt": "2026-10-19T09:30:00Z",
      "createdAt": "2026-10-19T09:30:00Z"
    }
  ]
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).

List the phone numbers this account owns

Request

Query parameters

Response

Errors

On this page