Free demo accountSign in

Developer API

Connect contacts, appointments, conversations and calls to your own CRM or practice software. For real-time events, add a signed webhook under Settings › Integrations › Webhooks.

  • Base URLhttps://zilko.co/api/v1
  • Version 1.0.0
  • OpenAPI 3.1
Contents

Getting started

The ZILKO REST API connects your business’s contacts, appointments, conversations and calls to your own CRM, practice software or automation tool. Requests and responses are JSON; all times are ISO 8601 in UTC.

  1. In the panel, create a key under Settings › Integrations › Developer API. Choose “Read and write” access if you will create contacts or appointments. /clinic/settings?tab=integrations
  2. Send the key in the Authorization header with every request and call the endpoints below.
  3. Add a signed webhook to hear about new contacts, appointments and calls the moment they happen.
curl "https://zilko.co/api/v1/me" \
  -H "Authorization: Bearer zk_live_…"

Authentication

Every request carries the key as a Bearer token. A key only sees its own business’s data and is shown in full only once, when created. If a key is lost or leaked, revoke it in the panel and create a new one.

Authorization: Bearer zk_live_…
ScopeAllows
readGET endpoints: contacts, appointments, free slots, team, conversations, calls.
writeIn addition to read, POST and PATCH: adding and updating contacts, notes, creating and updating appointments.

Keys do not work in demo accounts (409 DEMO_MODE); they start working once the account is activated.

Base URL

https://zilko.co/api/v1

All paths are relative to this URL. Only HTTPS is accepted.

Rate limit

120 requests per minute per key. Above the limit the API returns 429 RATE_LIMITED; wait a moment and retry. For bulk syncs, fetch only what changed with updatedSince.

Errors

Error responses always share the same envelope. code is for machines, message for people; for validation errors, fields tells you which field is invalid and why.

{
  "error": {
    "code": "VALIDATION",
    "message": "Invalid request",
    "fields": [{ "path": "startsAt", "message": "Invalid datetime" }]
  }
}
CodeMeaning
400 VALIDATIONInvalid request; fields gives details per field.
401 UNAUTHORIZEDThe key is missing, malformed or revoked.
403 FORBIDDENThe key’s scope is not enough (writing needs “write”) or the business is suspended (CLINIC_SUSPENDED).
404 NOT_FOUNDThe record was not found or belongs to another business.
409 CONFLICTThe time is taken, the record’s status does not allow it, or the account is a demo (DEMO_MODE).
429 RATE_LIMITEDThe per-minute limit (120) was exceeded.

Pagination

List endpoints use cursor pagination: the limit (1–100, default 50) and cursor parameters. Responses look like { items, nextCursor }; send nextCursor as cursor to get the next page. When nextCursor is null you are on the last page.

curl "https://zilko.co/api/v1/contacts?limit=50&cursor=clx8f2k1a0042" \
  -H "Authorization: Bearer zk_live_…"

{ "items": [ … ], "nextCursor": "clx8f2k1a0091" }

Webhooks

For real-time events, add an https URL under Settings › Integrations › Automation. Every delivery is a POST with a JSON body; Zapier, Make, n8n, Kommo and respond.io accept it directly.

Events

  • lead.created

    A new person’s first contact: name, phone, channel, language and first message.

  • conversation.summary

    When a conversation Zilko handled goes quiet for 30 minutes or the team takes over; last 10 messages.

  • appointment.created

    Appointment created: person, start and end, status, source and staff member.

  • appointment.updated

    Appointment changed (time, status or staff member).

  • appointment.cancelled

    Appointment cancelled.

  • call.ended

    Call ended: direction, duration, outcome and summary.

  • call.callback_requested

    During a call the person asked to talk to the team now: reason, short note and number to call back.

Headers

  • X-Zilko-Event

    event type, e.g. appointment.created

  • X-Zilko-Delivery

    delivery ID (the same on retries)

  • X-Zilko-Signature

    t=<unix seconds>,v1=<HMAC-SHA256 hex>

Verifying the signature: join the t from the header and the raw body as “t.body”, compute HMAC-SHA256 with the webhook’s signing key and compare it with v1 in constant time. Reject the request if t is older than 5 minutes. The id in the body is the event ID; use it to drop duplicates.

