Uitnodigingen · Schedulinq Docs

Een uitnodiging is de knop Uitnodigen in je CRM. Eén aanroep stuurt de klant een persoonlijke link om een dienst te boeken bij een van de teamleden die je koos; de klant kiest op je boekingspagina zelf een moment dat past. Het is dezelfde uitnodiging die je vanuit het dashboard kunt sturen, beschreven in Uitnodigingen versturen.

Het verzoek

POST /api/v1/invitations (recht invitations:write), met een Idempotency-Key:

Voorbeeldverzoek · POST /api/v1/invitations

IDEMPOTENCY_KEY=$(uuidgen)   # once per action; to retry, run only the curl line again (same key)
curl -X POST https://api.schedulinq.com/api/v1/invitations \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "address": {
    "city": "Amsterdam",
    "country": "NL",
    "line1": "Keizersgracht 100",
    "postalCode": "1015 AA"
  },
  "appointmentTypeId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
  "customer": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e06"
  },
  "metadata": {
    "campaignId": "C-42",
    "dealId": "D-123"
  },
  "users": [
    {
      "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e03"
    }
  ]
}'

Request body · POST /api/v1/invitations

{
  "address": {
    "city": "Amsterdam",
    "country": "NL",
    "line1": "Keizersgracht 100",
    "postalCode": "1015 AA"
  },
  "appointmentTypeId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
  "customer": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e06"
  },
  "metadata": {
    "campaignId": "C-42",
    "dealId": "D-123"
  },
  "users": [
    {
      "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e03"
    }
  ]
}

users zijn de teamleden waarbij de klant kan boeken: één of meer, hoogstens 100, elk als {"id": …} of {"email": …} en elk één keer. De boekingspagina biedt de momenten aan waarop een van hen vrij is, en de afspraak wordt bij een van hen geboekt — net als de teamleden die je in het dashboard bij een uitnodiging aanvinkt. Elk teamlid moet actief en inplanbaar zijn, en de dienst en elke extra doen. Een weigering noemt het item, bijvoorbeeld users[1].
appointmentTypeId is de dienst (GET /api/v1/services).
addOns zijn optioneel: elke extra één keer, aangeboden bij de dienst, en met een quantity boven één alleen als de extra dat toestaat.
customer is een bestaande klant op id — {"id": …} en verder niets — of de gegevens van de klant, die op e-mailadres wordt gezocht of aangemaakt. De regels zijn dezelfde als bij een planningslink.
address en metadata volgen dezelfde regels als bij een planningslink: het adres is dat van deze afspraak, nooit het factuuradres van de klant. Zie Kenmerken.
validUntil: zie Tot wanneer.

Met een klant die je al kent, op id:

Request body · POST /api/v1/invitations

{
  "address": {
    "city": "Amsterdam",
    "country": "NL",
    "line1": "Keizersgracht 100",
    "postalCode": "1015 AA"
  },
  "appointmentTypeId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
  "customer": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e06"
  },
  "metadata": {
    "campaignId": "C-42",
    "dealId": "D-123"
  },
  "users": [
    {
      "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e03"
    }
  ]
}

Een naam of duur stuur je niet mee. Schedulinq neemt de naam van de dienst, in de taal van je organisatie, en de duur van de dienst plus de extra's. Een dienst zonder eigen duur en zonder tijd van extra's geeft een 422 errors.validation.serviceHasNoDuration.

Een klant die op non-actief staat, wordt geweigerd met een 409 errors.api.customerDeactivated: die zou de link nooit kunnen boeken. Een id dat niet van een van je klanten is — onbekend, gearchiveerd, of van een andere organisatie — geeft een 404 errors.api.customerNotFound; een klant die is samengevoegd met een andere, wordt naar die andere gevolgd.

Wat er gebeurt

De uitnodiging gaat meteen weg, op naam en in de huisstijl van je organisatie, via je communicatiestappen — per e-mail, sms of WhatsApp, net als wanneer je er een vanuit het dashboard stuurt.

Antwoord · 201

{
  "address": {
    "city": "Amsterdam",
    "country": "NL",
    "line1": "Keizersgracht 100",
    "postalCode": "1015 AA"
  },
  "bookingPageClosed": false,
  "bookingUrl": "https://schedulinq.com/i/EXAMPLE-INVITATION",
  "colleagues": [
    {
      "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
      "name": "Offertebezoek"
    }
  ],
  "createdAt": "2026-10-01T09:00:00+02:00",
  "customerId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e06",
  "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e08",
  "initialEmailDeferred": false,
  "lineageRootId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e09",
  "location": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
    "name": "Offertebezoek"
  },
  "locationMode": "VIDEO",
  "metadata": {
    "campaignId": "C-42",
    "dealId": "D-123"
  },
  "rescheduledFromAppointmentId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e09",
  "service": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
    "name": "Offertebezoek"
  },
  "status": "PENDING",
  "updatedAt": "2026-10-01T09:00:00+02:00",
  "validUntil": "2026-10-31"
}

