Quickstarts

Every example assumes a key in $TKANA_KEY and the development base URL. Swap in https://api.tkana.sa/public/v1 for production.

export TKANA_KEY="tko_..."
export TKANA_API="https://api-dev.tkana.sa/public/v1"

Pull your customer list into a CRM

Needs read:customers.

curl

curl -s "$TKANA_API/customers?limit=50" \
  -H "Authorization: Bearer $TKANA_KEY"

fetch

const res = await fetch(`${process.env.TKANA_API}/customers?limit=50`, {
  headers: { Authorization: `Bearer ${process.env.TKANA_KEY}` },
});
const { data, pagination } = await res.json();

{
  "data": [
    {
      "id": "3f1c…",
      "phone": "+966501234567",
      "firstName": "Sara",
      "lastName": "Ali",
      "tags": ["vip"],
      "createdAt": "2026-01-04T08:12:00.000Z",
      "updatedAt": "2026-03-01T10:00:00.000Z"
    }
  ],
  "pagination": { "total": 128, "limit": 50, "offset": 0, "hasMore": true }
}

To keep that list current afterwards, do not page it again — sync it.

Mirror a ticket queue into a helpdesk

Needs read:tickets. Filter to the work that is still open, newest first.

curl -s "$TKANA_API/tickets?status=open&priority=high" \
  -H "Authorization: Bearer $TKANA_KEY"

A ticket carries its customer inline, so a queue view needs no second request:

{
  "id": "9b2e…",
  "requestNumber": "T-1042",
  "subject": "Refund not received",
  "status": "open",
  "priority": "high",
  "customer": { "id": "3f1c…", "firstName": "Sara", "lastName": "Ali", "phone": "+966501234567" },
  "slaDueAt": "2026-03-05T12:00:00.000Z"
}

Looking one up by the reference a customer quoted works too — ?search=T-1042 matches a request number exactly, and the subject and description by substring.

For the full story of one ticket, read its history:

curl -s "$TKANA_API/tickets/9b2e…/history" \
  -H "Authorization: Bearer $TKANA_KEY"

Entries come oldest first and say what changed: created, status_changed with from and to, assigned, updated, and comment.

Show this week’s appointments in a calendar

Needs read:bookings. from and to are inclusive days.

curl -s "$TKANA_API/bookings?from=2026-04-06&to=2026-04-12&status=confirmed" \
  -H "Authorization: Bearer $TKANA_KEY"

Dates and times are local to the organization

date, startTime and endTime are the organization’s own wall clock — 2026-04-06 and 14:30, not an instant. Do not convert them to UTC and back; render them as given. The only place you get real instants is availability, below.

Offer bookable times

Needs read:services.

1. List what can be booked.

   curl -s "$TKANA_API/services" -H "Authorization: Bearer $TKANA_KEY"

2. Find who provides it.

   curl -s "$TKANA_API/services/$SERVICE/resources" -H "Authorization: Bearer $TKANA_KEY"

3. Ask for free slots, at most 31 days at a time.

   curl -s "$TKANA_API/services/$SERVICE/resources/$RESOURCE/availability?from=2026-04-06&to=2026-04-12" \
     -H "Authorization: Bearer $TKANA_KEY"

{
  "data": [
    { "startAt": "2026-04-06T06:00:00.000Z", "endAt": "2026-04-06T07:00:00.000Z" },
    { "startAt": "2026-04-06T08:00:00.000Z", "endAt": "2026-04-06T09:00:00.000Z" }
  ]
}

Slots are real instants, already filtered by the resource’s working hours, existing bookings, the service’s buffers, and its lead-time and booking-horizon rules. A range wider than 31 days is refused with 422 rather than silently shortened.