Voiceland AI

Справочник API / Contacts

Contacts

Endpoints группы Contacts в API Voiceland AI, с параметрами, схемами и примерами curl.

Последнее обновление:

Описания endpoints и полей показаны на английском языке, ровно так, как их публикует API. Это наш выбор: здесь вы читаете то же, что увидите в ответах.

GET /v1/contacts#

List or look up contacts. Your contact book. ?phone= is the exact-number lookup a PBX makes (cache-first; the number is matched on its last ten digits, so +30 697…, 0030697… and 697… find the same person; a party formatted as Name<+30…> is read too). ?q= filters the list by name, company, email or number. Without either the whole book is returned (default limit 500, max 2000).

Параметры

Имя Место Тип Обязательно Описание
phone query string Exact-number lookup.
q query string Free-text filter.
limit query integer Max rows (default 500).

Ответы

Код Описание
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Пример запроса

curl "https://api.voiceland.ai/v1/contacts" \
  -H "Authorization: Bearer VL_API_KEY"

Пример ответа

{
  "items": [
    {
      "calls": 3,
      "company": "Grill House",
      "created_at": "2026-09-01T10:00:00Z",
      "custom": {
        "customer_tier": "gold"
      },
      "email": "maria@example.com",
      "first_name": "Maria",
      "id": "ct-3d60ba7619c2a4f1",
      "last_call_at": "2026-09-15T06:45:24Z",
      "last_name": "Papadopoulou",
      "mobile": "+30 697 260 5774",
      "notes": "Prefers pickup.",
      "phone": "+30 210 1234567",
      "source": "console",
      "updated_at": "2026-09-15T06:45:30Z"
    }
  ]
}

POST /v1/contacts#

Create a contact. One of a name, a company or a number is required. Numbers are stored as typed; the lookup keys are derived on write.

Тело запроса

application/json Схема: ContactRequest

Поле Тип Обязательно Описание
company string Да
custom object
email string Да
first_name string Да
last_name string Да
mobile string Да
notes string Да
phone string Да

Ответы

Код Описание
201 Created.
400 invalid_contact: nothing to identify the person by.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Пример запроса

curl -X POST "https://api.voiceland.ai/v1/contacts" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "Grill House",
  "custom": {
    "customer_tier": "gold"
  },
  "email": "maria@example.com",
  "first_name": "Maria",
  "last_name": "Papadopoulou",
  "mobile": "+30 697 260 5774",
  "notes": "Prefers pickup.",
  "phone": "+30 210 1234567"
}'

Успешный ответ возвращает Contact.

Пример ответа

{
  "calls": 3,
  "company": "Grill House",
  "created_at": "2026-09-01T10:00:00Z",
  "custom": {
    "customer_tier": "gold"
  },
  "email": "maria@example.com",
  "first_name": "Maria",
  "id": "ct-3d60ba7619c2a4f1",
  "last_call_at": "2026-09-15T06:45:24Z",
  "last_name": "Papadopoulou",
  "mobile": "+30 697 260 5774",
  "notes": "Prefers pickup.",
  "phone": "+30 210 1234567",
  "source": "console",
  "updated_at": "2026-09-15T06:45:30Z"
}

GET /v1/contacts/calls#

Recent journalled calls. The calls third-party systems (a PBX) have journalled for every agent, newest first.

Параметры

Имя Место Тип Обязательно Описание
limit query integer Max rows (default 50, max 500).

Ответы

Код Описание
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Пример запроса

curl "https://api.voiceland.ai/v1/contacts/calls" \
  -H "Authorization: Bearer VL_API_KEY"

Пример ответа

{
  "items": [
    {
      "agent": "front-desk",
      "callee_name": "Front desk",
      "callee_number": "401",
      "caller_name": "Maria Papadopoulou",
      "caller_number": "+306972605774",
      "contact_id": "ct-3d60ba7619c2a4f1",
      "contact_number": "+306972605774",
      "description": "Call: 15/09/2026 09:45:24 Incoming Call from Maria Papadopoulou<+306972605774> to Front desk<401> 00:00:06",
      "direction": "inbound",
      "duration_raw": "00:00:06",
      "duration_sec": 6,
      "external_id": "1789454724",
      "id": "ic-9a1b2c3d4e5f6071",
      "kind": "yeastar_crm",
      "received_at": "2026-09-15T06:45:31Z",
      "recording": true,
      "recording_url": "https://example.com/api/v1.0/crm/recording?secret=…",
      "started_at": "2026-09-15T06:45:24Z",
      "started_raw": "15/09/2026 09:45:24",
      "status": "Incoming Call",
      "subject": "Extension Call"
    }
  ]
}

