API Reference

The Oktivo API enables programmatic access to voice calling, token management, and webhook configuration.

Base URL

https://client-backend.oktivo.com

All API endpoints are served over HTTPS. HTTP requests are rejected.

Authentication

Endpoint Group	Auth Method	Header
`/api/v1/crm/calls/*`	API Token or JWT	`Authorization: Bearer okt_...`
`/api/v1/crm/tokens/*`	JWT only	`Authorization: Bearer <jwt>`
`/webhooks/endpoints/*`	JWT only	`Authorization: Bearer <jwt>`

See Authentication for details on token creation and management.

Rate Limits

Endpoint	Limit
`POST /api/v1/crm/calls`	60 requests/minute per account
All other endpoints	120 requests/minute per account

When rate limited, you’ll receive a 429 response with a Retry-After header indicating how many seconds to wait.

{
  "success": false,
  "message": "Rate limit exceeded. Try again in 45 seconds."
}

Error Format

All error responses follow a consistent structure:

{
  "success": false,
  "message": "Human-readable error description",
  "errors": [
    {
      "field": "phone",
      "message": "phone must be in E.164 format (e.g. +14155551234)"
    }
  ]
}

Field	Type	Description
`success`	boolean	Always `false` for errors
`message`	string	Summary of what went wrong
`errors`	array	Optional field-level validation errors

HTTP Status Codes

Code	Meaning
200	Success
201	Created (new resource)
400	Validation error check the `errors` array
401	Unauthorized invalid or missing token
402	Insufficient credits
404	Resource not found
409	Conflict resource is in an incompatible state
429	Rate limited wait and retry
500	Internal server error
503	Service unavailable retry with backoff

Pagination

List endpoints return all results for the authenticated user. For endpoints with large result sets, pagination is indicated by:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 127,
    "hasMore": true
  }
}

Use ?page=2&pageSize=50 query parameters to navigate pages.

Request Format

All request bodies must be JSON (Content-Type: application/json)
Path parameters are included in the URL (e.g., /calls/{contactUID})
Query parameters are used for filtering and pagination

API Versioning

The current API version is v1. The version is included in the URL path:

https://client-backend.oktivo.com/api/v1/crm/calls

Breaking changes will be introduced in new versions. The current version will remain supported with advance deprecation notice.

Overview

Authentication

Calls

Leads

Webhooks

API Reference Overview

API Reference

Base URL

Authentication

Rate Limits

Error Format

HTTP Status Codes

Request Format

API Versioning

​API Reference

​Base URL

​Authentication

​Rate Limits

​Error Format

​HTTP Status Codes

​Pagination

​Request Format

​API Versioning

API Reference

Base URL

Authentication

Rate Limits

Error Format

HTTP Status Codes

Pagination

Request Format

API Versioning