Voiceland AI

API-Referenz / Contacts

Contacts

Die Endpoints der Gruppe Contacts der Voiceland AI API, mit Parametern, Schemata und Beispielen mit curl.

Zuletzt aktualisiert:

Die Beschreibungen der Endpoints und der Felder erscheinen auf Englisch, genau so, wie die API sie ausliefert. Das ist Absicht: Sie lesen hier, was Sie auch in den Antworten sehen.

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

Parameter

Name Ort Typ Erforderlich Beschreibung
phone query string Exact-number lookup.
q query string Free-text filter.
limit query integer Max rows (default 500).

Antworten

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

Beispielanfrage

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

Beispielantwort

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

Anfragetext

application/json Schema: ContactRequest

Feld Typ Erforderlich Beschreibung
company string Ja
custom object
email string Ja
first_name string Ja
last_name string Ja
mobile string Ja
notes string Ja
phone string Ja

Antworten

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

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein Contact.

Beispielantwort

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

Parameter

Name Ort Typ Erforderlich Beschreibung
limit query integer Max rows (default 50, max 500).

Antworten

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

Beispielanfrage

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

Beispielantwort

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

Antworten

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

Beispielanfrage

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

Beispielantwort

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

Anfragetext

application/json Schema: ContactFieldsRequest

Feld Typ Erforderlich Beschreibung
fields array of ContactFieldDef Ja

Antworten

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

Beispielanfrage

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

Beispielantwort

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

Parameter

Name Ort Typ Erforderlich Beschreibung
id path string Ja Contact id (ct-…).

Antworten

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

Beispielanfrage

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

GET /v1/contacts/{id}#

Get a contact.

Parameter

Name Ort Typ Erforderlich Beschreibung
id path string Ja Contact id (ct-…).

Antworten

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

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein Contact.

Beispielantwort

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

Parameter

Name Ort Typ Erforderlich Beschreibung
id path string Ja Contact id (ct-…).

Anfragetext

application/json Schema: ContactRequest

Feld Typ Erforderlich Beschreibung
company string Ja
custom object
email string Ja
first_name string Ja
last_name string Ja
mobile string Ja
notes string Ja
phone string Ja

Antworten

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

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein Contact.

Beispielantwort

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

Parameter

Name Ort Typ Erforderlich Beschreibung
id path string Ja Contact id (ct-…).
limit query integer Max rows (default 50, max 500).

Antworten

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

Beispielanfrage

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

Beispielantwort

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

Schemata#

Contact#

Feld Typ Erforderlich Beschreibung
calls integer Ja
company string
created_at string (date-time) Ja
custom object
email string
external_ids map of string
first_name string Ja
id string Ja
last_call_at string (date-time)
last_name string
mobile string
notes string
phone string
source string
updated_at string (date-time) Ja

ContactFieldDef#

Feld Typ Erforderlich Beschreibung
key string Ja
label string Ja
options array of string
pbx_field string
required boolean Ja
show_in_list boolean Ja
type string Ja

ContactFieldsRequest#

Feld Typ Erforderlich Beschreibung
fields array of ContactFieldDef Ja

ContactRequest#

Feld Typ Erforderlich Beschreibung
company string Ja
custom object
email string Ja
first_name string Ja
last_name string Ja
mobile string Ja
notes string Ja
phone string Ja

Error#

Error envelope returned for non-2xx responses.

Feld Typ Erforderlich Beschreibung
error object Ja

Die Konsole

Diese Seiten sind schreibgeschützt. Der Testanruf, die API-Schlüssel und die aktuelle API-Referenz finden Sie in der Konsole, in der Ihr Konto angemeldet ist.

Konsole öffnen