Teamleden

Een koper of monteur die werk krijgt uit je CRM, is in Schedulinq een teamlid, met eigen werktijden, werkgebieden en agenda. Deze handleiding gaat over het lezen van je teamleden en het uitnodigen van nieuwe — de knop Koper aanmaken. Wat een teamlid in Schedulinq ziet en doet, staat in Je team uitnodigen en Teamleden beheren.

Woorden

In de API is een teamlid een user: de endpoints zijn /api/v1/users. Webhooks noemen ze colleague, zoals in colleague.activated.

Lezen

GET /api/v1/users (recht users:read) geeft je teamleden en de openstaande uitnodigingen voor nieuwe. Elk item heeft een status:

• ACTIVE — een teamlid;
• INACTIVE — een teamlid dat is gedeactiveerd;
• INVITED — een uitnodiging die nog niet is geaccepteerd, met haar invitationId en invitationExpiresAt.

Een teamlid draagt ook schedulable (of klanten bij hem of haar geboekt kunnen worden), calendarConnected (of Schedulinq een agenda van het teamlid leest) en de eigen velden.

GET /api/v1/roles (recht users:write) geeft de rollen die deze sleutel een nieuw teamlid mag geven. Gebruik een van hun id's als roleId.

curl "https://api.schedulinq.com/api/v1/users?limit=25" \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY"

Aanmaken

POST /api/v1/users (recht users:write) nodigt iemand uit op e-mailadres. Schedulinq verstuurt de uitnodigingsmail.

{
  "customFields": {
    "bedrijf": "Loodgieter Bakker"
  },
  "email": "piet+ov@loodgieter-bakker.example",
  "firstName": "Piet",
  "lastName": "Bakker",
  "locale": "nl",
  "metadata": {
    "campaignId": "C-42"
  },
  "roleId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e04"
}

email, firstName, lastName en roleId zijn verplicht. Er is geen veld om iemand beheerder te maken. Er zijn drie antwoorden:

201: uitgenodigd. Er is een nieuwe uitnodiging gemaakt en de mail is onderweg. Dit is ook het antwoord als een verlopen uitnodiging voor hetzelfde adres is vervangen; de invitationId is dan nieuw. De body is het volledige item.

{
  "admin": false,
  "createdAt": "2026-10-01T09:12:00Z",
  "customFields": {
    "bedrijf": "Loodgieter Bakker"
  },
  "email": "piet+ov@loodgieter-bakker.example",
  "firstName": "Piet",
  "invitationExpiresAt": "2026-10-08T09:12:00Z",
  "invitationId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e05",
  "lastName": "Bakker",
  "metadata": {
    "campaignId": "C-42"
  },
  "name": "Piet Bakker",
  "roleId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e04",
  "status": "INVITED"
}

200 met ACTIVE of INACTIVE: al een teamlid. Er verandert niets en er gaat geen mail uit. Een teamlid met INACTIVE is gedeactiveerd: planningslinks en uitnodigingen weigeren het tot een beheerder het weer activeert.

{
  "email": "sanne@installatiebedrijf-jansen.example",
  "id": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e03",
  "status": "ACTIVE"
}

200 met INVITED: al uitgenodigd. De openstaande uitnodiging blijft zoals ze is, en er gaat geen tweede mail uit.

{
  "email": "piet+ov@loodgieter-bakker.example",
  "invitationExpiresAt": "2026-10-08T09:12:00Z",
  "invitationId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e05",
  "status": "INVITED"
}

Een 200 is een ontvangstbewijs — de status, het id, de email en bij een uitnodiging invitationExpiresAt — tenzij de sleutel ook users:read heeft; dan is het het volledige item.

De weigeringen die je het vaakst tegenkomt:

• 409 errors.api.colleagueArchived: een gearchiveerd teamlid heeft dit adres. Zet het terug in Schedulinq, of nodig uit met een ander adres.
• 409 errors.api.emailInUseElsewhere: het adres hoort bij een account buiten je organisatie, die nooit wordt genoemd. Een adres wordt alleen ontdaan van spaties en in kleine letters gezet, dus een plus-adres zoals piet+ov@… is een ander adres dan piet@…. Gebruik je plus-adressen, controleer dan of je mailprovider ze bezorgt.
• 400 errors.validation.roleRequired: roleId ontbreekt.
• 403 errors.api.roleNotAssignable: de rol hoort niet bij de rollen van de sleutel, is sindsdien verwijderd, of is van een andere organisatie. Deze foutmelding heeft geen errors[].
• 409 errors.api.organisationScheduledForDeletion: de organisatie neemt geen wijzigingen meer aan.
• 429 errors.api.colleagueInvitationLimit, met Retry-After: standaard hoogstens 200 aanmaakaanroepen per uur per organisatie — elke aanroep telt, herhalingen meegeteld — en 3 keer opnieuw versturen per uur per uitnodiging. Zie Limieten.

