Afspraken

Afspraken worden in Schedulinq gemaakt: door een beller vanuit een planningslink, door de klant vanuit een uitnodiging of de boekingspagina, of door je team. De API leest ze terug, zodat je CRM kan laten zien wat er is geboekt. Wil je wijzigingen meteen horen, gebruik dan webhooks: elke webhook over een afspraak heeft dezelfde vorm als deze antwoorden.

Eén uitlezen

GET /api/v1/appointments/{id} (recht appointments:read):

curl https://api.schedulinq.com/api/v1/appointments/3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e09 \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY"

{
  "address": {
    "city": "Amsterdam",
    "country": "NL",
    "line1": "Keizersgracht 100",
    "postalCode": "1015 AA"
  },
  "cancellationReason": "Ziek",
  "cancelledAt": "2026-10-12T15:30:00+02:00",
  "cancelledBy": "CUSTOMER",
  "colleagues": [
    {
      "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
      "name": "Offertebezoek"
    }
  ],
  "createdAt": "2026-10-01T09:00:00+02:00",
  "customerId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e06",
  "end": "2026-10-14T11:00:00+02:00",
  "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e09",
  "invitationId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e08",
  "lineageRootId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e09",
  "location": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
    "name": "Offertebezoek"
  },
  "locationMode": "AT_CUSTOMER",
  "meetingProvider": "GOOGLE_MEET",
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "metadata": {
    "campaignId": "C-42",
    "dealId": "D-123"
  },
  "planningLinkId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e07",
  "rescheduledFromId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e09",
  "service": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
    "name": "Offertebezoek"
  },
  "start": "2026-10-14T10:00:00+02:00",
  "status": "CONFIRMED",
  "timeZone": "Europe/Amsterdam",
  "updatedAt": "2026-10-01T09:00:00+02:00"
}

Een gearchiveerde afspraak, of die van een andere organisatie, antwoordt 404 errors.api.appointmentNotFound.

Zoeken op kenmerk

GET /api/v1/appointments zoekt de afspraken met je kenmerken — bijvoorbeeld het deal-id dat je op de planningslink of uitnodiging zette.

curl --globoff "https://api.schedulinq.com/api/v1/appointments?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z&metadata[dealId]=D-123&limit=25" \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY"

• metadata[<key>]=<value> moet precies overeenkomen. Minstens één is verplicht, en elk filter dat je meestuurt moet kloppen. De haken mogen zo of als %5B en %5D. Zie Kenmerken.
• status geeft alleen afspraken met die status.
• from (inclusief) en to (exclusief) gaan over het begin. Stuur ze als datum-tijd met een offset; schrijf de + van een offset als %2B, of gebruik Z.
• Met limit (1 tot 100) en cursor blader je door de resultaten: geef de nextCursor van de vorige pagina mee.

Een onbekende queryparameter wordt geweigerd: een typfout als metdata[dealId] is een 400 errors.validation.unknownField, niet de lijst van alle afspraken.

De resultaten staan op volgorde van aanmaken, de oudste eerst, en een cursor gaat er één keer doorheen. Een afspraak die nog wordt opgeslagen terwijl je voorbij het moment van aanmaken bladert, komt niet meer bij die cursor terug. Wil je bijwerken, doe de zoekvraag dan opnieuw vanaf het begin; wil je bijblijven, volg dan de webhooks.

Statussen

Schedulinq gebruikt nu drie statussen:

• CONFIRMED — geboekt;
• COMPLETED — afgerond, ook als de factuur is verstuurd;
• CANCELLED — geannuleerd.

PENDING en NO_SHOW staan in de lijst met waarden, maar niets zet ze nog.

Een geannuleerde afspraak heeft ook cancelledAt, cancellationReason (als er een reden is opgegeven) en cancelledBy: CUSTOMER, STAFF, SYSTEM, of STAFF_RESCHEDULE als een teamlid hem met Verzetten annuleerde zodat de klant een nieuw moment kan boeken.

Als een afspraak naar een nieuw id verhuist

Een klant die via de eigen link verzet, verplaatst de afspraak niet: de oude wordt geannuleerd en er komt een nieuwe. De nieuwe afspraak heeft:

• rescheduledFromId — de afspraak die ze vervangt;
• lineageRootId — de eerste afspraak van de boeking, hoe vaak die ook verhuisde.

Sla je gegevens op onder lineageRootId als die er is, en anders onder id, dan hou je één record per boeking. Of volg appointment.rescheduled: die komt binnen op de nieuwe afspraak en noemt de oude. Zie Webhook-gebeurtenissen.

Gebruikt een teamlid Verzetten, dan wordt de afspraak geannuleerd met cancelledBy: STAFF_RESCHEDULE, en krijgt de klant een uitnodiging om een nieuw moment te boeken. De afspraak die de klant dan boekt, heeft op dezelfde manier rescheduledFromId en lineageRootId, en krijgt ook je kenmerken mee.

Wat erin staat

• Tijden als datum-tijd met de offset van de tijdzone van je organisatie, plus timeZone (een IANA-naam als Europe/Amsterdam).
• De dienst en de teamleden, met id en naam.
• De klant als customerId, zonder naam of contactgegevens.
• Waar het plaatsvindt: locationMode (AT_CUSTOMER, ON_LOCATION, VIDEO of PHONE), het address van het bezoek als het bij de klant is, de location als het op een van jouw locaties is, en bij een videogesprek de meetingUrl zodra die er is.
• invitationId of planningLinkId als de afspraak vanuit een van die twee is geboekt.
• Je kenmerken, als metadata.

Steeds opvragen

Gebruik liever webhooks: die komen binnen enkele seconden na een wijziging binnen en kosten je geen verzoeken. Gebruik de lijst af en toe om bij te werken, bijvoorbeeld als je webhook-ontvanger plat lag. Zie Limieten.

Veelgestelde vragen

Kan ik een afspraak maken of wijzigen via de API?

Nee. Afspraken worden in Schedulinq gemaakt — door je team vanuit een planningslink, of door de klant vanuit een uitnodiging — zodat de planner en de boekingspagina elk moment controleren. Wijzigen doe je in het dashboard.

Waarom staat er geen klantnaam in het antwoord?

Kenmerken en de customerId koppelen de afspraak aan de lead in je CRM, die de gegevens van de klant al heeft. Ze nog eens meesturen zou persoonsgegevens verder verspreiden dan nodig is.