Create an inbound agent
Create an inbound agent so a phone number can be answered by one of your agents.
Create an inbound agent so a phone number can be answered by one of your agents.
agent_id must name an agent in your organisation; any other value
answers 404. The application's webhook endpoints are derived server-side
from that agent — they are Graine's own call-handling URLs and are neither
accepted as input nor returned.
Creating the application does not yet make a number ring it: hand the
returned application_sid to Graine to have one of your numbers pointed
at it. Once linked, the number shows is_inbound: true in
GET /v2/phone-numbers.
Inbound agents are not available on every carrier. If your organisation is on one
that does not support them the request answers 400 — GET /v2/providers reports
what your organisation is configured for.
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.
v2/inbound-agentsAuthorization
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
Request Body
application/jsonRequirednameRequiredName
A human name for the inbound application.
agent_idRequiredAgent Id
The agent that should answer calls routed to this application. Must belong to your organisation.
Query Parameters
organization_idOrganization Id
Must match the organisation the API key belongs to.
Response Body
201
The created inbound application.
application_sidRequiredApplication Sid
Use this to update the application later.
nameRequiredName
The name it was created with.
agent_idRequiredAgent Id
The agent that will answer calls routed here.
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 such resource in this organisation. Cross-tenant reads answer 404, never 403.
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 — the telephony service is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
504
1502 — the telephony service did not respond in time.
errorRequiredError
Stable integer code from the /v2 error table.
messageRequiredMessage
Human-readable single sentence.
The created inbound application.