Skip to main content

​
Base URL

All API requests are made to: 
https://api.osvi.ai

​
Authentication

Every request must include your API token in the API-Token header: 
API-Token: <your-api-token>
You can find your API token in the OSVI dashboard under Settings → API.
Your API token is 16 characters long and scoped to your account. Keep it secret — do not expose it in client-side code.

​
Request Format

All request bodies must be JSON. Set the Content-Type header accordingly: 
Content-Type: application/json

​
Response Format

All responses return JSON. Successful responses follow this shape: 
{
  "success": true,
  "data": { ... }
}
Error responses: 
{
  "success": false,
  "errors": ["field is required"]
}

​
HTTP Status Codes

CodeMeaning
200Success
401Unauthorized — invalid or missing API-Token
404Resource not found
422Validation error — check the errors array in the response body
500Internal server error

​
Agent UUID

Most endpoints require an agent_uuid. This is the unique identifier for your OSVI agent, formatted as: 
agent_<alphanumeric-string>
Find your agent UUID in the OSVI dashboard on the agent’s detail page. The session-scoped chat control endpoints (support and inject-context) instead address a session by its id.

​
Agents API

Use GET /v1/active_agents to list the agents on your account that are currently active and able to take calls — handy for validating an agent_uuid before triggering a call.

​
Calls API

Use POST /v1/call to start an outbound phone call. Only agent_uuid, phone_number, and country_code are required; every other field is optional. Read results back without waiting for a webhook:
  • List calls (GET /v1/calls) with filters for status, agent, campaign, date range, and phone number.
  • Get a call (GET /v1/call/{id}) for its summary, extracted data, and analysis — the same payload post-call webhooks deliver.
  • Fetch the transcript or a presigned recording URL.

​
Campaigns API

  • Add contacts (POST /v1/campaigns/{id}/contacts) to push a contact list into a campaign and optionally start calling immediately — no manual CSV upload.
  • Get campaign status (GET /v1/campaigns/{id}/status) for call outcomes and queue progress.

​
Do Not Disturb API

Manage the numbers an agent must never call: add, list, and remove entries under /v1/dnd_numbers. Opt-outs propagate to the calling engine immediately, so they apply to in-flight campaigns.

​
Chat API

The Chat (v1) endpoints under /v1/chat/* are the current way to run text conversations with an agent. A typical flow is:
  1. Create a session for a customer (optional — sending a message will resolve or create one).
  2. Send messages with POST /v1/chat/inbound and read the agent’s reply.
  3. Use support commands for human takeover, and inject context to add out-of-band information mid-conversation.
The endpoints under the Legacy section — POST /call, /chat_sessions, and /chat_messages/send_message — are still available but will be deprecated soon. Build new integrations on the API v1 endpoints (POST /v1/call and /v1/chat/*).