> ## Documentation Index > Fetch the complete documentation index at: https://docs.osvi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Initiate a Phone Call > Starts an outbound phone call to the given number using the specified agent. The call is placed asynchronously — use `webhook_url` to receive a notification when the call completes. This is the current, versioned call endpoint. Only `agent_uuid`, `phone_number`, and `country_code` are required; omit any optional field to fall back to the agent's configured defaults. ## OpenAPI ````yaml POST /v1/call openapi: 3.1.0 info: title: OSVI AI API description: REST API for the OSVI AI voice and chat platform license: name: MIT version: 1.0.0 servers: - url: https://api.osvi.ai security: - ApiToken: [] paths: /v1/call: post: summary: Initiate a phone call description: >- Starts an outbound phone call to the given number using the specified agent. The call is placed asynchronously — use `webhook_url` to receive a notification when the call completes. This is the current, versioned call endpoint. Only `agent_uuid`, `phone_number`, and `country_code` are required; omit any optional field to fall back to the agent's configured defaults. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallRequest' responses: '200': description: Call initiated successfully content: application/json: schema: $ref: '#/components/schemas/CallResponse' '400': description: >- Validation error — a required field is missing or a field failed validation (e.g. invalid `country_code`, implausible `phone_number`, `initial_greeting` over 2000 characters, out-of-range `call_config_overrides` values, or a `data_extraction` item missing `description`). content: application/json: schema: $ref: '#/components/schemas/ErrorBadRequest' '401': description: Invalid or missing API token content: application/json: schema: $ref: '#/components/schemas/ErrorUnauthorized' '403': description: >- The agent does not exist or is not associated with the authenticated account. content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' components: schemas: CallRequest: type: object required: - agent_uuid - phone_number - country_code properties: agent_uuid: type: string description: >- Unique identifier of the OSVI agent that will handle the call. Must belong to the account that owns the API token, otherwise the request is rejected with `403 Forbidden`. example: agent_IsxxxxSf_60EhxxxxMGbz-Rxxg phone_number: type: string description: >- Destination phone number (digits only, without country code). Normalized and validated against `country_code`; an implausible number returns `400 Bad Request`. example: '9876543210' country_code: type: string description: >- ISO 3166-1 alpha-2 country code of the destination number. Must be a recognized country code, otherwise the request is rejected with `400 Bad Request`. example: IN system_prompt: type: string description: >- Optional runtime override for the agent's system prompt for this call only. example: >- You are calling to confirm the appointment scheduled for tomorrow at 10 AM. webhook_url: type: string format: uri description: >- URL that OSVI will POST to when the call completes. Must be a valid HTTP or HTTPS URL that includes a host. The payload matches the webhook schema documented in the Webhooks section. example: https://yourdomain.com/osvi-webhook person_name: type: string description: >- Name of the person being called. Made available to the agent during the call. example: John Doe additional_data: type: object additionalProperties: true description: >- Arbitrary key-value object passed to the agent at runtime. Use this to provide context the agent can reference during the conversation. Must be a JSON object — arrays or scalar values are rejected with `400 Bad Request`. example: appointment_date: '2025-01-15' product_name: Premium Plan initial_greeting: type: string maxLength: 2000 description: >- Opening line the agent speaks when the call connects. Maximum 2000 characters. example: >- Hello John, this is a reminder about your appointment tomorrow at 10 AM. call_config_overrides: type: object description: Per-call overrides for call behavior. All fields are optional. properties: max_call_duration_seconds: type: integer minimum: 30 maximum: 1800 description: >- Hard limit on the call length in seconds. Must be between 30 and 1800 (30 minutes). example: 300 enable_callback: type: boolean description: Whether the contact may trigger a callback for this call. example: false retry_config: type: object description: Controls automatic retries when the call is not answered. properties: enabled: type: boolean description: Whether automatic retries are enabled. example: true max_attempts: type: integer minimum: 1 maximum: 10 description: Maximum number of retry attempts. Must be between 1 and 10. example: 2 interval_minutes: type: integer minimum: 1 maximum: 1440 description: >- Minutes to wait between retry attempts. Must be between 1 and 1440 (24 hours). example: 30 example: max_call_duration_seconds: 300 enable_callback: false retry_config: enabled: true max_attempts: 2 interval_minutes: 30 data_extraction: type: array description: >- List of data points the agent should attempt to extract during the conversation. Must be an array; each item requires a non-empty `description`. items: type: object required: - description properties: key: type: string description: Identifier under which the extracted value is returned. example: appointment_confirmed description: type: string description: >- Instruction describing what the agent should ask or extract. Required for every item. example: >- Ask if they can confirm their appointment for tomorrow at 10 AM. required: type: boolean description: >- Whether this data point must be collected for the call to be considered successful. example: true output_format: type: string description: Expected format of the extracted value. example: yes or no example: - key: appointment_confirmed description: Ask if they can confirm their appointment for tomorrow at 10 AM. required: true output_format: yes or no - key: reschedule_preference description: If they cannot make it, ask what date and time works better. required: false output_format: date and time CallResponse: type: object properties: success: type: boolean example: true data: type: object properties: call_id: type: string description: >- Unique identifier for this call. Included in the webhook payload on completion. example: call_abc123xyz ErrorBadRequest: type: object properties: success: type: boolean example: false error: type: string example: max_call_duration_seconds must be between 30 and 1800 details: type: object nullable: true example: null ErrorUnauthorized: type: object properties: success: type: boolean example: false error: type: string example: Invalid API token ErrorForbidden: type: object properties: success: type: boolean example: false error: type: string example: Agent not found or not associated with this account details: type: object nullable: true example: null securitySchemes: ApiToken: type: apiKey in: header name: API-Token description: >- 16-character API token associated with your OSVI account. Find it in your dashboard under Settings → API. ````