Plaatsen en abonnement

• Tijdens de proefperiode is er geen grens aan het aantal teamleden.
• Na de proefperiode neemt een openstaande uitnodiging een plaats in. Een 409 errors.api.noSeatsAvailable betekent dat de betaalde plaatsen vol zijn, openstaande uitnodigingen meegeteld. De API koopt nooit een plaats; een beheerder voegt er een toe in Schedulinq. Zie Abonnement en gebruikers.
• Een 402 errors.api.trialUserLimit betekent dat de organisatie geen toegang heeft: de proefperiode is afgelopen zonder abonnement, of het abonnement is vervallen. Dan antwoordt elke aanmaak met 402, ook voor iemand die al teamlid is.
• Is een van beide opgelost, stuur dan een nieuwe Idempotency-Key. Dezelfde sleutel herhaalt de weigering 24 uur lang. Zie Idempotentie.

De uitnodigingsmail

De mail gaat uit in de taal die je als locale meegeeft, anders in de taal van je organisatie, en noemt je organisatie. De link erin is zeven dagen geldig.

Opnieuw versturen

POST /api/v1/users/invitations/{id}/resend (recht users:write) verstuurt de uitnodiging opnieuw, met de invitationId uit de lijst of uit het antwoord op de aanmaak.

• Er gaat een nieuwe link uit, zeven dagen extra geldig; de vorige link werkt niet meer.
• Een verlopen uitnodiging wordt vernieuwd — en heeft dan een plaats nodig — tot de nachtelijke opruiming haar verwijdert. Daarna antwoordt het opnieuw versturen met 404: maak het teamlid dan opnieuw aan.
• Is de uitnodiging geaccepteerd, dan antwoordt het met 409 errors.api.colleagueInvitationAccepted.
• Een sleutel mag alleen een uitnodiging opnieuw versturen die hij zelf had kunnen maken: nooit een uitnodiging voor een beheerder, en alleen een met een rol uit de rollen van de sleutel.
• Idempotency-Key is verplicht, omdat een herhaalde verzending twee keer zou mailen.

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/users/invitations/3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e05/resend \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

Eigen velden

customFields neemt de waarden van de eigen velden voor teamleden van je organisatie, op sleutel. Ze worden naar het teamlid gekopieerd zodra het accepteert. Typen worden gecontroleerd; "verplicht" wordt hier niet afgedwongen. Een sleutel die geen eigen veld van je organisatie is, wordt geweigerd met errors.api.custom_field_unknown_key. Zie Eigen velden toevoegen.

Na het accepteren

• Staat Agenda koppelen bij activeren aan in je organisatie (Team → Leden → Acties), dan koppelt het nieuwe teamlid eerst zijn Google- of Microsoft-agenda.
• De webhook colleague.activated meldt dat de uitnodiging is geaccepteerd, met haar invitationId en haar kenmerken — je campagne-id bijvoorbeeld. Zie Webhook-gebeurtenissen.
• calendarConnected en de webhooks colleague.calendar_connected en colleague.calendar_disconnected melden de agenda.
• Diensten, werkgebieden en werktijden stelt een beheerder in Schedulinq in. schedulable zegt wanneer klanten bij het teamlid geboekt kunnen worden.

Een rol voor kopers

Een koper hoeft meestal alleen zijn eigen afspraken te zien en geen klanten: een rol met afspraken op Eigen en zonder toegang tot klanten. Maak die één keer aan onder Rollen en rechten, en geef de sleutel van je CRM alleen die rol.

Veelgestelde vragen

Kan ik een teamlid via de API beheerder maken?

Nee. Beheerder is nooit een rol die een sleutel kan toewijzen; een beheerder maakt iemand beheerder in Schedulinq.

Een koper heeft een nieuw e-mailadres. Wat nu?

Pas het aan in Schedulinq. Een aanmaak met het nieuwe adres zou een tweede teamlid uitnodigen.

Hoe maak ik een uitnodiging ongedaan die mijn CRM per ongeluk stuurde?

Annuleer haar op de Team-pagina in Schedulinq: daar staat "Via API" met de naam van de sleutel. De API annuleert geen uitnodigingen.