Customers

Management of customers (people being served). Requires attendant role or above.

Endpoints

Method	Endpoint	Description	Minimum Role
GET	/api/v1/customers	List customers	attendant
POST	/api/v1/customers	Create customer	attendant
GET	/api/v1/customers/:id	Get customer	attendant
PUT	/api/v1/customers/:id	Update customer	attendant
DELETE	/api/v1/customers/:id	Delete customer	attendant
POST	/api/v1/customers/merge	Merge duplicate customers	supervisor

---

List Customers

GET /api/v1/customers

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	20	Items per page
sort_by	string	name	Sort field (name, email, inserted_at)
sort_order	string	asc	Sort direction
search	string	-	Search by name, email, or phone

Request Example

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

Success Response (200)

{
  "data": [
    {
      "id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
      "name": "Carlos Ferreira",
      "email": "carlos@email.com",
      "phone": "+5511999998888",
      "document": "123.456.789-00",
      "notes": "Cliente preferencial",
      "call_count": 5,
      "last_call_at": "2026-02-15T14:30:00Z",
      "inserted_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-02-15T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

---

Create Customer

POST /api/v1/customers

Request Body

Field	Type	Required	Description
name	string	Yes	Full name
email	string	No	Email
phone	string	No	Phone number
document	string	No	CPF or CNPJ
notes	string	No	Notes

Request Example

curl -X POST https://voki.avanter.com.br/api/v1/customers \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Ana Costa",
      "email": "ana@email.com",
      "phone": "+5511977776655",
      "document": "987.654.321-00"
    }
  }'

Success Response (201)

{
  "data": {
    "id": "3b4c5d6e-7f8a-9012-cdef-345678901234",
    "name": "Ana Costa",
    "email": "ana@email.com",
    "phone": "+5511977776655",
    "document": "987.654.321-00",
    "notes": null,
    "call_count": 0,
    "last_call_at": null,
    "inserted_at": "2026-02-18T15:00:00Z",
    "updated_at": "2026-02-18T15:00:00Z"
  }
}

---

Get Customer

GET /api/v1/customers/:id

Request Example

curl -X GET https://voki.avanter.com.br/api/v1/customers/2a3b4c5d-6e7f-8901-bcde-f23456789012 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

---

Update Customer

PUT /api/v1/customers/:id

Request Example

curl -X PUT https://voki.avanter.com.br/api/v1/customers/2a3b4c5d-6e7f-8901-bcde-f23456789012 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "notes": "VIP customer - priority treatment"
    }
  }'

---

Delete Customer

DELETE /api/v1/customers/:id

Request Example

curl -X DELETE https://voki.avanter.com.br/api/v1/customers/3b4c5d6e-7f8a-9012-cdef-345678901234 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (204)

No response body.

---

Merge Customers

Merges two or more duplicate customer records into a single record. Requires supervisor role.

POST /api/v1/customers/merge

Request Body

Field	Type	Required	Description
target_id	uuid	Yes	ID of the customer that will receive the data
source_ids	uuid[]	Yes	IDs of the customers to be merged

Request Example

curl -X POST https://voki.avanter.com.br/api/v1/customers/merge \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
    "source_ids": ["3b4c5d6e-7f8a-9012-cdef-345678901234"]
  }'

Success Response (200)

{
  "data": {
    "id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
    "name": "Carlos Ferreira",
    "email": "carlos@email.com",
    "phone": "+5511999998888",
    "document": "123.456.789-00",
    "call_count": 7,
    "merged_count": 1
  }
}

Note

The source customers (source_ids) will be removed and all their calls will be reassigned to the target customer.