Graine AI
API referencePhone numbers

List phone numbers

List the phone numbers available to your organisation.

List the phone numbers available to your organisation.

Each entry says what the carrier permits on the number (capabilities), whether it is dedicated to you or drawn from a shared pool (is_shared), and whether it is routed to an inbound agent (is_inbound plus agent_id) or used for placing calls out.

Numbers are allocated by Graine, not through this API: there is no create, update or delete here, and the internal trunk identifiers a number carries are not published.

The telephony service returns the whole set in one response, so this endpoint pages in memory — total is the true count for your organisation and every page is consistent with it.

Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

GET
/v2/phone-numbers
/v2/phone-numbers?capability=voice&page=1&page_size=20

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Query Parameters

capabilityCapability

Return only numbers with this capability, e.g. 'voice'.

Maximum length: 64

organization_idOrganization Id

Must match the organisation the API key belongs to.

pagePage

1-indexed page number (max 10000 — narrow the window instead)

Default: 1Minimum: 1Maximum: 10000

page_sizePage Size

Items per page (max 100)

Default: 20Minimum: 1Maximum: 100

Response Body

200

A page of phone numbers.

data
Required
Data

This page of numbers.

pagination
Required
Pagination

Where this page sits in the result set.

400

1000 — malformed or contradictory input (bad transfer target, bad timeout).

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

402

1400 — the organisation has insufficient credits for this request.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — per-organisation rate limit exceeded. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

503

1501 — the telephony service is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

504

1502 — the telephony service did not respond in time.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

curl -X GET "https://api.graine.ai/v2/phone-numbers?capability=voice&organization_id=string&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

A page of phone numbers.

{
  "data": [
    {
      "phone_number": "+917971442184",
      "capabilities": [
        "voice"
      ],
      "is_inbound": true,
      "is_shared": false,
      "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7,
    "has_more": true
  }
}

Previous

List inbound agents GET

Next

List configured telephony providers GET