Planningslinks · Schedulinq Docs

Een planningslink is de knop Plan in je CRM. Wie de lead aan de telefoon heeft, klikt erop, en de planner van Schedulinq opent met de klant, het teamlid, de dienst en het adres al ingevuld. Die kiest een moment, slaat de afspraak op en gaat terug naar het CRM. Wat de beller in Schedulinq ziet, staat in Afspraakmogelijkheden zoeken.

Zo werkt het

Klikt de beller op Plan, dan maakt je backend een planningslink met POST /api/v1/planning-links (recht planning_links:write). Het antwoord is een 201 met id, url, expiresAt, customerId en — als je een teamlid noemde — userId.
Je backend stuurt de browser van de beller naar url, bijvoorbeeld met een HTTP 303. Is de beller niet ingelogd in Schedulinq, dan logt die eerst in en komt daarna terug op de link.
De planner opent op de klant, de dienst, het teamlid (of iedereen die de dienst doet) en het adres uit je verzoek.
De beller kiest een moment en slaat de afspraak op. Die krijgt je kenmerken mee.
Terug naar CRM brengt de beller terug naar het adres dat je opgaf.

Voorbeeldverzoek · POST /api/v1/planning-links

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/planning-links \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "appointmentTypeId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
  "customer": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e06"
  },
  "metadata": {
    "campaignId": "C-42",
    "dealId": "D-123"
  },
  "returnUrl": "https://crm.example.com/deals/D-123"
}'

Antwoord · 201

{
  "customerId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e06",
  "expiresAt": "2026-10-14T09:15:00+02:00",
  "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e07",
  "url": "https://app.schedulinq.com/plan-link#EXAMPLE-TOKEN",
  "userId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e03"
}

Maak hem bij de klik, nooit vooraf

De url is een geheim dat de planner één keer opent, binnen 15 minuten. Maak de link dus op het moment van de klik, en stuur de browser er meteen naartoe.

Zet hem nooit in een e-mail, een sms of een pagina die vooraf wordt opgebouwd, en log hem nooit.
Het token staat achter de # van de URL, zodat het nooit in een serverlog of een Referer-header terechtkomt.
Later de planner weer nodig? Maak een nieuwe link. Elk verzoek met een nieuwe Idempotency-Key maakt een nieuwe link; zie Idempotentie.

Per organisatie kunnen er hoogstens 120 planningslinks per minuut worden gemaakt, hoeveel sleutels je ook hebt. Zie Limieten.

Het verzoek

Request body · POST /api/v1/planning-links

{
  "appointmentTypeId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
  "customer": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e06"
  },
  "metadata": {
    "campaignId": "C-42",
    "dealId": "D-123"
  },
  "returnUrl": "https://crm.example.com/deals/D-123"
}

user is optioneel: het teamlid waarop de planner opent, {"id": …} of {"email": …}, precies één van de twee. Het teamlid moet actief en inplanbaar zijn. Zonder user opent de planner op elk teamlid dat de dienst doet, en heeft het antwoord geen userId. Hoe dan ook kan de beller in de planner nog een ander teamlid kiezen.
appointmentTypeId is de dienst waarop de planner opent (GET /api/v1/services). Die is optioneel; het teamlid moet de dienst wel doen, als je er een noemt.
customer kan op twee manieren. Op id — {"id": …} en verder geen veld — is het een van je klanten: een klant die is samengevoegd met een andere, wordt naar die andere gevolgd, en een id dat onbekend, gearchiveerd of van een andere organisatie is, geeft een 404 errors.api.customerNotFound. Een id samen met een ander klantveld geeft een 400 errors.validation.customerIdOrDetails. Op gegevens is email verplicht en wordt de klant op dat adres gezocht, ongeacht hoofdletters, onder je bestaande klanten; een klant die is samengevoegd met een andere, wordt naar die andere gevolgd. Zijn er meerdere, dan wint een klant die niet op non-actief staat, en daarna de klant die het laatst is gewijzigd. Bij een bestaande klant worden alleen lege namen, een lege bedrijfsnaam en een leeg telefoonnummer ingevuld; er wordt niets overschreven. Een nieuwe klant krijgt het e-mailadres in kleine letters. Een PERSON (de standaard) heeft lastName nodig, een BUSINESS companyName. phone is E.164 (een + en de landcode) of een nationaal nummer in het land van je organisatie.
address is waar deze afspraak plaatsvindt, als die bij de klant is. Het vervangt nooit het factuuradres van de klant en wordt niet bij de klant opgeslagen. line1 bevat de straat en het huisnummer.
metadata zijn je kenmerken, zoals een deal-id. Ze gaan mee naar elke afspraak die vanuit de link wordt geboekt. Zie Kenmerken.
returnUrl is waar Terug naar CRM naartoe gaat; zie hieronder.

