Voiceland AI

Référence de l'API / Contacts

Contacts

Les endpoints du groupe Contacts de l'API Voiceland AI, avec les paramètres, les schémas et des exemples curl.

Dernière mise à jour:

Les descriptions des endpoints et des champs restent en anglais, telles que l'API les publie. C'est un choix délibéré : vous lisez ici ce que vous verrez aussi dans les réponses.

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

Paramètres

Nom Emplacement Type Requis Description
phone query string Exact-number lookup.
q query string Free-text filter.
limit query integer Max rows (default 500).

Réponses

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

Exemple de requête

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

Exemple de réponse

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

Corps de la requête

application/json Schéma : ContactRequest

Champ Type Requis Description
company string Oui
custom object
email string Oui
first_name string Oui
last_name string Oui
mobile string Oui
notes string Oui
phone string Oui

Réponses

Code Description
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.

Exemple de requête

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

Une réponse réussie renvoie un Contact.

Exemple de réponse

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

Paramètres

Nom Emplacement Type Requis Description
limit query integer Max rows (default 50, max 500).

Réponses

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

Exemple de requête

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

Exemple de réponse

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

Réponses

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

Exemple de requête

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

Exemple de réponse

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

Corps de la requête

application/json Schéma : ContactFieldsRequest

Champ Type Requis Description
fields array of ContactFieldDef Oui

Réponses

Code Description
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.

Exemple de requête

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

Exemple de réponse

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

Paramètres

Nom Emplacement Type Requis Description
id path string Oui Contact id (ct-…).

Réponses

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

Exemple de requête

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

GET /v1/contacts/{id}#

Get a contact.

Paramètres

Nom Emplacement Type Requis Description
id path string Oui Contact id (ct-…).

Réponses

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

Exemple de requête

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

Une réponse réussie renvoie un Contact.

Exemple de réponse

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

Paramètres

Nom Emplacement Type Requis Description
id path string Oui Contact id (ct-…).

Corps de la requête

application/json Schéma : ContactRequest

Champ Type Requis Description
company string Oui
custom object
email string Oui
first_name string Oui
last_name string Oui
mobile string Oui
notes string Oui
phone string Oui

Réponses

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

Exemple de requête

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

Une réponse réussie renvoie un Contact.

Exemple de réponse

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

Paramètres

Nom Emplacement Type Requis Description
id path string Oui Contact id (ct-…).
limit query integer Max rows (default 50, max 500).

Réponses

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

Exemple de requête

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

Exemple de réponse

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

Schémas#

Contact#

Champ Type Requis Description
calls integer Oui
company string
created_at string (date-time) Oui
custom object
email string
external_ids map of string
first_name string Oui
id string Oui
last_call_at string (date-time)
last_name string
mobile string
notes string
phone string
source string
updated_at string (date-time) Oui

ContactFieldDef#

Champ Type Requis Description
key string Oui
label string Oui
options array of string
pbx_field string
required boolean Oui
show_in_list boolean Oui
type string Oui

ContactFieldsRequest#

Champ Type Requis Description
fields array of ContactFieldDef Oui

ContactRequest#

Champ Type Requis Description
company string Oui
custom object
email string Oui
first_name string Oui
last_name string Oui
mobile string Oui
notes string Oui
phone string Oui

Error#

Error envelope returned for non-2xx responses.

Champ Type Requis Description
error object Oui

La console

Ces pages sont en lecture seule. L'appel de test, les clés API et la référence de l'API à jour se trouvent dans la console, où votre compte est connecté.

Ouvrir la console