GET /v1/contacts/fields#

Custom contact fields. The fields you defined on top of the built-in ones (name, company, email, phone, mobile, notes), and pbx_fields: the PBX contact fields a definition may publish under through pbx_field. A definition with pbx_field set is included in the PBX template as that field, so the value shows on the phone.

Ответы

Код Описание
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Пример запроса

curl "https://api.voiceland.ai/v1/contacts/fields" \
  -H "Authorization: Bearer VL_API_KEY"

Пример ответа

{
  "fields": [
    {
      "key": "customer_tier",
      "label": "Customer tier",
      "options": [
        "standard",
        "gold",
        "vip"
      ],
      "pbx_field": "Remark",
      "required": false,
      "show_in_list": true,
      "type": "select"
    }
  ],
  "pbx_fields": [
    {
      "label": "Home number",
      "name": "HomeNumber"
    },
    {
      "label": "Remark (replaces notes)",
      "name": "Remark"
    }
  ],
  "updated_at": "2026-09-19T08:00:00Z"
}

PUT /v1/contacts/fields#

Replace the custom contact fields. At most 20 fields. key is lowercase letters, digits and underscores (it is how custom addresses the value and how the PBX template reads it); type is text, number, date (YYYY-MM-DD), select (with options) or bool. Each PBX field may be used by one definition. Removing a field does not delete stored values; they are ignored until the field comes back.

Тело запроса

application/json Схема: ContactFieldsRequest

Поле Тип Обязательно Описание
fields array of ContactFieldDef Да

Ответы

Код Описание
200 Success.
400 invalid_fields: the message names the field and the rule.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Пример запроса

curl -X PUT "https://api.voiceland.ai/v1/contacts/fields" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": [
    {
      "key": "customer_tier",
      "label": "Customer tier",
      "options": [
        "standard",
        "gold",
        "vip"
      ],
      "pbx_field": "Remark",
      "required": false,
      "show_in_list": true,
      "type": "select"
    }
  ]
}'

Пример ответа

{
  "fields": [
    {
      "key": "customer_tier",
      "label": "Customer tier",
      "options": [
        "standard",
        "gold",
        "vip"
      ],
      "pbx_field": "Remark",
      "required": false,
      "show_in_list": true,
      "type": "select"
    }
  ],
  "pbx_fields": [
    {
      "label": "Home number",
      "name": "HomeNumber"
    }
  ],
  "updated_at": "2026-09-19T08:00:00Z"
}

DELETE /v1/contacts/{id}#

Delete a contact.

Параметры

Имя Место Тип Обязательно Описание
id path string Да Contact id (ct-…).

Ответы

Код Описание
204 Deleted.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Пример запроса

curl -X DELETE "https://api.voiceland.ai/v1/contacts/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/contacts/{id}#

Get a contact.

Параметры

Имя Место Тип Обязательно Описание
id path string Да Contact id (ct-…).

Ответы

Код Описание
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Пример запроса

curl "https://api.voiceland.ai/v1/contacts/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

Успешный ответ возвращает Contact.

Пример ответа

{
  "calls": 3,
  "company": "Grill House",
  "created_at": "2026-09-01T10:00:00Z",
  "custom": {
    "customer_tier": "gold"
  },
  "email": "maria@example.com",
  "first_name": "Maria",
  "id": "ct-3d60ba7619c2a4f1",
  "last_call_at": "2026-09-15T06:45:24Z",
  "last_name": "Papadopoulou",
  "mobile": "+30 697 260 5774",
  "notes": "Prefers pickup.",
  "phone": "+30 210 1234567",
  "source": "console",
  "updated_at": "2026-09-15T06:45:30Z"
}

