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.
total is the exact count for your organisation and every page is
consistent with it.
An organisation that has no numbers or carrier set up yet answers 404 rather than an empty page.
Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/phone-numbersAuthorization
AuthorizationRequiredBearer <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'.
64organization_idOrganization Id
Must match the organisation the API key belongs to.
pagePage
1-indexed page number (max 10000 — narrow the window instead)
1Minimum: 1Maximum: 10000page_sizePage Size
Items per page (max 100)
20Minimum: 1Maximum: 100Response Body
200
A page of phone numbers.
dataRequiredData
This page of numbers.
paginationRequiredPagination
Where this page sits in the result set.
400
1000 — malformed or contradictory input (bad transfer target, bad timeout).
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
402
1400 — the organisation has insufficient credits for this request.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
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.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
404
1200 — no numbers or carrier have been set up for this organisation yet.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
422
1001 — the body or query failed validation; the message names the first offending field.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — per-organisation rate limit exceeded. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
503
1501 — a service this endpoint depends on is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
504
1502 — a service this endpoint depends on did not respond in time.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
A page of phone numbers.