tafels.

RESOURCES

API documentation

Connect your own systems to Tafels, such as your website, a POS or a CRM. The API is included in the Premium plan.

Getting started

  1. In Tafels, open Settings → API and create a key.
  2. Send the key with every request, in the Authorization header.
  3. Keep the key secret. Anyone with it can read and change your reservations. Revoke keys you no longer use.
Authorization: Bearer tfl_…

GET https://tafels.app/api/v1/restaurant

Base URL: https://tafels.app/api/v1

Conventions

  • Requests and responses are JSON. Send Content-Type: application/json.
  • Dates are YYYY-MM-DD and times HH:MM on the quarter hour, in the restaurant’s local time (Europe/Amsterdam).
  • Each key can make 120 requests per minute.
  • Every reservation has a version that goes up by one with each change. Send it back when you change the reservation, so you never overwrite someone else’s change.

Errors

Errors come back as JSON with a readable message, in English, or in Dutch when you send Accept-Language: nl.

{ "error": "No suitable table is available at this time. Choose another time or join the waitlist." }
400Invalid input, for example a date in the past or a missing field.
401The API key is missing or not valid.
402API access is switched off or not included in the plan.
404The reservation does not exist, or belongs to another restaurant.
409No suitable table is free, a ticket is full, or the reservation changed since you read it.
415The body is not JSON. Send Content-Type: application/json.
429More than 120 requests in a minute with this key.

GET/api/v1/restaurant

The restaurant the key belongs to: name, contact details, booking page and closures.

Response

{
  "id": "…",
  "slug": "the-juniper-room",
  "name": "The Juniper Room",
  "address": "Prinsengracht 1, Amsterdam",
  "phone": "+31 20 123 4567",
  "email": "hello@juniper.example",
  "timezone": "Europe/Amsterdam",
  "bookingEnabled": true,
  "bookingPage": "https://tafels.app/book/the-juniper-room",
  "buffer": 15,
  "closures": [{ "from": "2026-12-31", "to": "2027-01-01", "closed": true, "note": "New Year" }]
}

GET/api/v1/tickets

Everything guests can book, such as Lunch or a Christmas menu, with days, arrival times, party sizes and limits. Prices are in cents.

Response

{
  "tickets": [{
    "id": "tk_2b1e…",
    "name": "Christmas dinner",
    "description": "Five courses",
    "active": true,
    "days": [0, 1, 2, 3, 4, 5, 6],
    "startDate": "2026-12-24",
    "endDate": "2026-12-26",
    "firstTime": "18:00",
    "lastTime": "19:30",
    "duration": 180,
    "minGuests": 2,
    "maxGuests": 6,
    "maxPerSlot": 12,
    "maxPerDay": 60,
    "rooms": ["Garden room"],
    "pricePerPerson": 8950,
    "depositPerPerson": null,
    "sort": 1,
    "showImage": true,
    "imageUrl": "https://tafels.app/api/images/img_4c1d…"
  }]
}

GET/api/v1/tables

All tables with their seats and room.

Response

{
  "tables": [
    { "id": "t-07", "name": "07", "seats": 4, "room": "Dining room", "shape": "square", "active": true }
  ]
}

GET/api/v1/availability?date=2026-12-24&guests=4

Bookable times for a date and party size, per ticket, as guests see them on the booking page.

Query parameters

dateYYYY-MM-DDThe day to check.
guestsnumberParty size, 1 to 20.

Response

{
  "tickets": [{
    "id": "tk_2b1e…",
    "name": "Christmas dinner",
    "description": "Five courses",
    "duration": 180,
    "minGuests": 2,
    "maxGuests": 6,
    "pricePerPerson": 8950,
    "depositPerPerson": null,
    "imageUrl": "https://tafels.app/api/images/img_4c1d…",
    "slots": [
      { "time": "18:00", "available": true },
      { "time": "18:15", "available": false }
    ]
  }]
}

GET/api/v1/reservations?from=2026-12-01&to=2026-12-31

Reservations in a date range of at most 93 days, ordered by date and time.

Query parameters

fromYYYY-MM-DDFirst day.
toYYYY-MM-DDLast day. Optional, defaults to from.
statusstringOptional. Only this status, for example Confirmed or Cancelled.
emailstringOptional. Only reservations for this guest email.

Response

{ "reservations": [ { …reservation } ] }

GET/api/v1/reservations/{id}

One reservation.

Response

{
  "id": "3f0c1a9e-6c1d-4a51-9a3e-2b8f4f0c7d21",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "phone": "+31 6 12345678",
  "date": "2026-12-24",
  "time": "19:00",
  "guests": 4,
  "tableId": "t-07",
  "ticketId": "tk_2b1e…",
  "ticketName": "Christmas dinner",
  "status": "Confirmed",
  "notes": "Window table if possible",
  "source": "API",
  "channel": "",
  "voucherCode": "",
  "duration": 180,
  "lang": "en",
  "createdAt": "2026-11-02T10:14:03.512Z",
  "version": 1
}

POST/api/v1/reservations

Creates a reservation with the same rules as staff bookings: a suitable table must be free, but ticket limits can be exceeded. The guest gets a confirmation email when emails are switched on.

Body