Een klant die je al kent, op id, en geen teamlid:

Request body · POST /api/v1/planning-links

{
  "appointmentTypeId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e01",
  "customer": {
    "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e06"
  },
  "metadata": {
    "campaignId": "C-42",
    "dealId": "D-123"
  },
  "returnUrl": "https://crm.example.com/deals/D-123"
}

Wie hem kan openen

De link werkt voor een teamlid van je organisatie dat afspraken voor iedereen mag maken en alle klanten mag zien. Wie hem als eerste opent, is de eigenaar: opent dezelfde persoon hem binnen de 15 minuten opnieuw — na herladen, of een verbroken verbinding — dan krijgt die dezelfde planner. Ieder ander ziet dat de link al is gebruikt. Iemand van een andere organisatie ziet dat de link niet bestaat.

Je CRM hoeft het Schedulinq-account van de beller niet te kennen: wie de link opent, logt in Schedulinq in als zichzelf.

Wat de beller ziet als het misgaat

Schedulinq toont één melding per reden: de link is verlopen (na 15 minuten), is al gebruikt, bestaat niet (een andere organisatie, of een URL die niet volledig is overgekomen), of de beller heeft niet de rechten om vanuit het CRM te plannen. Het antwoord is steeds hetzelfde: klik in het CRM opnieuw op Plan, zodat je backend een nieuwe link maakt. Zie Afspraakmogelijkheden zoeken.

Terug naar je CRM

returnUrl moet een https-URL zijn waarvan de origin op de lijst met toegestane terugkeeradressen van je organisatie staat. Een beheerder houdt die lijst bij onder Integraties → API, in de kaart Toegestane terugkeeradressen onder de sleutels. Elke andere URL wordt geweigerd bij het maken van de link, met een 400 errors.validation.returnUrlOriginNotAllowed. Zolang de lijst leeg is, wordt elke planningslink met een returnUrl geweigerd.

Terug naar CRM staat in de balk boven de planner en, na het opslaan, bovenaan de pagina van de afspraak — ook na herladen. Het is zichtbaar voor wie mag plannen, en alleen zolang de origin op de lijst staat: haal je de origin weg, dan verdwijnt de knop.

De kaart Toegestane terugkeeradressen op de API-pagina met twee adressen, elk met Verwijderen, en een vak om er een toe te voegen.

Meerdere afspraken vanuit één link

Dat mag. Elke afspraak die vanuit de link wordt gemaakt — één, of meerdere achter elkaar — krijgt de kenmerken van de link mee, en het id van de link als planningLinkId. Ze kunnen worden opgeslagen tot 24 uur nadat de link is geopend, en alleen voor de klant van de link.

Foutmeldingen

De meldingen die een CRM het vaakst tegenkomt:

404 errors.api.colleagueNotFound: geen teamlid van je organisatie heeft dit id of adres.
404 errors.api.serviceNotFound: de dienst bestaat niet of is gearchiveerd.
404 errors.api.customerNotFound: geen klant van je organisatie heeft dit id.
409 errors.api.colleagueNotActive: het teamlid is op non-actief gezet, gearchiveerd, niet inplanbaar, of heeft de uitnodiging nog niet geaccepteerd.
422 errors.validation.userCannotDoEveryService: het teamlid doet deze dienst niet.

Alle codes staan bij de operatie in de referentie.

Veelgestelde vragen

Kan een klant de link gebruiken?

Nee. De link opent de planner van Schedulinq, en daarvoor moet een teamlid van je organisatie ingelogd zijn dat mag plannen. Wil je de klant zelf een moment laten kiezen, stuur dan een uitnodiging.

De beller heeft het tabblad gesloten. Wat nu?

Klik opnieuw op Plan: je backend maakt een nieuwe link. Dezelfde link opnieuw openen werkt alleen voor dezelfde persoon, binnen de 15 minuten.

Ligt het teamlid vast in de planner?

Nee. De planner opent op het teamlid dat je noemde, maar de beller kan iemand anders kiezen. Uitlezen en webhooks laten dan zien wie er echt is geboekt. Laat je user weg, dan opent de planner op iedereen die de dienst doet.