Kolio REST API and webhooks

10.1What does the Kolio REST API do?

Kolio REST API is an HTTP/JSON interface under the base URL https://kolio.si/api/integrations/v1 through which an external system reads and changes the bookings (calendar), CRM contacts and tasks of one Kolio account; it authenticates with an API key that determines both the account (tenant) and the permitted scope.

All three entry points — the application UI, the REST API and the MCP server — write through the same business cores. A booking created over the API goes through the same location opening hours, free performer and overlap checks as one your team enters in the calendar; a task gets the same timeline as in the CRM. An integration therefore cannot create a record the application itself would refuse.

10.2How do I create an API key?

An API key is created by a member with the Settings permission on the Settings → MCP sources and integrations page, in the API keys section; the full key is shown only once, and the database keeps only its SHA-256 hash and a visible prefix.

10.3How do I authenticate?

Send the key in the Authorization: Bearer kolio_sk_… header or in the X-API-Key: kolio_sk_… header; the account (tenant) is always derived from the key and never from the request body or URL, so one key can never reach another account's data.

curl -s https://kolio.si/api/integrations/v1/ping \
  -H "Authorization: Bearer kolio_sk_…"

# response
{
  "ok": true,
  "tenantId": "…",
  "scopes": ["contacts:read", "bookings:write"],
  "timestamp": "2026-09-15T08:12:03.512Z"
}

All other endpoints return { "data": … } on success and { "error": "code", "message": "explanation in Slovenian" } on failure. The error code is stable and meant for program logic; the message is meant for people.

10.4Scopes and permissions

Every API key scope maps to an existing member permission in Kolio, so a key never opens an area the application itself does not know; scopes are exact strings with no hierarchy — contacts:write does not include contacts:read.

10.5Which endpoints are available?

Integrations API v1 has eight paths: ping, locations plus two each for bookings, contacts and tasks — the collection (GET list, POST create) and the single record (GET, PATCH, DELETE); lists are limited by the limit parameter (default 50, maximum 200).

Bookings

curl -s -X POST https://kolio.si/api/integrations/v1/bookings \
  -H "Authorization: Bearer kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "slotStart": "2026-09-22T09:00",
    "serviceId": "<service id>",
    "contactId": "<contact id>",
    "locationId": "<location id from GET /locations>",
    "notes": "Booking from the webshop"
  }'

# 201
{ "data": { "id": "…", "slotStart": "2026-09-22T07:00:00.000Z",
            "slotEnd": "2026-09-22T07:30:00.000Z", "status": "confirmed",
            "serviceId": "…", "contactId": "…", "locationId": "…", "locationName": "Ljubljana",
            "source": "api", "…": "…" } }

# 422 — outside the location's opening hours, no free performer or assignee is not a member
{ "error": "booking_rejected", "message": "Termin je izven delovnega časa lokacije." }

REST v1 does not offer a free-slot list; free times are returned by the find_free_slots tool on the MCP server. You can also check occupancy with GET /bookings?from=…&to=… together with the locations' opening hours from GET /locations, which you set in calendar and services. Writes over the API are strict: a slot outside the location's opening hours or without a free performer returns 422 booking_rejected; only the team can enter exceptions in the calendar.

Contacts

curl -s -X POST https://kolio.si/api/integrations/v1/contacts \
  -H "X-API-Key: kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ana",
    "lastName": "Novak",
    "email": "ana.novak@example.com",
    "phone": "+38640123456",
    "externalId": "erp-10482",
    "tags": ["webshop"],
    "gdprConsent": true
  }'

# 201
{ "data": { "id": "…", "firstName": "Ana", "lastName": "Novak",
            "email": "ana.novak@example.com", "externalId": "erp-10482", "…": "…" } }

# 422
{ "error": "missingFields",
  "message": "Kontakt potrebuje vsaj eno od polj: ime, priimek, telefon ali e-pošta." }

Check whether the contact already exists before creating it: GET /contacts?email=…, ?phone=… or ?externalId=… return exact matches, while ?q=… searches first name, last name, email, phone and company. The externalId field is meant for the customer's id in your system (ERP, webshop).

Tasks

# POST — new task
curl -s -X POST https://kolio.si/api/integrations/v1/tasks \
  -H "Authorization: Bearer kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call the customer about quote 2026-118",
    "contactId": "<contact id>",
    "assigneeEmail": "sales@your-company.com",
    "priority": 2,
    "dueAt": "2026-09-18T12:00"
  }'

# 201
{ "data": { "id": "tsk_…", "title": "Call the customer …", "status": "nova",
            "priority": 2, "dueAt": "2026-09-18T10:00:00.000Z", "…": "…" } }

# PATCH — complete the task with a comment
curl -s -X PATCH https://kolio.si/api/integrations/v1/tasks/tsk_… \
  -H "Authorization: Bearer kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "zakljucena", "comment": "The customer confirmed the quote." }'

# 422 — unknown assignee
{ "error": "unknownAssignee", "message": "…" }

10.6How does the API interpret time?

All input times are ISO 8601; a string with an offset or Z is taken literally, a string without an offset (2026-09-22T09:00) is read as local time in your account's time zone (Settings → General, default Europe/Ljubljana), and a plain date (2026-09-22) as midnight of that day in the same zone.

Responses return times as UTC instants with a trailing Z (e.g. 2026-09-22T07:00:00.000Z). The server runs in UTC; without this rule a booking sent as 09:00 without an offset would silently shift by one or two hours. The rule applies to slotStart, slotEnd, from, to and dueAt.

10.7How do webhooks work?

A webhook is an HTTP POST that Kolio sends to your URL when an event happens, with the JSON envelope { event, tenantId, timestamp, data } signed with HMAC-SHA256 (RFC 2104) in the X-Kolio-Signature header (format sha256= + hex HMAC); the event time is in the X-Kolio-Timestamp header and in the body's timestamp field, so the signature is bound to time. Delivery is one attempt, best effort (no retries).

POST /webhook HTTP/1.1
Content-Type: application/json
X-Kolio-Event: booking.created
X-Kolio-Timestamp: 2026-09-15T08:14:22.318Z
X-Kolio-Signature: sha256=3f1a9c…

{
  "event": "booking.created",
  "tenantId": "…",
  "timestamp": "2026-09-15T08:14:22.318Z",
  "data": {
    "bookingId": "…",
    "contactId": "…",
    "serviceId": "…",
    "slotStart": "2026-09-22T07:00:00.000Z",
    "slotEnd": "2026-09-22T07:30:00.000Z",
    "status": "confirmed"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyKolioSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

10.8Limits and good practice

Kolio REST API v1 has no idempotency key and no webhook retries, so the integration itself must prevent duplicate records — by checking for existence before creating and by storing the ids Kolio returns.

• Use a separate key with its own name for each integration — the timeline shows which integration acted, and you can revoke it without stopping the others.
• Before POST /contacts look the contact up by email, phone or externalId; before POST /bookings read the occupancy of the period and, with several locations, pass locationId.
• To cancel a booking use PATCH { "status": "cancelled" }, to close a task PATCH { "status": "arhivirana" }; DELETE is permanent and also removes the timeline.
• Send times with an offset and store the ids from responses (data.id) — they are the only reliable key for a later PATCH.
• Handle errors by the error field, not by the message text, which is meant for people and may change.