REST API

9.1 Overview

Voki offers a complete REST API for integration with external systems. The API allows you to manage calls, customers, departments, access links, and much more programmatically.

Base URL: https://voki.avanter.com.br/api

Format: JSON (Content-Type: application/json)

9.2 Authentication

All authenticated requests must include the JWT token in the header:

Authorization: Bearer {access_token}

To obtain a token:

curl -X POST https://voki.avanter.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "yourPassword",
    "tenant": "company-name"
  }'

Response:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "user": {
    "id": "uuid",
    "name": "User Name",
    "email": "user@company.com",
    "role": "manager"
  }
}

9.3 Main Endpoints

Authentication

Method	Endpoint	Description
POST	/api/auth/login	Login
POST	/api/auth/refresh	Refresh token
POST	/api/auth/mfa/verify	Verify MFA code
POST	/api/auth/logout	Logout
POST	/api/auth/forgot-password	Request password reset
POST	/api/auth/reset-password	Reset password

Users

Method	Endpoint	Description
GET	/api/v1/users/me	Authenticated user data
GET	/api/v1/users	List users
GET	/api/v1/users/:id	User details
POST	/api/v1/users	Create user
PUT	/api/v1/users/:id	Update user

Departments

Method	Endpoint	Description
GET	/api/v1/departments	List departments
GET	/api/v1/departments/:id	Department details
POST	/api/v1/departments	Create department
PUT	/api/v1/departments/:id	Update department
DELETE	/api/v1/departments/:id	Delete department
POST	/api/v1/departments/:id/users	Add agent to department
DELETE	/api/v1/departments/:id/users/:user_id	Remove agent from department
GET	/api/v1/departments/:id/users	List department agents

Calls

Method	Endpoint	Description
GET	/api/v1/calls	List calls
GET	/api/v1/calls/:id	Call details
POST	/api/v1/calls/:id/assign	Assign call to an agent
POST	/api/v1/calls/:id/start	Start call
POST	/api/v1/calls/:id/complete	Complete call
POST	/api/v1/calls/:call_id/upload	Upload file to call
GET	/api/v1/calls/:call_id/recording	Get recording
POST	/api/v1/calls/:call_id/recording/upload	Upload recording

Customers

Method	Endpoint	Description
GET	/api/v1/customers	List customers
GET	/api/v1/customers/:id	Customer details
POST	/api/v1/customers	Create customer
PUT	/api/v1/customers/:id	Update customer
DELETE	/api/v1/customers/:id	Delete customer
POST	/api/v1/customers/merge	Merge duplicate customers

Access Links

Method	Endpoint	Description
GET	/api/v1/access-links	List links
GET	/api/v1/access-links/:id	Link details
POST	/api/v1/access-links	Create link
POST	/api/v1/access-links/batch	Create links in batch
POST	/api/v1/access-links/:id/cancel	Cancel link

Appointments

Method	Endpoint	Description
GET	/api/v1/appointments	List appointments
GET	/api/v1/appointments/:id	Appointment details
POST	/api/v1/appointments	Create appointment
PUT	/api/v1/appointments/:id	Update appointment
GET	/api/v1/appointments/conflicts	Check time conflicts
POST	/api/v1/appointments/:id/confirm	Confirm appointment
POST	/api/v1/appointments/:id/cancel	Cancel appointment
POST	/api/v1/appointments/:id/complete	Mark as completed
POST	/api/v1/appointments/:id/no-show	Mark as no-show

Tags

Method	Endpoint	Description
GET	/api/v1/tags	List tags
GET	/api/v1/tags/tree	Tag tree
POST	/api/v1/tags	Create tag
PUT	/api/v1/tags/:id	Update tag
DELETE	/api/v1/tags/:id	Delete tag
GET	/api/v1/calls/:call_id/tags	Tags for a call
POST	/api/v1/calls/:call_id/tags	Apply tag to call
DELETE	/api/v1/calls/:call_id/tags/:tag_id	Remove tag from call

Analytics

Method	Endpoint	Description
GET	/api/v1/analytics/overview	Metrics overview
GET	/api/v1/analytics/hourly	Hourly metrics
GET	/api/v1/analytics/agents	Metrics by agent
GET	/api/v1/analytics/trends	Trends
POST	/api/v1/analytics/refresh-views	Refresh materialized views

Webhooks

Method	Endpoint	Description
GET	/api/v1/webhooks	List webhooks
GET	/api/v1/webhooks/:id	Webhook details
POST	/api/v1/webhooks	Create webhook
PUT	/api/v1/webhooks/:id	Update webhook
DELETE	/api/v1/webhooks/:id	Delete webhook
GET	/api/v1/webhooks/:id/deliveries	Delivery history
POST	/api/v1/webhooks/:id/test	Test webhook

Export

Method	Endpoint	Description
GET	/api/v1/export/calls.csv	Export calls as CSV
GET	/api/v1/export/customers.csv	Export customers as CSV
GET	/api/v1/export/links.csv	Export links as CSV

Public Access (Customers)

Method	Endpoint	Description
GET	/api/v1/call/:token/validate	Validate access token
POST	/api/v1/call/:token/join	Join the service queue
GET	/api/v1/call/status/:call_id	Call status
POST	/api/v1/call/evaluate/:call_id	Submit post-service evaluation

9.4 Rate Limiting

Endpoint Type	Limit	Interval
Authentication	5 requests	Per minute
Public API	30 requests	Per minute

When the limit is exceeded:

• HTTP Status: 429 Too Many Requests
• Header Retry-After: seconds until you can try again

9.5 Response Codes

Code	Meaning
200	Success
201	Resource created successfully
400	Bad request (missing or incorrect parameters)
401	Not authenticated (missing or expired token)
403	Forbidden (insufficient role or plan limit)
404	Resource not found
422	Validation error (invalid data)
429	Rate limit exceeded
500	Internal server error

9.6 Interactive Documentation

The complete API documentation with request and response examples is available at:

https://voki.avanter.com.br/docs

---