Trigger Call
curl --request POST \
--url https://client-backend.oktivo.com/api/v1/crm/calls \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phone": "<string>",
"name": "<string>",
"agentId": "<string>",
"dynamicVariables": {},
"deferIfUnavailable": true,
"retryConfig": {
"retryCount": 123,
"retryDelays": [
{}
]
}
}
'import requests
url = "https://client-backend.oktivo.com/api/v1/crm/calls"
payload = {
"phone": "<string>",
"name": "<string>",
"agentId": "<string>",
"dynamicVariables": {},
"deferIfUnavailable": True,
"retryConfig": {
"retryCount": 123,
"retryDelays": [{}]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phone: '<string>',
name: '<string>',
agentId: '<string>',
dynamicVariables: {},
deferIfUnavailable: true,
retryConfig: {retryCount: 123, retryDelays: [{}]}
})
};
fetch('https://client-backend.oktivo.com/api/v1/crm/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://client-backend.oktivo.com/api/v1/crm/calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone' => '<string>',
'name' => '<string>',
'agentId' => '<string>',
'dynamicVariables' => [
],
'deferIfUnavailable' => true,
'retryConfig' => [
'retryCount' => 123,
'retryDelays' => [
[
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://client-backend.oktivo.com/api/v1/crm/calls"
payload := strings.NewReader("{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"agentId\": \"<string>\",\n \"dynamicVariables\": {},\n \"deferIfUnavailable\": true,\n \"retryConfig\": {\n \"retryCount\": 123,\n \"retryDelays\": [\n {}\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://client-backend.oktivo.com/api/v1/crm/calls")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"agentId\": \"<string>\",\n \"dynamicVariables\": {},\n \"deferIfUnavailable\": true,\n \"retryConfig\": {\n \"retryCount\": 123,\n \"retryDelays\": [\n {}\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://client-backend.oktivo.com/api/v1/crm/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"agentId\": \"<string>\",\n \"dynamicVariables\": {},\n \"deferIfUnavailable\": true,\n \"retryConfig\": {\n \"retryCount\": 123,\n \"retryDelays\": [\n {}\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"contactUID": "contact_7f8a9b0c1d2e",
"campaignUID": "campaign_3e4f5g6h7i8j"
}
}
{
"success": false,
"message": "Validation failed",
"errors": [
{
"field": "phone",
"message": "phone must be in E.164 format (e.g. +14155551234)"
}
]
}
{
"success": false,
"message": "Insufficient credits",
"available": 2.5,
"required": 5.0
}
{
"success": false,
"message": "Agent not found"
}
{
"success": true,
"data": {
"status": "deferred",
"reason": "window",
"notBefore": "2026-01-02T03:30:00.000Z",
"deferredCallId": "dfc_example_123",
"contactUID": "contact_7f8a9b0c1d2e"
}
}
{
"success": false,
"message": "Rate limit exceeded. Try again in 45 seconds."
}
{
"success": false,
"message": "Concurrency limit reached maximum concurrent calls active"
}
{
"success": false,
"message": "Voice service is temporarily unavailable. Please retry shortly.",
"reason": "voice_unavailable"
}
Calls
Trigger Call
Trigger a single outbound call to a contact.
POST
/
api
/
v1
/
crm
/
calls
Trigger Call
curl --request POST \
--url https://client-backend.oktivo.com/api/v1/crm/calls \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phone": "<string>",
"name": "<string>",
"agentId": "<string>",
"dynamicVariables": {},
"deferIfUnavailable": true,
"retryConfig": {
"retryCount": 123,
"retryDelays": [
{}
]
}
}
'import requests
url = "https://client-backend.oktivo.com/api/v1/crm/calls"
payload = {
"phone": "<string>",
"name": "<string>",
"agentId": "<string>",
"dynamicVariables": {},
"deferIfUnavailable": True,
"retryConfig": {
"retryCount": 123,
"retryDelays": [{}]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phone: '<string>',
name: '<string>',
agentId: '<string>',
dynamicVariables: {},
deferIfUnavailable: true,
retryConfig: {retryCount: 123, retryDelays: [{}]}
})
};
fetch('https://client-backend.oktivo.com/api/v1/crm/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://client-backend.oktivo.com/api/v1/crm/calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone' => '<string>',
'name' => '<string>',
'agentId' => '<string>',
'dynamicVariables' => [
],
'deferIfUnavailable' => true,
'retryConfig' => [
'retryCount' => 123,
'retryDelays' => [
[
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://client-backend.oktivo.com/api/v1/crm/calls"
payload := strings.NewReader("{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"agentId\": \"<string>\",\n \"dynamicVariables\": {},\n \"deferIfUnavailable\": true,\n \"retryConfig\": {\n \"retryCount\": 123,\n \"retryDelays\": [\n {}\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://client-backend.oktivo.com/api/v1/crm/calls")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"agentId\": \"<string>\",\n \"dynamicVariables\": {},\n \"deferIfUnavailable\": true,\n \"retryConfig\": {\n \"retryCount\": 123,\n \"retryDelays\": [\n {}\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://client-backend.oktivo.com/api/v1/crm/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"agentId\": \"<string>\",\n \"dynamicVariables\": {},\n \"deferIfUnavailable\": true,\n \"retryConfig\": {\n \"retryCount\": 123,\n \"retryDelays\": [\n {}\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"contactUID": "contact_7f8a9b0c1d2e",
"campaignUID": "campaign_3e4f5g6h7i8j"
}
}
{
"success": false,
"message": "Validation failed",
"errors": [
{
"field": "phone",
"message": "phone must be in E.164 format (e.g. +14155551234)"
}
]
}
{
"success": false,
"message": "Insufficient credits",
"available": 2.5,
"required": 5.0
}
{
"success": false,
"message": "Agent not found"
}
{
"success": true,
"data": {
"status": "deferred",
"reason": "window",
"notBefore": "2026-01-02T03:30:00.000Z",
"deferredCallId": "dfc_example_123",
"contactUID": "contact_7f8a9b0c1d2e"
}
}
{
"success": false,
"message": "Rate limit exceeded. Try again in 45 seconds."
}
{
"success": false,
"message": "Concurrency limit reached maximum concurrent calls active"
}
{
"success": false,
"message": "Voice service is temporarily unavailable. Please retry shortly.",
"reason": "voice_unavailable"
}
Request Body
Phone number in E.164 format (e.g.,
+14155551234). Must start with + followed by country code and number.The ID of the agent that will handle this call. Must reference an existing agent in your account.
Optional key-value pairs injected into the agent’s prompt. Maximum 20 entries. Keys max 64 characters. Every value must be a string, max 512 characters. The same values are returned in the call’s webhooks as
data.dynamicVariables.Example: {"company": "Acme Corp", "plan": "Enterprise"}Optional. If
true, a call that cannot be placed right now because the calling window is closed or the voice service is briefly unavailable is queued instead of refused. The response is then 202 Accepted with data.status set to "deferred", plus reason, notBefore, deferredCallId and contactUID. Must be a boolean.Response
{
"success": true,
"data": {
"contactUID": "contact_7f8a9b0c1d2e",
"campaignUID": "campaign_3e4f5g6h7i8j"
}
}
{
"success": false,
"message": "Validation failed",
"errors": [
{
"field": "phone",
"message": "phone must be in E.164 format (e.g. +14155551234)"
}
]
}
{
"success": false,
"message": "Insufficient credits",
"available": 2.5,
"required": 5.0
}
{
"success": false,
"message": "Agent not found"
}
{
"success": true,
"data": {
"status": "deferred",
"reason": "window",
"notBefore": "2026-01-02T03:30:00.000Z",
"deferredCallId": "dfc_example_123",
"contactUID": "contact_7f8a9b0c1d2e"
}
}
{
"success": false,
"message": "Rate limit exceeded. Try again in 45 seconds."
}
{
"success": false,
"message": "Concurrency limit reached maximum concurrent calls active"
}
{
"success": false,
"message": "Voice service is temporarily unavailable. Please retry shortly.",
"reason": "voice_unavailable"
}
Error Codes
| Code | Meaning |
|---|---|
| 400 | Request body validation failed |
| 402 | Insufficient credits to start the call |
| 403 | The contact is on the Do Not Disturb list (the body has "code": "CONTACT_ON_DND"), or calling is not allowed at this time (outside the calling window) |
| 404 | The specified agentId does not exist in your account |
| 429 | Two different causes. Rate limit: more than 60 requests in a minute; the message says how many seconds to wait and the Retry-After header carries the same number. Concurrency limit: your account already has the maximum number of calls running at the same time; the message starts with “Concurrency limit reached” and there is no Retry-After header. Wait and retry with growing delays |
| 503 | Voice service or a pre-dial check is temporarily unavailable. The body has a reason (voice_unavailable, dnd_unavailable or check_failed). When the reason is voice_unavailable, a Retry-After header gives the seconds to wait |
This endpoint accepts both API Token (
okt_...) and JWT authentication.