Voiceland AI

Riferimento API / Contacts

Contacts

Gli endpoint del gruppo Contacts dell'API Voiceland AI, con parametri, schemi ed esempi curl.

Ultimo aggiornamento:

Le descrizioni degli endpoint e dei campi restano in inglese, esattamente come le pubblica l'API. È una scelta voluta: qui legge ciò che vedrà anche nelle risposte.

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).

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
phone query string Exact-number lookup.
q query string Free-text filter.
limit query integer Max rows (default 500).

Risposte

Codice Descrizione
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Esempio di richiesta

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

Esempio di risposta

{
  "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.

Corpo della richiesta

application/json Schema: ContactRequest

Campo Tipo Obbligatorio Descrizione
company string Sì
custom object
email string Sì
first_name string Sì
last_name string Sì
mobile string Sì
notes string Sì
phone string Sì

Risposte

Codice Descrizione
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.

Esempio di richiesta

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"
}'

Una risposta riuscita restituisce un Contact.

Esempio di risposta

{
  "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.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
limit query integer Max rows (default 50, max 500).

Risposte

Codice Descrizione
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Esempio di richiesta

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

Esempio di risposta

{
  "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.

Risposte

Codice Descrizione
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Esempio di richiesta

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

Esempio di risposta

{
  "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.

Corpo della richiesta

application/json Schema: ContactFieldsRequest

Campo Tipo Obbligatorio Descrizione
fields array of ContactFieldDef Sì

Risposte

Codice Descrizione
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.

Esempio di richiesta

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"
    }
  ]
}'

Esempio di risposta

{
  "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.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
id path string Sì Contact id (ct-…).

Risposte

Codice Descrizione
204 Deleted.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Esempio di richiesta

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

GET /v1/contacts/{id}#

Get a contact.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
id path string Sì Contact id (ct-…).

Risposte

Codice Descrizione
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Esempio di richiesta

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

Una risposta riuscita restituisce un Contact.

Esempio di risposta

{
  "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.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
id path string Sì Contact id (ct-…).

Corpo della richiesta

application/json Schema: ContactRequest

Campo Tipo Obbligatorio Descrizione
company string Sì
custom object
email string Sì
first_name string Sì
last_name string Sì
mobile string Sì
notes string Sì
phone string Sì

Risposte

Codice Descrizione
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Esempio di richiesta

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"
}'

Una risposta riuscita restituisce un Contact.

Esempio di risposta

{
  "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.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
id path string Sì Contact id (ct-…).
limit query integer Max rows (default 50, max 500).

Risposte

Codice Descrizione
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Esempio di richiesta

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

Esempio di risposta

{
  "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"
    }
  ]
}

Schemi#

Contact#

Campo Tipo Obbligatorio Descrizione
calls integer Sì
company string
created_at string (date-time) Sì
custom object
email string
external_ids map of string
first_name string Sì
id string Sì
last_call_at string (date-time)
last_name string
mobile string
notes string
phone string
source string
updated_at string (date-time) Sì

ContactFieldDef#

Campo Tipo Obbligatorio Descrizione
key string Sì
label string Sì
options array of string
pbx_field string
required boolean Sì
show_in_list boolean Sì
type string Sì

ContactFieldsRequest#

Campo Tipo Obbligatorio Descrizione
fields array of ContactFieldDef Sì

ContactRequest#

Campo Tipo Obbligatorio Descrizione
company string Sì
custom object
email string Sì
first_name string Sì
last_name string Sì
mobile string Sì
notes string Sì
phone string Sì

Error#

Error envelope returned for non-2xx responses.

Campo Tipo Obbligatorio Descrizione
error object Sì

La console

Queste pagine sono di sola lettura. La chiamata di prova, le chiavi API e il riferimento API aggiornato si trovano nella console, dove il suo account è connesso.

Apri la console