Appointment API

This API lets external information systems and AI agents book appointments with Ceder Verwarming on behalf of customers. All requests over HTTPS.

Authentication

Every request needs an API key in the HTTP header:

X-Api-Key: <your-key>

Do not have a key yet? Request one below. Provide your company name, contact details and a short description of the intended use. After approval by Ceder Verwarming you will receive the key by email. Do not share your key publicly.

Company name* Contact person* Email address* Phone number Address Postcode City

What will you use the API for?*

Request a key

Base URL

https://cederverwarming.nl/wp-json/ceder/v1

Time slots

The arrival time is a 2-hour window. Appointments are possible on all days. Note: the evening slot (18:00-20:00) and the whole weekend (Sat + Sun) are available only for service: "storing" (fixing a breakdown).

block	arrival between	breakdown only
0800-1000	08:00 - 10:00	no
0900-1100	09:00 - 11:00	no
1000-1200	10:00 - 12:00	no
1230-1430	12:30 - 14:30	no
1330-1530	13:30 - 15:30	no
1430-1630	14:30 - 16:30	no
1800-2000	18:00 - 20:00	yes (evening)

Evening, weekend and same-day rate

Evening, weekend and same-day appointments carry a rate (informational; the API does not charge any amounts). Rates do not stack, the highest percentage applies:

time	rate
same-day (booked on the day itself)	150%
weekday evening (18:00-20:00)	150%
Saturday	150%
Sunday	200%

The fields storing_only and surcharge_pct are returned per slot in GET /availability and in the response of POST /appointments.

Endpoints

GET /blocks

Returns the fixed time slots.

GET /availability

Returns free slots. Optional query parameters from and to (format YYYY-MM-DD) and service (e.g. storing). With service you only get slots in which that service may be booked (without service all bookable slots are returned, with the storing_only flag).

curl -H "X-Api-Key: YOUR_KEY" \
  "https://cederverwarming.nl/wp-json/ceder/v1/availability?from=2026-07-01&to=2026-07-15"

Response:

{
  "count": 42,
  "window_until": "2026-07-26",
  "available_slots": [
    { "date": "2026-07-01", "block": "0800-1000",
      "label": "08:00 - 10:00", "arrival_from": "08:00", "arrival_to": "10:00" }
  ]
}

POST /appointments

Books an appointment on behalf of a customer. Body in JSON.

field	required	description
customer.name	yes	name of the customer
customer.email	yes	email address (customer receives confirmation)
customer.phone	no	phone number
customer.address	yes	visiting address (must be within 40 km drive of Amsterdam)
customer.company	no	company name (business customer)
customer.kvk	no	Chamber of Commerce (KvK) number
customer.invoice_address	no	separate billing address
customer.invoice_email	no	billing email address (administration only)
date	yes	date YYYY-MM-DD
block	yes	time slot, e.g. 1000-1200
service	no	onderhoud, storing, vervangen or anders. For weekend or evening slots only storing is allowed.
notes	no	notes

curl -X POST "https://cederverwarming.nl/wp-json/ceder/v1/appointments" \
  -H "X-Api-Key: UW_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "Jan Jansen", "email": "jan@voorbeeld.nl",
                  "phone": "020 244 2926", "address": "Silvoldestraat 94, Amsterdam" },
    "date": "2026-07-02", "block": "1000-1200",
    "service": "onderhoud", "notes": "CV-ketel Nefit"
  }'

Response (201):

{
  "status": "ok",
  "appointment": {
    "id": 12, "date": "2026-07-02", "block": "1000-1200",
    "label": "10:00 - 12:00", "service": "Boiler or ventilation maintenance",
    "customer": { "name": "Jan Jansen", "email": "jan@voorbeeld.nl" }
  },
  "message": "Appointment scheduled. The customer receives a confirmation by email."
}

Error codes

status	meaning
400	required fields missing or invalid
401	API key missing or invalid
403	email address not allowed
409	time slot unavailable or just taken
422	address is outside the service area (more than 40 km)

An appointment via the API is final immediately (no email verification needed); the customer does receive a confirmation email.