PUT /v1/contacts/{id}#

Update a contact. Replaces the editable fields; the call counters and the creation stamp are kept.

Параметры

Имя Место Тип Обязательно Описание
id path string Да Contact id (ct-…).

Тело запроса

application/json Схема: ContactRequest

Поле Тип Обязательно Описание
company string Да
custom object
email string Да
first_name string Да
last_name string Да
mobile string Да
notes string Да
phone string Да

Ответы

Код Описание
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Пример запроса

curl -X PUT "https://api.voiceland.ai/v1/contacts/{id}" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "Grill House",
  "custom": {
    "customer_tier": "gold"
  },
  "email": "maria@example.com",
  "first_name": "Maria",
  "last_name": "Papadopoulou",
  "mobile": "+30 697 260 5774",
  "notes": "Prefers pickup.",
  "phone": "+30 210 1234567"
}'

Успешный ответ возвращает Contact.

Пример ответа

{
  "calls": 3,
  "company": "Grill House",
  "created_at": "2026-09-01T10:00:00Z",
  "custom": {
    "customer_tier": "gold"
  },
  "email": "maria@example.com",
  "first_name": "Maria",
  "id": "ct-3d60ba7619c2a4f1",
  "last_call_at": "2026-09-15T06:45:24Z",
  "last_name": "Papadopoulou",
  "mobile": "+30 697 260 5774",
  "notes": "Prefers pickup.",
  "phone": "+30 210 1234567",
  "source": "console",
  "updated_at": "2026-09-15T06:45:30Z"
}

GET /v1/contacts/{id}/calls#

A contact's journalled calls. Newest first. recording_url is the PBX's own playback link when the PBX sent one.

Параметры

Имя Место Тип Обязательно Описание
id path string Да Contact id (ct-…).
limit query integer Max rows (default 50, max 500).

Ответы

Код Описание
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Пример запроса

curl "https://api.voiceland.ai/v1/contacts/{id}/calls" \
  -H "Authorization: Bearer VL_API_KEY"

Пример ответа

{
  "items": [
    {
      "agent": "front-desk",
      "callee_name": "Front desk",
      "callee_number": "401",
      "caller_name": "Maria Papadopoulou",
      "caller_number": "+306972605774",
      "contact_id": "ct-3d60ba7619c2a4f1",
      "contact_number": "+306972605774",
      "description": "Call: 15/09/2026 09:45:24 Incoming Call from Maria Papadopoulou<+306972605774> to Front desk<401> 00:00:06",
      "direction": "inbound",
      "duration_raw": "00:00:06",
      "duration_sec": 6,
      "external_id": "1789454724",
      "id": "ic-9a1b2c3d4e5f6071",
      "kind": "yeastar_crm",
      "received_at": "2026-09-15T06:45:31Z",
      "recording": true,
      "recording_url": "https://example.com/api/v1.0/crm/recording?secret=…",
      "started_at": "2026-09-15T06:45:24Z",
      "started_raw": "15/09/2026 09:45:24",
      "status": "Incoming Call",
      "subject": "Extension Call"
    }
  ]
}

Схемы#

Contact#

Поле Тип Обязательно Описание
calls integer Да
company string
created_at string (date-time) Да
custom object
email string
external_ids map of string
first_name string Да
id string Да
last_call_at string (date-time)
last_name string
mobile string
notes string
phone string
source string
updated_at string (date-time) Да

ContactFieldDef#

Поле Тип Обязательно Описание
key string Да
label string Да
options array of string
pbx_field string
required boolean Да
show_in_list boolean Да
type string Да

ContactFieldsRequest#

Поле Тип Обязательно Описание
fields array of ContactFieldDef Да

ContactRequest#

Поле Тип Обязательно Описание
company string Да
custom object
email string Да
first_name string Да
last_name string Да
mobile string Да
notes string Да
phone string Да

Error#

Error envelope returned for non-2xx responses.

Поле Тип Обязательно Описание
error object Да

Консоль

Эти страницы доступны только для чтения. Тестовый звонок, ключи API и актуальный справочник API находятся в консоли, где выполнен вход в ваш аккаунт.

Открыть консоль