Het antwoord zegt dat het eerste bericht in de wachtrij staat, nooit dat het is verstuurd.
bookingPageClosed: true betekent dat je boekingspagina nu geen boekingen aanneemt. De uitnodiging bestaat, maar het eerste bericht wordt niet verstuurd, en de link komt uit op een gesloten pagina tot je je boekingspagina weer openzet.
initialEmailDeferred: true betekent dat het eerste bericht niet is verstuurd omdat de klant geen e-mailadres heeft.
bookingUrl is de persoonlijke link van de klant: die opent de boekingspagina met de gegevens van de klant ingevuld en boekt op diens naam. Geef hem alleen aan die klant. Log hem nooit, en laat hem nooit aan iemand anders zien.

In het dashboard staat bij de uitnodiging Aangemaakt: Via API met de naam van de sleutel. Verder gedraagt ze zich als elke andere uitnodiging: je team kan haar openen, wijzigen en opnieuw versturen.

Meerdere kopers per lead

Een tweede uitnodiging voor dezelfde klant en dienst is gewoon nog een uitnodiging: de API en het dashboard weigeren haar niet, en boeken met de ene sluit de andere niet. Zo kan een leadplatform één klant op twee manieren uitnodigen namens meerdere kopers: één uitnodiging per koper, die elk los worden geboekt, of één uitnodiging met meerdere kopers in users, van wie de klant er één boekt. Een herhaling van hetzelfde verzoek vangt de Idempotency-Key op: dezelfde sleutel met dezelfde body geeft de eerste uitnodiging terug en verstuurt niets. Zie Idempotentie.

Per organisatie gelden drie budgetten, hoeveel sleutels je ook hebt: 60 uitnodigingen per minuut, 5.000 per 24 uur, en 10 naar dezelfde klant per 24 uur, geteld op e-mailadres (een klant die je op id noemt, telt onder zijn e-mailadres). Die laatste antwoordt 429 errors.api.customerInvitationLimit. Zie Limieten.

Tot wanneer

validUntil is de laatste dag waarop de uitnodiging geboekt kan worden, als datum in de tijdzone van je organisatie. Zonder krijgt de uitnodiging de standaard van je organisatie, dezelfde die het dashboard voorstelt. Een datum in het verleden of te ver vooruit wordt geweigerd. Hoe de vervaldatum werkt, staat onder Tot wanneer de klant kan boeken.

Teruglezen

Met recht invitations:read:

GET /api/v1/invitations/{id} leest één uitnodiging.
GET /api/v1/invitations?metadata[dealId]=D-123 zoekt uitnodigingen op een kenmerk. Minstens één metadata[…]-filter is verplicht; status beperkt tot PENDING (kan geboekt worden), USED (geboekt), CANCELLED of EXPIRED; met limit en cursor blader je door de resultaten.

Voorbeeldverzoek · GET /api/v1/invitations

curl --globoff "https://api.schedulinq.com/api/v1/invitations?metadata[dealId]=D-123&limit=25" \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY"

bookingUrl staat alleen in het antwoord op het aanmaken (en op een herhaling daarvan met dezelfde Idempotency-Key), nooit bij het uitlezen of in een webhook. Heeft je systeem hem nodig, bewaar hem dan uit dat antwoord.

Zodra de klant boekt, is de uitnodiging USED en staan in appointmentIds de afspraken, de vroegste eerst. De webhook invitation.booked bevat dezelfde id's. Zie Webhook-gebeurtenissen.

Beëindigd in het dashboard

De API kan een uitnodiging niet intrekken; dat doet je team in het dashboard.

Een ingetrokken uitnodiging krijgt status CANCELLED, en de webhook invitation.cancelled.
Een gearchiveerde uitnodiging antwoordt vanaf dan 404, en de webhook is invitation.deleted.

Veelgestelde vragen

Kan ik één uitnodiging met meerdere diensten sturen?

Niet via de API. Een API-uitnodiging bevat één dienst, met de extra's, en de teamleden die je noemt. Meerdere diensten in één uitnodiging kun je vanuit het dashboard sturen.

De klant zegt dat er niets is aangekomen. Wat nu?

Lees de uitnodiging uit en kijk naar status. Kijk daarna op de pagina van de uitnodiging in het dashboard: de berichtentijdlijn laat zien of het bericht is verstuurd, en je team kan het daar opnieuw versturen.

Kan ik de boekingslink later nog zien?

Nee. Die staat alleen in het antwoord op het aanmaken. Bewaar hem dan als je hem nodig hebt, net zo zorgvuldig als een wachtwoord.