Departments

Management of service departments. Departments organize agents and define call queues. Requires supervisor role or above.

Important

Departments that have associated recordings cannot be deleted. Use deactivation in that case.

Endpoints

Method	Endpoint	Description	Minimum Role
GET	/api/v1/departments	List departments	supervisor
POST	/api/v1/departments	Create department	supervisor
GET	/api/v1/departments/:id	Get department	supervisor
PUT	/api/v1/departments/:id	Update department	supervisor
DELETE	/api/v1/departments/:id	Delete department	supervisor
GET	/api/v1/departments/:id/users	List department users	supervisor
POST	/api/v1/departments/:id/users	Add user to department	supervisor
DELETE	/api/v1/departments/:id/users/:user_id	Remove user from department	supervisor

---

List Departments

GET /api/v1/departments

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	20	Items per page
sort_by	string	name	Sort field
sort_order	string	asc	Sort direction

Request Example

curl -X GET "https://voki.avanter.com.br/api/v1/departments?page=1&page_size=10" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": [
    {
      "id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "name": "Suporte Técnico",
      "identifier": "suporte-tecnico",
      "description": "Departamento de suporte técnico ao cliente",
      "active": true,
      "sector_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
      "max_queue_size": 20,
      "max_wait_time": 300,
      "user_count": 5,
      "inserted_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-02-01T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_pages": 1,
    "total_count": 3
  }
}

---

Create Department

POST /api/v1/departments

Request Body

Field	Type	Required	Description
name	string	Yes	Department name
identifier	string	No	Unique identifier (slug, auto-generated if omitted)
description	string	No	Description
sector_id	uuid	No	Associated sector ID
max_queue_size	integer	No	Maximum queue size (default: 20)
max_wait_time	integer	No	Maximum wait time in seconds (default: 300)

Request Example

curl -X POST https://voki.avanter.com.br/api/v1/departments \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "department": {
      "name": "Vendas",
      "description": "Departamento de vendas e consultoria",
      "sector_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
      "max_queue_size": 15,
      "max_wait_time": 180
    }
  }'

Success Response (201)

{
  "data": {
    "id": "a7b8c9d0-e1f2-3456-ghij-789012345678",
    "name": "Vendas",
    "identifier": "vendas",
    "description": "Departamento de vendas e consultoria",
    "active": true,
    "sector_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
    "max_queue_size": 15,
    "max_wait_time": 180,
    "user_count": 0,
    "inserted_at": "2026-02-18T12:00:00Z",
    "updated_at": "2026-02-18T12:00:00Z"
  }
}

---

Get Department

GET /api/v1/departments/:id

Request Example

curl -X GET https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

---

Update Department

PUT /api/v1/departments/:id

Request Example

curl -X PUT https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "department": {
      "name": "Suporte Premium",
      "max_queue_size": 30
    }
  }'

---

Delete Department

DELETE /api/v1/departments/:id

Warning

Departments with associated recordings will return a 422 error. Deactivate the department instead of deleting it.

Request Example

curl -X DELETE https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (204)

No response body.

Errors

Code	Description
422	Department has recordings and cannot be deleted
404	Department not found

---

List Department Users

GET /api/v1/departments/:department_id/users

Request Example

curl -X GET https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456/users \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "João Silva",
      "email": "joao@empresa.com",
      "role": "attendant",
      "active": true
    }
  ]
}

---

Add User to Department

POST /api/v1/departments/:department_id/users

Request Body

Field	Type	Required	Description
user_id	uuid	Yes	ID of the user to add

Request Example

curl -X POST https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456/users \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Success Response (201)

{
  "data": {
    "message": "User added to department"
  }
}

---

Remove User from Department

DELETE /api/v1/departments/:department_id/users/:user_id

Request Example

curl -X DELETE https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (204)

No response body.