> ## 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. # Start an outbound call > Initiates an outbound phone call via MCube, Twilio, Exotel, Plivo, Vobiz, Tata Smartflo, SIP, or VoiceLink. Requires sufficient credits and available call concurrency; use `GET /calls/concurrency` to inspect current capacity before starting a call. The provider you pass must appear in the partner's `allowed_telephony_providers` list and its credentials must already be configured. For non-MCube providers, pass `connection_id` when the partner has multiple active connections for the same provider. Provider-only calls remain backward compatible when exactly one active connection exists for that provider. Pass `from_number` to choose the caller ID for this call: it must be an active phone number owned on the selected connection (it overrides the agent-bound or default number for Twilio, Plivo, Vobiz, Tata Smartflo, VoiceLink, and SIP; MCube and Exotel caller IDs are fixed, so a differing `from_number` returns 400). When omitted, the caller ID is the agent-bound number where supported, otherwise the connection default. The resolved caller ID is returned as `from_number` in the response. The call is placed asynchronously. Use `call.status.updated` webhooks or `GET /calls/{id}` to track live status, and use `session.completed` for final transcript, recording, billing, variables, and extraction data. ## OpenAPI ````yaml /openapi.json post /calls/start openapi: 3.1.0 info: title: Vocobase Partner 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 partner 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: 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. paths: /calls/start: post: tags: - Calls summary: Start an outbound call description: >- Initiates an outbound phone call via MCube, Twilio, Exotel, Plivo, Vobiz, Tata Smartflo, SIP, or VoiceLink. Requires sufficient credits and available call concurrency; use `GET /calls/concurrency` to inspect current capacity before starting a call. The provider you pass must appear in the partner's `allowed_telephony_providers` list and its credentials must already be configured. For non-MCube providers, pass `connection_id` when the partner has multiple active connections for the same provider. Provider-only calls remain backward compatible when exactly one active connection exists for that provider. Pass `from_number` to choose the caller ID for this call: it must be an active phone number owned on the selected connection (it overrides the agent-bound or default number for Twilio, Plivo, Vobiz, Tata Smartflo, VoiceLink, and SIP; MCube and Exotel caller IDs are fixed, so a differing `from_number` returns 400). When omitted, the caller ID is the agent-bound number where supported, otherwise the connection default. The resolved caller ID is returned as `from_number` in the response. The call is placed asynchronously. Use `call.status.updated` webhooks or `GET /calls/{id}` to track live status, and use `session.completed` for final transcript, recording, billing, variables, and extraction data. operationId: startCall requestBody: required: true content: application/json: schema: type: object required: - agent_id - to_number properties: agent_id: type: string format: uuid description: ID of the agent to use for this call. to_number: type: string description: Destination phone number in E.164 format. example: '+919876543210' provider: type: string enum: - mcube - twilio - exotel - plivo - vobiz - tata_smartflo - sip - voicelink default: mcube description: >- Telephony provider. Defaults to `mcube` if not specified. The provider must be in your partner's `allowed_telephony_providers` list and its credentials must be configured. connection_id: type: string format: uuid description: >- Telephony connection ID to use for this call. Required when multiple active connections exist for the selected non-MCube provider. This is how you select which configured `from_number`/DID set should place the call. from_number: type: string description: >- Optional per-call caller ID in E.164 format. Must be an ACTIVE phone number owned on the selected connection (`connection_id` picks the connection; `from_number` picks the number within it) -- an unknown number returns 400 `VALIDATION_ERROR`, never a silent substitution. Overrides the agent-bound/default number for Twilio, Plivo, Vobiz, VoiceLink, and SIP. MCube and Exotel use a fixed caller ID, so any differing value returns 400. For VoiceLink, the DID should be call-ready (mapped and routed) or the carrier may reject the call. `fromNumber` is accepted for backwards compatibility. example: '+919484957224' variables: type: object additionalProperties: type: string description: >- Pre-call variable values. Keys must match variable names declared on the agent (`Agent.variables`). Substituted into the agent's prompt and greeting via `{{name}}` placeholders. Echoed in the `session.completed` webhook for partner-side audit. Missing variables render as empty strings. example: callee_name: Sajal mobile_number: '+919876543210' example: agent_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 to_number: '+919876543210' provider: plivo connection_id: 9b7f1c44-c87f-4f0c-9124-3c802a9c1a20 variables: callee_name: Sajal mobile_number: '+919876543210' responses: '201': description: Call initiated successfully. content: application/json: schema: type: object properties: success: type: boolean const: true data: type: object properties: call_id: type: string format: uuid session_id: type: string format: uuid status: type: string example: pending provider: type: string enum: - mcube - twilio - exotel - plivo - vobiz - tata_smartflo - sip - voicelink connection_id: type: - string - 'null' format: uuid description: >- Telephony connection selected for the call. `null` for MCube or legacy provider-only flows without a connection row. from_number: type: string description: Resolved caller ID used for the outbound call. to_number: type: string agent_id: type: string format: uuid example: success: true data: call_id: c1234567-abcd-1234-abcd-123456789012 session_id: s1234567-abcd-1234-abcd-123456789012 status: pending provider: plivo connection_id: 9b7f1c44-c87f-4f0c-9124-3c802a9c1a20 from_number: '+918011223344' to_number: '+919876543210' agent_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 '400': description: Validation error or ambiguous connection selection. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation: summary: Invalid request body value: success: false error: code: VALIDATION_ERROR message: to_number must be in E.164 format (e.g., +919876543210) connection_ambiguous: summary: Multiple active provider connections value: success: false error: code: CONNECTION_AMBIGUOUS message: >- connection_id is required because this partner has multiple active plivo connections. '401': $ref: '#/components/responses/Unauthorized' '403': description: Insufficient credits. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: Insufficient credits '404': $ref: '#/components/responses/NotFound' '429': description: Concurrent call limit reached. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: LIMIT_REACHED message: >- Maximum 3 concurrent calls allowed. 3 calls currently active. '500': $ref: '#/components/responses/InternalError' '502': description: Telephony provider call failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_ERROR message: Failed to initiate call. Please try again. components: schemas: 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 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 NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Resource not found 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. ````