Contacts

Οι περιγραφές των 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).

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Αποκρίσεις

Παράδειγμα αιτήματος

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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Αποκρίσεις

Παράδειγμα αιτήματος

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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

GET /v1/contacts/{id}#

Get a contact.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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.

Παράμετροι

Σώμα αιτήματος

application/json Σχήμα: ContactRequest

Αποκρίσεις

Παράδειγμα αιτήματος

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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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#

ContactFieldDef#

ContactFieldsRequest#

ContactRequest#

Error#

Error envelope returned for non-2xx responses.