> ## Documentation Index > Fetch the complete documentation index at: https://docs.firetone.com.au/llms.txt > Use this file to discover all available pages before exploring further. # Ring a number into an IVR > FireTone rings `to` from `caller_id` (one of your numbers; optional when you have exactly one), and whoever answers hears the IVR's **published** revision — the same walk a number pointed at the IVR gives its callers. For a reminder with "press 1 to confirm", a survey, a notice. `variables` are available to the IVR's steps as `{{name}}`. Answers 202 at once: the dial happens in the background, and how it went is posted to `callback_url` (`call.started`, `call.ended`; `call.failed` with the reason if nobody answered) and kept on the request (`GET /call-requests/{id}`). Refused 422 with the reason: the IVR has never been published, the number is one of your own, no route reaches it, or billing refuses it. 404 when the IVR is not yours. 503 `node_busy` with `Retry-After` when the node has no room right now. Rate limited with click-to-call (60 a minute per key). Requires calls:originate. ## OpenAPI ````yaml /api-reference/openapi-public.json post /calls/ivr openapi: 3.0.3 info: description: >- The API your own systems use: place and follow calls, have an AI agent call someone, run campaigns and get their results, keep contacts in step with your CRM, and receive signed webhooks. Authenticate with an integration key (Authorization: Bearer ft_...), used only from the IP addresses it allows. title: FireTone API version: 0.1.0 servers: - description: Your platform's API host url: https://{host}/api/v1 variables: host: default: api.firet.one security: - bearerAuth: [] tags: - name: Auth - description: >- Live calls and what can be done to them: hang up, hold, transfer, park, merge, monitor, whisper; the Desk's own call. name: Calls - description: 'Outbound campaigns: contacts, attempts, outcomes.' name: Campaigns - description: 'Customers: who called, what is known about them, and their memory.' name: Contacts - description: What was said on an AI call, and the review of it. name: Conversations - name: IVR - description: >- Your own systems: HTTP connections an IVR calls mid-call, and webhooks for call events. Tenant URLs must be public https addresses. name: Integrations - name: Live - name: Provisioning - name: Reporting - description: Tickets raised by people, agents and the API. name: Tickets - description: Messages left for an extension or a queue. name: Voicemail paths: /calls/ivr: post: tags: - Live summary: Ring a number into an IVR description: >- FireTone rings `to` from `caller_id` (one of your numbers; optional when you have exactly one), and whoever answers hears the IVR's **published** revision — the same walk a number pointed at the IVR gives its callers. For a reminder with "press 1 to confirm", a survey, a notice. `variables` are available to the IVR's steps as `{{name}}`. Answers 202 at once: the dial happens in the background, and how it went is posted to `callback_url` (`call.started`, `call.ended`; `call.failed` with the reason if nobody answered) and kept on the request (`GET /call-requests/{id}`). Refused 422 with the reason: the IVR has never been published, the number is one of your own, no route reaches it, or billing refuses it. 404 when the IVR is not yours. 503 `node_busy` with `Retry-After` when the node has no room right now. Rate limited with click-to-call (60 a minute per key). Requires calls:originate. operationId: postCallsIvr parameters: - $ref: '#/components/parameters/idempotencyKey' - description: 'true: check everything, place nothing, and return the plan.' in: query name: dry_run required: false schema: type: boolean requestBody: content: application/json: schema: properties: callback_url: description: >- Where this call's events are posted, signed with your callback secret. type: string caller_id: description: >- The number of yours the person sees. Optional when you have exactly one. example: '+61298765432' type: string flow_id: description: The IVR to run for whoever answers. It must be published. format: uuid type: string organisation_id: description: >- Not needed: the IVR settles the organisation. If given, it must be the IVR's. format: uuid type: string reference: description: >- Your own id for this call. It comes back on the request, the callbacks and the call record. maxLength: 128 type: string to: description: The number to ring. An outside number, not one of your own. example: '+61412345678' type: string variables: additionalProperties: maxLength: 500 type: string description: >- Values for this call, available to the IVR's steps as {{name}}. example: appointment: Tuesday 3pm name: Sam maxProperties: 30 type: object required: - flow_id - to type: object required: true responses: '200': content: application/json: schema: properties: dry_run: type: boolean plan: properties: caller_id: type: string flow: description: The IVR's name. type: string max_seconds: description: >- How long the balance allows, when the organisation is prepaid. type: integer revision: description: The published revision the person will hear. type: integer to_e164: description: The number as it will be dialled. type: string trunk: description: The carrier route the call leaves by. type: string type: object required: - dry_run - plan type: object description: >- A dry run's plan: dry_run is always true, and nothing was placed or billed. '202': content: application/json: schema: properties: plan: properties: caller_id: type: string flow: description: The IVR's name. type: string max_seconds: description: >- How long the balance allows, when the organisation is prepaid. type: integer revision: description: The published revision the person will hear. type: integer to_e164: description: The number as it will be dialled. type: string trunk: description: The carrier route the call leaves by. type: string type: object reference: type: string request_id: type: string status: type: string type: object description: Dialling '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '409': description: >- no_callback_secret: a callback_url was given and the organisation has no callback secret to sign it with. '422': description: refused, with the reason '503': description: >- The call was not placed because the node has no room for it right now: it is at its channel limit, the machine is loaded, or every AI session it allows is in use. Code `node_busy`, with a `Retry-After` of 30 seconds. Nothing rang and nothing was billed; send the same request again. Distinct from 422, which means the request itself is wrong. components: parameters: idempotencyKey: description: >- Any string up to 255 characters. A retry with the same key and the same body gets the first answer again (with Idempotent-Replayed: true) instead of doing it twice; the same key with a different body is 409 idempotency_mismatch; while the first is still running, 409 idempotency_in_progress. Kept 24 hours. in: header name: Idempotency-Key required: false schema: maxLength: 255 type: string responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/Error' description: The request is not valid. The message names every field that is wrong. NotFound: content: application/json: schema: $ref: '#/components/schemas/Error' description: Not found, or not visible to the caller schemas: Error: properties: error: properties: code: enum: - invalid_request - invalid_credentials - unauthenticated - forbidden - not_found - conflict - internal type: string message: type: string required: - code - message type: object required: - error type: object securitySchemes: bearerAuth: bearerFormat: JWT or API key description: >- Every request sends `Authorization: Bearer `. The token is either a panel session (a JWT from /auth/login, 12 hours) or an API key `ft__`. An API key is accepted only from an address on its IP allowlist (403 ip_not_allowed otherwise; 403 ip_allowlist_required for an old key that has none), is limited to its rate per minute (429 rate_limited with Retry-After; X-RateLimit-Limit/Remaining/Reset on every response), and at most 60 call placements a minute. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.