namestringRequired. The guest’s name.
emailstringOptional. Needed for confirmation and reminder emails.
phonestringOptional.
dateYYYY-MM-DDRequired.
timeHH:MMRequired. A quarter hour.
guestsnumberRequired. 1 to 20.
ticketIdstringOptional. Without it, the ticket that runs at this time is used.
tableIdstringOptional. Without it, the best free table is chosen.
statusstringOptional. Confirmed (default) or Waitlist.
notesstringOptional. Up to 1000 characters.
langnl | enOptional. The language of the guest’s emails.
voucherCodestringOptional. For deal tickets: uses up this code from the ticket’s list.

Example

curl -X POST https://tafels.app/api/v1/reservations \
  -H "Authorization: Bearer tfl_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","date":"2026-12-24","time":"19:00","guests":4}'

Response

{
  "id": "3f0c1a9e-6c1d-4a51-9a3e-2b8f4f0c7d21",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "phone": "+31 6 12345678",
  "date": "2026-12-24",
  "time": "19:00",
  "guests": 4,
  "tableId": "t-07",
  "ticketId": "tk_2b1e…",
  "ticketName": "Christmas dinner",
  "status": "Confirmed",
  "notes": "Window table if possible",
  "source": "API",
  "channel": "",
  "voucherCode": "",
  "duration": 180,
  "lang": "en",
  "createdAt": "2026-11-02T10:14:03.512Z",
  "version": 1
}

PATCH/api/v1/reservations/{id}

Changes a reservation. Send the version you last read plus the fields to change; other fields stay as they are.

If the reservation changed since you read it, the version no longer matches and you get a 409. Read it again and retry.

Body

versionnumberRequired. The version from your last read.
statusstringOptional. Confirmed, Arrived, Seated, Completed, Cancelled, No-show or Waitlist.
…Any other reservation field, such as date, time, guests or notes.

Example

curl -X PATCH https://tafels.app/api/v1/reservations/3f0c1a9e-… \
  -H "Authorization: Bearer tfl_…" \
  -H "Content-Type: application/json" \
  -d '{"version":1,"time":"19:30"}'

Response

{
  "id": "3f0c1a9e-6c1d-4a51-9a3e-2b8f4f0c7d21",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "phone": "+31 6 12345678",
  "date": "2026-12-24",
  "time": "19:30",
  "guests": 4,
  "tableId": "t-07",
  "ticketId": "tk_2b1e…",
  "ticketName": "Christmas dinner",
  "status": "Confirmed",
  "notes": "Window table if possible",
  "source": "API",
  "channel": "",
  "voucherCode": "",
  "duration": 180,
  "lang": "en",
  "createdAt": "2026-11-02T10:14:03.512Z",
  "version": 2
}

DELETE/api/v1/reservations/{id}

Cancels a reservation and frees its table. The reservation is kept with status Cancelled, and the guest gets a cancellation email when emails are switched on.

Response

{
  "id": "3f0c1a9e-6c1d-4a51-9a3e-2b8f4f0c7d21",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "phone": "+31 6 12345678",
  "date": "2026-12-24",
  "time": "19:00",
  "guests": 4,
  "tableId": "t-07",
  "ticketId": "tk_2b1e…",
  "ticketName": "Christmas dinner",
  "status": "Cancelled",
  "notes": "Window table if possible",
  "source": "API",
  "channel": "",
  "voucherCode": "",
  "duration": 180,
  "lang": "en",
  "createdAt": "2026-11-02T10:14:03.512Z",
  "version": 2
}

The reservation object

idstringUnique id.
name, email, phonestringGuest details.
date, timestringArrival, in local time.
guestsnumberParty size.
durationnumberMinutes the table is held.
tableIdstring | nullThe assigned table. Null on the waitlist.
ticketId, ticketNamestringWhat was booked, such as Lunch.
statusstringConfirmed, Arrived, Seated, Completed, Cancelled, No-show or Waitlist.
sourcestringOnline, Staff, Phone, Walk-in, Waitlist or API.
channelstringFor online bookings: the ?via= of the booking link, such as instagram. Empty when booked directly.
voucherCodestringThe deal or gift voucher code used, if any.
notesstringNotes from the guest or staff.
langnl | enThe language of the guest’s emails.
createdAtISO 8601When the reservation was made.
versionnumberGoes up by one with each change.

Webhooks

Webhooks let your system hear about changes straight away, instead of asking every few minutes. Add an HTTPS URL under Settings → API → Webhooks and choose the events. Tafels sends a POST with a JSON body for each event.

reservation.createdA reservation was made, online, by staff or through the API.
reservation.updatedA reservation changed: time, table, guests, status (for example Seated) or details.
reservation.cancelledA reservation was cancelled, by the guest or the restaurant.

Payload

{
  "id": "evt_9b2f…",
  "type": "reservation.created",
  "createdAt": "2026-11-02T10:14:03.601Z",
  "restaurant": "the-juniper-room",
  "data": {
    "reservation": { …reservation }
  }
}

Headers

Tafels-EventThe event type, such as reservation.created.
Tafels-DeliveryThe delivery id. It stays the same when a delivery is retried.
Tafels-Signaturet=timestamp,v1=signature. The signature is an HMAC-SHA256 of "timestamp.body" with your signing secret.

Checking the signature

Use the signing secret shown when you added the webhook. Reject events with a wrong signature or an old timestamp.

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

// In your webhook handler, with the raw request body as a string:
function isFromTafels(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const recent = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return recent && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ''));
}

Retries

Answer with a 2xx status within 5 seconds. Otherwise Tafels tries again after 1, 5 and 30 minutes, and after 2, 6, 12 and 24 hours. The same event can arrive more than once and events can arrive out of order: use the event id to skip duplicates and the reservation version to keep the newest.