Skip to main content
POST
/
v1
/
call
Initiate a phone call
curl --request POST \
  --url https://api.osvi.ai/v1/call \
  --header 'API-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_uuid": "agent_IsxxxxSf_60EhxxxxMGbz-Rxxg",
  "phone_number": "9876543210",
  "country_code": "IN",
  "system_prompt": "You are calling to confirm the appointment scheduled for tomorrow at 10 AM.",
  "webhook_url": "https://yourdomain.com/osvi-webhook",
  "person_name": "John Doe",
  "additional_data": {
    "appointment_date": "2025-01-15",
    "product_name": "Premium Plan"
  },
  "initial_greeting": "Hello John, this is a reminder about your appointment tomorrow at 10 AM.",
  "call_config_overrides": {
    "max_call_duration_seconds": 300,
    "enable_callback": false,
    "retry_config": {
      "enabled": true,
      "max_attempts": 2,
      "interval_minutes": 30
    }
  },
  "data_extraction": [
    {
      "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"
    }
  ]
}
'
{
  "success": true,
  "data": {
    "call_id": "call_abc123xyz"
  }
}

Authorizations

​
API-Token
string
header
required

16-character API token associated with your OSVI account. Find it in your dashboard under Settings → API.

Body

application/json
​
agent_uuid
string
required

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
string
required

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
string
required

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
string

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
string<uri>

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
string

Name of the person being called. Made available to the agent during the call.

Example:

"John Doe"

​
additional_data
object

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
string

Opening line the agent speaks when the call connects. Maximum 2000 characters.

Maximum string length: 2000
Example:

"Hello John, this is a reminder about your appointment tomorrow at 10 AM."

​
call_config_overrides
object

Per-call overrides for call behavior. All fields are optional.

Example:
{
  "max_call_duration_seconds": 300,
  "enable_callback": false,
  "retry_config": {
    "enabled": true,
    "max_attempts": 2,
    "interval_minutes": 30
  }
}
​
data_extraction
object[]

List of data points the agent should attempt to extract during the conversation. Must be an array; each item requires a non-empty description.

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"
  }
]

Response

Call initiated successfully

​
success
boolean
Example:

true

​
data
object