// Node.js (Express: express.raw({ type: 'application/json' }))
const crypto = require('crypto');
const header = req.get('X-Zilko-Signature'); // t=…,v1=…
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto.createHmac('sha256', process.env.ZILKO_SIGNING_KEY)
  .update(`${parts.t}.${req.body}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
  && Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;

If the receiver answers with anything other than 2xx, or does not answer within 10 seconds, Zilko retries 5 times over about an hour. After 50 failed deliveries in a row the URL is turned off and the business is notified.

Account

The business the key belongs to.

GET/me

The key’s business

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/me" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "business": {
    "id": "clx8f2k1a0001",
    "name": "Elif Sahin",
    "sector": "DENTAL",
    "timezone": "Europe/Istanbul",
    "locale": "en"
  },
  "key": {
    "name": "Elif Sahin",
    "scopes": [
      "read"
    ]
  }
}

Contacts

Customer, patient or guest records (CRM).

GET/contacts

List contacts

Parameters

  • qstringquery

    Search in name, phone or email.

  • stageStagequery

    NEW_LEAD, NO_ANSWER, AWAITING_MEDIA, CONSULTATION, CONFIRMED, LOST

  • updatedSincestring (date-time)query

    Records changed after this moment (for syncing).

  • cursorstringquery

    The nextCursor from the previous response.

  • limitintegerquery

    1–100 · default 50

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/contacts?limit=20" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "items": [
    {
      "id": "clx8f2k1a0001",
      "name": "Elif Sahin",
      "phone": "+49 151 0000000",
      "email": "elif@example.com",
      "country": "DE",
      "language": "en",
      "stage": "NEW_LEAD",
      "source": "INSTAGRAM",
      "createdAt": "2026-10-28T09:15:00.000Z",
      "updatedAt": "2026-10-28T09:15:00.000Z"
    }
  ],
  "nextCursor": "clx8f2k1a0042"
}
POST/contactsneeds the “write” scope

Add a contact (returns the existing contact when the phone or email matches)

Request body · ContactInput

  • namestringrequired

    max 160 chars

  • phonestring

    International format recommended (+49 …).

    max 40 chars

  • emailstring (email)
  • countrystring

    max 80 chars

  • languagestring

    max 32 chars

  • stageStage

    NEW_LEAD, NO_ANSWER, AWAITING_MEDIA, CONSULTATION, CONFIRMED, LOST

  • notestring

    First note on the contact.

    max 5000 chars

Responses

  • 200Existing contact with the same phone or email
  • 201Created
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl -X POST "https://zilko.co/api/v1/contacts" \
  -H "Authorization: Bearer zk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Elif Sahin",
    "phone": "+49 151 0000000",
    "email": "elif@example.com",
    "language": "en",
    "note": "Asked about implant prices."
  }'
Example response · 201
{
  "id": "clx8f2k1a0001",
  "name": "Elif Sahin",
  "phone": "+49 151 0000000",
  "email": "elif@example.com",
  "country": "DE",
  "language": "en",
  "stage": "NEW_LEAD",
  "source": "INSTAGRAM",
  "createdAt": "2026-10-28T09:15:00.000Z",
  "updatedAt": "2026-10-28T09:15:00.000Z"
}
GET/contacts/{id}

Get a contact

Parameters

  • idstringrequiredpath

    Contact ID

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/contacts/clx8f2k1a0001" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "id": "clx8f2k1a0001",
  "name": "Elif Sahin",
  "phone": "+49 151 0000000",
  "email": "elif@example.com",
  "country": "DE",
  "language": "en",
  "stage": "NEW_LEAD",
  "source": "INSTAGRAM",
  "createdAt": "2026-10-28T09:15:00.000Z",
  "updatedAt": "2026-10-28T09:15:00.000Z"
}
PATCH/contacts/{id}needs the “write” scope

Update a contact

Parameters

  • idstringrequiredpath

    Contact ID

Request body · ContactUpdate

  • namestring
  • phonestring | null
  • emailstring | null
  • countrystring | null
  • languagestring | null
  • stageStage

    NEW_LEAD, NO_ANSWER, AWAITING_MEDIA, CONSULTATION, CONFIRMED, LOST

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl -X PATCH "https://zilko.co/api/v1/contacts/clx8f2k1a0001" \
  -H "Authorization: Bearer zk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "NEW_LEAD"
  }'
Example response · 200
{
  "id": "clx8f2k1a0001",
  "name": "Elif Sahin",
  "phone": "+49 151 0000000",
  "email": "elif@example.com",
  "country": "DE",
  "language": "en",
  "stage": "NEW_LEAD",
  "source": "INSTAGRAM",
  "createdAt": "2026-10-28T09:15:00.000Z",
  "updatedAt": "2026-10-28T09:15:00.000Z"
}
POST/contacts/{id}/notesneeds the “write” scope

Add a note to a contact

Parameters

  • idstringrequiredpath

    Contact ID

Request body

  • textstringrequired

    max 5000 chars

Responses

  • 201Added
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl -X POST "https://zilko.co/api/v1/contacts/clx8f2k1a0001/notes" \
  -H "Authorization: Bearer zk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Called back, wants a quote by email."
  }'
Example response · 201
{
  "id": "clx8f2k1a0001",
  "text": "Hello, I would like information about implants.",
  "createdAt": "2026-10-28T09:15:00.000Z"
}

Appointments

Appointments and reservations; free slots.

GET/appointments

List appointments

Parameters

  • fromstring (date-time)query

    Start (inclusive). Default: now.

  • tostring (date-time)query

    End (exclusive). Default: 30 days from now.

  • statusAppointmentStatusquery

    PENDING, BOOKED, CONFIRMED, COMPLETED, CANCELLED, NO_SHOW

  • contactIdstringquery
  • cursorstringquery

    The nextCursor from the previous response.

  • limitintegerquery

    1–100 · default 50

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/appointments?limit=20" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "items": [
    {
      "id": "clx8f2k1a0001",
      "contactId": "clx8f2k1a0001",
      "contact": {
        "id": "clx8f2k1a0001",
        "name": "Elif Sahin",
        "phone": "+49 151 0000000"
      },
      "staffId": "stf_3k9d",
      "startsAt": "2026-10-30T11:00:00.000Z",
      "endsAt": "2026-10-30T11:30:00.000Z",
      "status": "PENDING",
      "kind": "CONSULTATION",
      "source": "INSTAGRAM",
      "partySize": 2,
      "notes": "First visit",
      "createdAt": "2026-10-28T09:15:00.000Z"
    }
  ],
  "nextCursor": "clx8f2k1a0042"
}
POST/appointmentsneeds the “write” scope

Create an appointment

Pass contactId or contact. With contact, the person matching by phone or email is used, otherwise a new one is created. A clashing time returns 409.

Request body · AppointmentInput

  • contactIdstring
  • contactContactInput
  • startsAtstring (date-time)required
  • durationMininteger

    Default 30 (seating time at a restaurant).

    5–480

  • endsAtstring (date-time)

    Check-out at a hotel.

  • kindstring
  • staffIdstring
  • partySizeinteger

    1–500

  • notesstring

    max 2000 chars

Responses

  • 201Created
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 409The time is taken or the record’s status does not allow it
  • 429120 requests per minute per key
Request
curl -X POST "https://zilko.co/api/v1/appointments" \
  -H "Authorization: Bearer zk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "name": "Elif Sahin",
      "phone": "+49 151 0000000"
    },
    "startsAt": "2026-10-30T11:00:00.000Z",
    "durationMin": 30,
    "notes": "First visit"
  }'
Example response · 201
{
  "id": "clx8f2k1a0001",
  "contactId": "clx8f2k1a0001",
  "contact": {
    "id": "clx8f2k1a0001",
    "name": "Elif Sahin",
    "phone": "+49 151 0000000"
  },
  "staffId": "stf_3k9d",
  "startsAt": "2026-10-30T11:00:00.000Z",
  "endsAt": "2026-10-30T11:30:00.000Z",
  "status": "PENDING",
  "kind": "CONSULTATION",
  "source": "INSTAGRAM",
  "partySize": 2,
  "notes": "First visit",
  "createdAt": "2026-10-28T09:15:00.000Z"
}
GET/appointments/{id}

Get an appointment

Parameters

  • idstringrequiredpath

    Appointment ID

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/appointments/clx8f2k1a0007" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "id": "clx8f2k1a0001",
  "contactId": "clx8f2k1a0001",
  "contact": {
    "id": "clx8f2k1a0001",
    "name": "Elif Sahin",
    "phone": "+49 151 0000000"
  },
  "staffId": "stf_3k9d",
  "startsAt": "2026-10-30T11:00:00.000Z",
  "endsAt": "2026-10-30T11:30:00.000Z",
  "status": "PENDING",
  "kind": "CONSULTATION",
  "source": "INSTAGRAM",
  "partySize": 2,
  "notes": "First visit",
  "createdAt": "2026-10-28T09:15:00.000Z"
}
PATCH/appointments/{id}needs the “write” scope

Update, confirm or cancel an appointment

Parameters

  • idstringrequiredpath

    Appointment ID

Request body · AppointmentUpdate

  • startsAtstring (date-time)
  • durationMininteger

    5–480

  • endsAtstring (date-time)
  • statusstring

    CONFIRMED, CANCELLED, COMPLETED, NO_SHOW

  • staffIdstring | null
  • partySizeinteger

    1–500

  • notesstring | null

    max 2000 chars

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 409The time is taken or the record’s status does not allow it
  • 429120 requests per minute per key
Request
curl -X PATCH "https://zilko.co/api/v1/appointments/clx8f2k1a0007" \
  -H "Authorization: Bearer zk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CONFIRMED"
  }'
Example response · 200
{
  "id": "clx8f2k1a0001",
  "contactId": "clx8f2k1a0001",
  "contact": {
    "id": "clx8f2k1a0001",
    "name": "Elif Sahin",
    "phone": "+49 151 0000000"
  },
  "staffId": "stf_3k9d",
  "startsAt": "2026-10-30T11:00:00.000Z",
  "endsAt": "2026-10-30T11:30:00.000Z",
  "status": "PENDING",
  "kind": "CONSULTATION",
  "source": "INSTAGRAM",
  "partySize": 2,
  "notes": "First visit",
  "createdAt": "2026-10-28T09:15:00.000Z"
}
GET/availability

Free slots

Parameters

  • datestring (date)query

    First day (in the business’s time zone). Default: today.

  • daysintegerquery

    1–14 · default 7

  • staffIdstringquery

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/availability" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "timezone": "Europe/Istanbul",
  "slots": [
    {
      "startsAt": "2026-10-30T11:00:00.000Z",
      "endsAt": "2026-10-30T11:30:00.000Z",
      "staffId": "stf_3k9d"
    }
  ]
}
GET/staff

Team (doctors, specialists, staff)

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/staff" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "items": [
    {
      "id": "clx8f2k1a0001",
      "name": "Elif Sahin",
      "title": "Dr.",
      "specialty": "Implant",
      "active": true
    }
  ]
}

Conversations

Instagram, WhatsApp and Messenger conversations (read-only).

GET/conversations

List conversations (by latest message)

Parameters

  • channelChannelquery

    INSTAGRAM, WHATSAPP, MESSENGER

  • contactIdstringquery
  • cursorstringquery

    The nextCursor from the previous response.

  • limitintegerquery

    1–100 · default 50

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/conversations?limit=20" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "items": [
    {
      "id": "clx8f2k1a0001",
      "channel": "INSTAGRAM",
      "contact": {
        "id": "clx8f2k1a0001",
        "name": "Elif Sahin"
      },
      "aiEnabled": true,
      "unread": 1,
      "lastMessageAt": "2026-10-28T09:15:00.000Z",
      "preview": "Is Thursday 2 pm OK?"
    }
  ],
  "nextCursor": "clx8f2k1a0042"
}
GET/conversations/{id}/messages

Messages in a conversation (newest first)

Parameters

  • idstringrequiredpath

    Conversation ID

  • cursorstringquery

    The nextCursor from the previous response.

  • limitintegerquery

    1–100 · default 50

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/conversations/cnv_7h2m/messages?limit=20" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "items": [
    {
      "id": "clx8f2k1a0001",
      "direction": "IN",
      "author": "PATIENT",
      "text": "Hello, I would like information about implants.",
      "createdAt": "2026-10-28T09:15:00.000Z"
    }
  ],
  "nextCursor": "clx8f2k1a0042"
}

Calls

Voice assistant calls with summary and transcript (read-only).

GET/calls

List calls

Parameters

  • fromstring (date-time)query
  • tostring (date-time)query
  • contactIdstringquery
  • cursorstringquery

    The nextCursor from the previous response.

  • limitintegerquery

    1–100 · default 50

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/calls?limit=20" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "items": [
    {
      "id": "clx8f2k1a0001",
      "contactId": "clx8f2k1a0001",
      "direction": "INBOUND",
      "channel": "PHONE",
      "outcome": "ANSWERED",
      "startedAt": "2026-10-30T11:00:00.000Z",
      "durationSec": 192,
      "summary": "Asked about implant prices; booked for Thursday 2 pm."
    }
  ],
  "nextCursor": "clx8f2k1a0042"
}
GET/calls/{id}

Get a call (summary and transcript)

Parameters

  • idstringrequiredpath

    Call ID

Responses

  • 200Success
  • 400Invalid request
  • 401Missing, invalid or revoked key
  • 403The key’s scope is not enough (writing needs "write")
  • 404Record not found
  • 429120 requests per minute per key
Request
curl "https://zilko.co/api/v1/calls/cll_5p1q" \
  -H "Authorization: Bearer zk_live_…"
Example response · 200
{
  "id": "clx8f2k1a0001",
  "contactId": "clx8f2k1a0001",
  "direction": "INBOUND",
  "channel": "PHONE",
  "outcome": "ANSWERED",
  "startedAt": "2026-10-30T11:00:00.000Z",
  "durationSec": 192,
  "summary": "Asked about implant prices; booked for Thursday 2 pm.",
  "transcript": [
    {
      "role": "zilko",
      "text": "Hello, I would like information about implants.",
      "t": 4.2
    }
  ]
}
Chat on WhatsApp