> ## Documentation Index > Fetch the complete documentation index at: https://docs.callva.io/llms.txt > Use this file to discover all available pages before exploring further. # Place an outbound call > Requires permission: `outbound_calls.create`. What a token may call depends on its role: see [Authentication and permissions](/authentication). Guide: [Calls and outbound dispatch](/guides/calls). ## OpenAPI ````yaml /api-reference/openapi.json post /call openapi: 3.1.2 info: title: CallVA External API version: 1.0.0 description: >- The CallVA External API lets your own systems - or an autonomous agent acting for you - run a CallVA project: place calls, read and update call records, configure voice agents and their presets, manage custom fields, assets, webhook schedules, automations, phone numbers and projects. ## Authentication Every request carries an API token as a bearer token: `Authorization: Bearer `. Tokens are created in the dashboard; see the `bearerAuth` security scheme for how. ## Not every endpoint is open to every token Which endpoints a token can call depends on the role given to that token when it was created. A role is a set of permissions, such as `calls.read` or `agents.update`, and each endpoint below names the one permission it requires ("Requires permission: ...", and the `x-permission` field of the operation). A call to an endpoint whose permission the token's role does not hold answers `403` with `"code": "insufficient_permission"`; it never answers a partial result. To reach more endpoints, give the token a role that holds their permissions. ## Projects A project-scoped token works in its own project and needs nothing more. An organization-wide token names the project of each request: in the `X-Project-ID` header, or as `project_id` (in the query string for reads and deletes, in the body for writes). A request with no project answers `400` with `"code": "PROJECT_REQUIRED"`. ## Responses Every response is a JSON envelope: `{"success": true, "message": "...", "data": ...}`. Lists that are paginated add `pagination` (`current_page`, `last_page`, `per_page`, `total`, `from`, `to`); `per_page` sets the page size, up to the server's maximum, and `page` the page. A failure answers `{"success": false, "message": "...", "errors": {...}}`, with `errors` present where a field-level reason exists (`422`). servers: - url: https://api.callva.io/api/v1/external description: Production - url: https://staging.api.callva.io/api/v1/external description: Staging - url: https://api.dev.callva.io/api/v1/external description: Development security: - bearerAuth: [] tags: - name: Outbound calls description: >- Place an outbound call through the project's voice agent. Guide: [Calls and outbound dispatch](/guides/calls). - name: Calls description: >- Call records with the project's custom fields: list, filter, read, create, update, delete, and aggregate them. Guide: [Calls and outbound dispatch](/guides/calls). - name: Transcripts description: >- The transcript of a call. Guide: [Calls and outbound dispatch](/guides/calls). - name: Recordings description: >- The audio recording of a call. Guide: [Calls and outbound dispatch](/guides/calls). - name: Actions description: >- Record actions defined for the project, and pressing them on a call. Guide: [Authentication and permissions](/authentication). - name: Agents description: >- Voice agents: their prompt, behaviour and the configuration a call runs on. Guide: [Authentication and permissions](/authentication). - name: Presets description: >- The speech-stack presets an agent can run on, and an agent's configuration on each of them. Guide: [Authentication and permissions](/authentication). - name: Agent tools description: >- The tools an agent may call during a conversation. Guide: [Authentication and permissions](/authentication). - name: Assets description: >- Reusable prompt content that agents reference. Guide: [Authentication and permissions](/authentication). - name: Custom fields description: >- The project's data model: the fields every call record carries. Guide: [Custom fields](/guides/custom-fields). - name: Custom field groups description: >- How custom fields are grouped and ordered. Guide: [Custom fields](/guides/custom-fields). - name: Saved views description: >- Shared calls-list views of the project. Guide: [Authentication and permissions](/authentication). - name: Webhook schedules description: >- Rules that send scheduled webhooks for matching calls. Guide: [Webhooks](/guides/webhooks). - name: Webhook logs description: >- The webhooks the platform sent and what they answered. Guide: [Webhooks](/guides/webhooks). - name: Automations description: >- Scripts that run on platform events, on a schedule or on demand, and their runs. Guide: [Automations](/guides/automations). - name: Automation triggers description: >- HTTP triggers that start an automation from outside. Guide: [Automations](/guides/automations). - name: Variables description: >- Values and secrets that automations read. Guide: [Automations](/guides/automations). - name: Knowledge description: >- What the project holds true, and what not to do. Guide: [Authentication and permissions](/authentication). - name: Issues description: >- What was found to work or not work on calls. Guide: [Authentication and permissions](/authentication). - name: Projects description: >- The projects of the organization the token belongs to. Guide: [Quickstart](/quickstart). - name: Project settings description: 'The settings of the token''s project. Guide: [Webhooks](/guides/webhooks).' - name: Phone numbers description: >- The phone numbers the project calls from and answers on. Guide: [Authentication and permissions](/authentication). - name: Phone providers description: >- The telephony providers connected to the organization. Guide: [Authentication and permissions](/authentication). paths: /call: post: tags: - Outbound calls summary: Place an outbound call description: >- Requires permission: `outbound_calls.create`. What a token may call depends on its role: see [Authentication and permissions](/authentication). Guide: [Calls and outbound dispatch](/guides/calls). operationId: call.initiate parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: type: object properties: destination: type: string pattern: ^\+[1-9]\d{1,14}$ agent_id: type: string format: uuid phone_number_id: type: - string - 'null' format: uuid call_id: type: - string - 'null' format: uuid agent_overrides: type: - object - 'null' properties: voice: type: - string - 'null' name: type: - string - 'null' maxLength: 255 temperature: type: - number - 'null' minimum: 0 maximum: 2 greeting_type: type: - string - 'null' enum: - prompt - exact - instruction - null greeting_exact: type: - string - 'null' greeting_instruction: type: - string - 'null' max_call_duration: type: - integer - 'null' minimum: 30 maximum: 7200 user_silence_timeout: type: - integer - 'null' minimum: 0 maximum: 120 call_silence_timeout: type: - integer - 'null' minimum: 0 maximum: 600 user_prompt_phrases: type: - array - 'null' items: type: string maxLength: 500 max_prompt_attempts: type: - integer - 'null' minimum: 0 maximum: 10 agent_speaks_first: type: - boolean - 'null' farewell_type: type: - string - 'null' farewell_text: type: - string - 'null' prompt: type: - string - 'null' prompt_variables: type: - array - 'null' items: type: string custom_webhook_enabled: type: - boolean - 'null' custom_webhook_url: type: - string - 'null' format: uri maxLength: 2048 preset_overrides: type: - object - 'null' properties: name: type: - string - 'null' config: type: - array - 'null' items: type: string services_overrides: type: - object - 'null' properties: copilot: type: - object - 'null' properties: enabled: type: - boolean - 'null' tools_overrides: type: - array - 'null' items: type: string overrides: type: - object - 'null' properties: agent: type: - array - 'null' items: type: string preset: type: - array - 'null' items: type: string services: type: - array - 'null' items: type: string tools: type: - array - 'null' items: type: string custom_fields: type: - array - 'null' items: type: string required: - destination - agent_id responses: '201': description: >- The call was placed. `call` is the call record with its field values, `room` and `sip_participant` the LiveKit room and SIP leg it runs in, and `config` the compiled agent configuration it runs on. content: application/json: schema: type: object properties: success: type: boolean message: type: string data: type: object properties: call: type: object additionalProperties: {} room: type: object additionalProperties: {} sip_participant: type: object additionalProperties: {} config: type: object additionalProperties: {} required: - call - room - sip_participant - config required: - success - message - data '400': $ref: '#/components/responses/ProjectRequired' '401': $ref: '#/components/responses/Unauthenticated' '403': $ref: '#/components/responses/PermissionDenied' '422': description: >- The request did not validate. `errors.error` is `validation_error`; every other key of `errors` is a field of the request with its messages. content: application/json: schema: type: object properties: success: type: boolean message: type: string errors: type: object additionalProperties: anyOf: - type: string - type: array items: type: string required: - success - message - errors '503': description: '' content: application/json: schema: type: object properties: success: type: boolean message: type: string const: Failed to initiate outbound call errors: type: object properties: error: type: string const: livekit_error action: type: string const: terminate reason_code: type: string const: internal_error caller_message: type: 'null' required: - error - action - reason_code - caller_message required: - success - message - errors 4XX: description: >- The call was refused: the agent, phone number or call named was not found or cannot be used, the balance does not cover it, or the room is at its concurrency limit. `errors.error` names the reason. content: application/json: schema: type: object properties: success: type: boolean message: type: string errors: type: object properties: error: type: string action: type: string reason_code: type: string caller_message: type: 'null' required: - error - action - reason_code - caller_message required: - success - message - errors components: parameters: ProjectId: name: X-Project-ID in: header description: >- The project this request acts in. Required with an organization-wide token (or send `project_id` instead); ignored with a project token, which always acts in its own project. schema: type: string format: uuid responses: ProjectRequired: description: An organization-wide token named no project. content: application/json: schema: type: object properties: success: type: boolean examples: - false message: type: string examples: - >- This API token is tenant-scoped. Please provide project_id in the request payload or query parameters, or use a project-scoped token. code: type: string examples: - PROJECT_REQUIRED required: - success - message - code Unauthenticated: description: The bearer token is missing, invalid, revoked or expired. content: application/json: schema: type: object properties: error: type: string examples: - Invalid or expired token message: type: string examples: - The provided token is invalid or has expired required: - error - message PermissionDenied: description: The token's role does not hold the permission this endpoint requires. content: application/json: schema: type: object properties: success: type: boolean examples: - false message: type: string examples: - Insufficient permission. code: type: string examples: - insufficient_permission required: - success - message - code securitySchemes: bearerAuth: type: http description: >- A CallVA API token, sent as `Authorization: Bearer `. **Creating one.** In the CallVA dashboard, open the organization's Settings, then API Keys, and choose Create API Key: give the key a name, choose its role, and choose its project scope - All projects for an organization-wide token, or one project for a project token. The key is shown once, when it is created, and cannot be read again; store it then. Creating keys needs the `api_tokens.create` permission, which owners and admins hold, and a key cannot create another key. **Organization-wide or project token.** A project token works in the one project it was created for; any project named in the request is ignored. An organization-wide token reaches the projects of its organization, and each request names its project with the `X-Project-ID` header or `project_id` (query string for reads and deletes, body for writes). **What it can call.** The token's role decides which endpoints it may call; each endpoint names the permission it requires, and a token whose role lacks it is answered `403`. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.