Colleagues

A buyer or installer who receives work from your CRM is a team member in Schedulinq, with their own working hours, service areas and calendar. This guide covers reading your team members and inviting new ones — the Create buyer button. What a team member sees and does in Schedulinq is in Invite your team and Team members.

Words

In the API a team member is a user: the endpoints are /api/v1/users. Webhooks call them colleague, as in colleague.activated.

Reading

GET /api/v1/users (scope users:read) lists your team members and the open invitations for new ones. Each item has a status:

• ACTIVE — a team member;
• INACTIVE — a team member who was deactivated;
• INVITED — an invitation that has not been accepted yet, with its invitationId and invitationExpiresAt.

A team member also carries schedulable (whether customers can be booked with them), calendarConnected (whether Schedulinq reads a calendar of theirs) and their custom fields.

GET /api/v1/roles (scope users:write) lists the roles this key may give a new team member. Use one of their ids as roleId.

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

Creating

POST /api/v1/users (scope users:write) invites someone by e-mail address. Schedulinq sends the invitation mail.

{
  "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 and roleId are required. There is no field to make someone an admin. There are three answers:

201: invited. A new invitation was made and the mail is on its way. This is also the answer when an expired invitation for the same address was replaced; the invitationId is then new. The body is the full 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 with ACTIVE or INACTIVE: already a team member. Nothing changes and no mail goes out. An INACTIVE team member is deactivated: planning links and invitations refuse them until an admin activates them again.

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

200 with INVITED: already invited. The open invitation stays as it is, and no second mail goes out.

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

A 200 is a receipt — the status, the id, the email and an invitation's invitationExpiresAt — unless the key also holds users:read; then it is the full item.

The refusals you are most likely to meet:

• 409 errors.api.colleagueArchived: an archived team member has this address. Restore them in Schedulinq, or invite with another address.
• 409 errors.api.emailInUseElsewhere: the address belongs to an account outside your organisation, which is never named. An address is only trimmed and lowercased, so a plus-address such as piet+ov@… is a different address from piet@…. If you use plus-addresses, check that your mail provider delivers them.
• 400 errors.validation.roleRequired: roleId is missing.
• 403 errors.api.roleNotAssignable: the role is not among the key's roles, was deleted since, or belongs to another organisation. This problem has no errors[].
• 409 errors.api.organisationScheduledForDeletion: the organisation accepts no changes.
• 429 errors.api.colleagueInvitationLimit, with Retry-After: at most 200 create calls an hour per organisation by default — every create counts, repeats included — and 3 resends an hour per invitation. See Rate limits.

Seats and subscription

• During the trial there is no limit on team members.
• After the trial, a pending invitation takes a seat. A 409 errors.api.noSeatsAvailable means the paid seats are full, pending invitations included. The API never buys a seat; an admin adds one in Schedulinq. See Subscription and seats.
• A 402 errors.api.trialUserLimit means the organisation has no access: the trial ended without a subscription, or the subscription lapsed. Then every create answers 402, also for someone who is already a team member.
• After either is fixed, send a new Idempotency-Key. The same key replays the refusal for 24 hours. See Idempotency.

The invitation mail

The mail goes out in the language you give as locale, else in your organisation's language, and names your organisation. The link in it is valid for seven days.

Resending

POST /api/v1/users/invitations/{id}/resend (scope users:write) sends the invitation again, with the invitationId from the list or the create answer.

• It sends a new link, valid for seven more days; the previous link stops working.
• An expired invitation is renewed — and then needs a seat — until the nightly clean-up deletes it. After that the resend answers 404: create the team member again.
• Once the invitation is accepted, the resend answers 409 errors.api.colleagueInvitationAccepted.
• A key may resend only an invitation it could have made: never an admin invitation, and only one whose role is among the key's roles.
• Idempotency-Key is required, because a replayed resend would mail twice.

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"

Custom fields

customFields takes the values of your organisation's custom fields for team members, by key. They are copied to the team member when they accept. Types are checked; "required" is not enforced here. A key that is no custom field of your organisation is refused with errors.api.custom_field_unknown_key. See Custom fields.

After accepting

• If your organisation has Connect calendar on activation switched on (Team → Members → Actions), the new team member connects their Google or Microsoft calendar first.
• The webhook colleague.activated tells you the invitation was accepted, with its invitationId and its metadata — your campaign id, for example. See Webhook events.
• calendarConnected and the webhooks colleague.calendar_connected and colleague.calendar_disconnected tell you about the calendar.
• Services, service areas and working hours are set by an admin in Schedulinq. schedulable tells you when customers can be booked with the team member.

A role for buyers

A buyer typically needs to see only their own appointments and no customers: a role with appointments at Own and no customer access. Create it once under Roles and permissions, and give your CRM's key only that role.

Frequently asked questions

Can I make a team member an admin through the API?

No. Admin is never a role a key can assign; an admin makes someone an admin in Schedulinq.

A buyer changed e-mail address. What now?

Change it in Schedulinq. A create with the new address would invite a second team member.

How do I undo an invitation my CRM sent by mistake?

Cancel it on the Team page in Schedulinq: it says "Via API" with the key's name. The API does not cancel invitations.