> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt > Use this file to discover all available pages before exploring further. # Push a lead (place an IVR call) > Places one outbound call that runs the published version of the flow, with `data` as the lead. Calls go out on your VoiceLink connection. The call is placed asynchronously: a 202 means it was accepted, not that it was answered. When the flow has Fetch blocks right after Start, they run before dialing; if one fails the number is never dialed and the call ends as `failed` with `ivr.failure = "prefetch_failed"` on `session.completed`. Track the call with `call.status.updated` webhooks or `GET /calls/{id}`, and read the result from the `ivr` block of `session.completed`. Rate limited per account with the same per-minute call quota as `POST /calls/start`, and counted against the same concurrent call limit. A call needs enough balance for one minute at your IVR price for the voice model of the flow's published version (Standard or Premium) to start; it is billed per pulse of answered time at that price. ## OpenAPI ````yaml /openapi.json post /ivr-flows/{flowId}/calls openapi: 3.1.0 info: title: Vocobase API version: '2.0' description: >- API for managing voice AI agents, documents, and calls on the Vocobase platform. servers: - url: https://api.vocobase.com/api/v2 description: Production security: - bearerAuth: [] tags: - name: Config description: >- Read and update account configuration, webhook settings, and telephony credentials. - name: Agents description: Create, read, update, and delete voice AI agents. - name: Voices description: >- List voice tiers, available voices, and stream preview audio for agent configuration. - name: Documents description: Upload, manage, and delete knowledge base documents. - name: Agent Documents description: Link and unlink documents to agents for knowledge base integration. - name: Calls description: Initiate outbound calls and view call history. - name: IVR Flows description: >- Keypad (DTMF) IVR flows built in the dashboard. List published flows, read the lead fields a flow expects, and push one lead to place one call on the published version. - name: Phone Numbers description: >- Import DIDs, assign agents for inbound routing, and re-sync carrier Application bindings. - name: Inbound Routing Policies description: >- Define pre-answer routing decisions for inbound calls before AI sessions are created. - name: Telephony Connections description: Create, list, rename, and disconnect named V2 telephony connections. - name: VoiceLink Management description: Manage VoiceLink reseller clients, DID mapping, and readiness sync. - name: Projects description: Organize agents into projects. Every agent belongs to exactly one project. - name: Dictionaries description: Speech-recognition dictionary CRUD and agent attachment. - name: Sessions description: Browser-initiated WebRTC voice sessions for in-app voice agents. - name: Campaigns description: Batch outbound calling. - name: Billing description: Balance, transactions, and usage summaries. - name: Custom Functions description: HTTP endpoints the agent can call mid-conversation. - name: Extraction Sets description: Reusable sets of post-call extraction fields. - name: Lifecycle Hooks description: Automatic pre-call and post-call integration steps. - name: Messaging description: Bring-your-own WhatsApp sending. - name: Integration Logs description: Audit trail for integration calls. - name: Connectors description: Catalog of tools an agent can be connected to. - name: Customers description: B2B2B sub-tenants and their tool connections. - name: Agent Tools description: Binding connectors and connections to an agent. paths: /ivr-flows/{flowId}/calls: post: tags: - IVR Flows summary: Push a lead (place an IVR call) description: >- Places one outbound call that runs the published version of the flow, with `data` as the lead. Calls go out on your VoiceLink connection. The call is placed asynchronously: a 202 means it was accepted, not that it was answered. When the flow has Fetch blocks right after Start, they run before dialing; if one fails the number is never dialed and the call ends as `failed` with `ivr.failure = "prefetch_failed"` on `session.completed`. Track the call with `call.status.updated` webhooks or `GET /calls/{id}`, and read the result from the `ivr` block of `session.completed`. Rate limited per account with the same per-minute call quota as `POST /calls/start`, and counted against the same concurrent call limit. A call needs enough balance for one minute at your IVR price for the voice model of the flow's published version (Standard or Premium) to start; it is billed per pulse of answered time at that price. operationId: startIvrCall parameters: - name: flowId in: path required: true schema: type: string format: uuid description: >- IVR flow ID, from `GET /ivr-flows` or the flow page in the dashboard. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IvrCallRequest' example: to: '+919876543210' data: loan_id: L-88231 amount_due: 30000 due_date: '2026-06-04' client_reference_id: lead-88231-attempt-1 responses: '200': description: >- Replay: this `client_reference_id` was used before. The original call is returned and no new call is placed. content: application/json: schema: type: object properties: success: type: boolean const: true data: $ref: '#/components/schemas/IvrCallReplay' example: success: true data: call_id: c1234567-abcd-1234-abcd-123456789012 session_id: s1234567-abcd-1234-abcd-123456789012 status: completed from_number: '+917969008446' to_number: '+919876543210' flow_id: f1234567-abcd-1234-abcd-123456789012 client_reference_id: lead-88231-attempt-1 idempotent_replay: true '202': description: Accepted. The call is queued for dialing. content: application/json: schema: type: object properties: success: type: boolean const: true data: $ref: '#/components/schemas/IvrCallAccepted' example: success: true data: call_id: c1234567-abcd-1234-abcd-123456789012 session_id: s1234567-abcd-1234-abcd-123456789012 status: pending from_number: '+917969008446' to_number: '+919876543210' flow_id: f1234567-abcd-1234-abcd-123456789012 flow_version: 3 client_reference_id: lead-88231-attempt-1 '400': description: >- Invalid request, lead data that does not match the flow, or VoiceLink not set up. Lead problems carry a `fields` list. content: application/json: schema: oneOf: - $ref: '#/components/schemas/IvrLeadErrorResponse' - $ref: '#/components/schemas/ErrorResponse' examples: lead_fields: summary: data does not match the flow fields value: success: false error: code: VALIDATION_ERROR message: data does not match the fields of the flow fields: - name: amount_due problem: wrong_type - name: loan_id problem: missing - name: loanid problem: unknown to: summary: Invalid destination number value: success: false error: code: VALIDATION_ERROR message: to must be in E.164 format (e.g., +919876543210) from_not_owned: summary: Caller ID not on the connection value: success: false error: code: VALIDATION_ERROR message: >- from +917969008446 is not an active phone number on the selected VoiceLink connection connection_ambiguous: summary: Several VoiceLink connections value: success: false error: code: CONNECTION_AMBIGUOUS message: >- connection_id is required because this partner has multiple active voicelink connections. provider_not_configured: summary: VoiceLink not configured value: success: false error: code: PROVIDER_NOT_CONFIGURED message: >- VoiceLink telephony is not configured for this account, or the connection has no default phone number. '401': $ref: '#/components/responses/Unauthorized' '402': description: >- The telephony account is out of balance. Retrying will not help until it is topped up. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: telephony_credit: summary: Telephony balance exhausted value: success: false error: code: TELEPHONY_CREDIT_EXHAUSTED message: >- The telephony account is out of balance, so no call can be placed. Retry once it is topped up. '403': description: >- IVR Flows is not enabled on the account, or the balance is too low to start a call. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: disabled: summary: IVR Flows not enabled on the account value: success: false error: code: IVR_FLOWS_DISABLED message: >- IVR Flows is not enabled on this account. Contact Vocobase to enable it. credits: summary: Insufficient balance value: success: false error: code: FORBIDDEN message: Insufficient credits '404': description: >- No flow with this ID on your account, or the `connection_id` was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Flow not found value: success: false error: code: NOT_FOUND message: Flow not found '409': description: The flow has no published version. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_published: summary: Flow not published value: success: false error: code: FLOW_NOT_PUBLISHED message: Publish the flow before placing calls '422': description: >- The account has no IVR price for the voice model of the flow's published version. Contact Vocobase. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: pricing: summary: IVR pricing missing value: success: false error: code: IVR_PRICING_NOT_CONFIGURED message: >- IVR pricing is not configured for this voice model on this account. Contact Vocobase. '429': description: >- Per-minute call quota or concurrent call limit reached. Retry after a short backoff (`Retry-After` is set on `RATE_LIMITED`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rate_limited: summary: Per-minute call quota value: success: false error: code: RATE_LIMITED message: Call rate limit exceeded. Maximum 50 calls per minute. concurrency: summary: Concurrent call limit value: success: false error: code: LIMIT_REACHED message: >- Maximum 3 concurrent calls allowed. 3 calls currently active. '500': $ref: '#/components/responses/InternalError' '502': description: The telephony provider refused the dial. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: provider: summary: Dial failed value: success: false error: code: INTERNAL_ERROR message: Failed to initiate call. Please try again. '503': description: The call could not be queued. Nothing was dialed; retry. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: queue: summary: Could not queue value: success: false error: code: SERVICE_UNAVAILABLE message: Could not queue the call. Please try again. components: schemas: IvrCallRequest: type: object required: - to properties: to: type: string description: Destination phone number in E.164 format. example: '+919876543210' from: type: string description: >- Optional caller ID in E.164 format. Must be an active phone number on the selected VoiceLink connection; an unknown number returns 400 `VALIDATION_ERROR`. When omitted, the connection default is used. example: '+917969008446' connection_id: type: string format: uuid description: >- VoiceLink connection to place the call on. Required when the account has more than one active VoiceLink connection. data: type: object additionalProperties: true description: >- Lead values, keyed by the field names from `GET /ivr-flows/{flowId}`. Every required field must be present and non-empty; keys the flow does not declare are refused. See `IvrLeadField.type` for how each type must be sent. example: loan_id: L-88231 amount_due: 30000 due_date: '2026-06-04' client_reference_id: type: string maxLength: 128 description: >- Your idempotency key, at most 128 characters. A repeat returns the original call with `idempotent_replay: true` and places no new call. The key space is shared with `POST /calls/start` on the same account. example: lead-88231-attempt-1 IvrCallReplay: type: object description: The call originally created with this `client_reference_id`. required: - call_id - session_id - status - from_number - to_number - flow_id - client_reference_id - idempotent_replay properties: call_id: type: string format: uuid session_id: type: - string - 'null' format: uuid status: type: string description: >- Current call status, lowercased (e.g. `pending`, `ringing`, `in_progress`, `completed`, `failed`). from_number: type: string to_number: type: string flow_id: type: - string - 'null' format: uuid description: >- `null` when the earlier call was not placed on this flow (for example a `POST /calls/start` call that used the same key). client_reference_id: type: string idempotent_replay: type: boolean const: true IvrCallAccepted: type: object required: - call_id - session_id - status - from_number - to_number - flow_id - flow_version - client_reference_id properties: call_id: type: string format: uuid session_id: type: string format: uuid status: type: string const: pending from_number: type: string description: Resolved caller ID. to_number: type: string flow_id: type: string format: uuid flow_version: type: integer description: Published version the call runs. client_reference_id: type: - string - 'null' IvrLeadErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: type: object required: - code - message - fields properties: code: type: string const: VALIDATION_ERROR message: type: string fields: type: array items: $ref: '#/components/schemas/IvrLeadProblem' ErrorResponse: type: object properties: success: type: boolean const: false error: type: object properties: code: type: string message: type: string required: - code - message required: - success - error IvrLeadProblem: type: object required: - name - problem properties: name: type: string description: Field name (or the unknown key you sent, cut to 64 characters). problem: type: string enum: - missing - wrong_type - unknown description: >- `missing`: a required field is absent, `null` or `""`. `wrong_type`: the value cannot be read as the field type. `unknown`: the flow declares no such field (at most 20 are reported). responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key in format: `rg_live_xxxx`. Pass as a Bearer token in the Authorization header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.