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
- In Tafels, open Settings → API and create a key.
- Send the key with every request, in the Authorization header.
- 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/restaurantBase 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." }400 | Invalid input, for example a date in the past or a missing field. |
401 | The API key is missing or not valid. |
402 | API access is switched off or not included in the plan. |
404 | The reservation does not exist, or belongs to another restaurant. |
409 | No suitable table is free, a ticket is full, or the reservation changed since you read it. |
415 | The body is not JSON. Send Content-Type: application/json. |
429 | More 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-DD | The day to check. |
guestsnumber | Party 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-DD | First day. |
toYYYY-MM-DD | Last day. Optional, defaults to from. |
statusstring | Optional. Only this status, for example Confirmed or Cancelled. |
emailstring | Optional. 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
namestring | Required. The guest’s name. |
emailstring | Optional. Needed for confirmation and reminder emails. |
phonestring | Optional. |
dateYYYY-MM-DD | Required. |
timeHH:MM | Required. A quarter hour. |
guestsnumber | Required. 1 to 20. |
ticketIdstring | Optional. Without it, the ticket that runs at this time is used. |
tableIdstring | Optional. Without it, the best free table is chosen. |
statusstring | Optional. Confirmed (default) or Waitlist. |
notesstring | Optional. Up to 1000 characters. |
langnl | en | Optional. The language of the guest’s emails. |
voucherCodestring | Optional. 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
versionnumber | Required. The version from your last read. |
statusstring | Optional. 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
idstring | Unique id. |
name, email, phonestring | Guest details. |
date, timestring | Arrival, in local time. |
guestsnumber | Party size. |
durationnumber | Minutes the table is held. |
tableIdstring | null | The assigned table. Null on the waitlist. |
ticketId, ticketNamestring | What was booked, such as Lunch. |
statusstring | Confirmed, Arrived, Seated, Completed, Cancelled, No-show or Waitlist. |
sourcestring | Online, Staff, Phone, Walk-in, Waitlist or API. |
channelstring | For online bookings: the ?via= of the booking link, such as instagram. Empty when booked directly. |
voucherCodestring | The deal or gift voucher code used, if any. |
notesstring | Notes from the guest or staff. |
langnl | en | The language of the guest’s emails. |
createdAtISO 8601 | When the reservation was made. |
versionnumber | Goes 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.created | A reservation was made, online, by staff or through the API. |
reservation.updated | A reservation changed: time, table, guests, status (for example Seated) or details. |
reservation.cancelled | A 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-Event | The event type, such as reservation.created. |
Tafels-Delivery | The delivery id. It stays the same when a delivery is retried. |
Tafels-Signature | t=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.