---
title: "Invite a worker to join Maqqie"
method: POST
path: "/public/onboarding/v1/invite-worker"
tags: ["Onboarding flow"]
---

# Invite a worker to join Maqqie

`POST /public/onboarding/v1/invite-worker`

## Request

- Base URL: `https://api.maqqie.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.maqqie.app/public/onboarding/v1/invite-worker`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://maqqie.app/auth/realms/maqqie/protocol/openid-connect/token`
- TypeScript: <https://skmtc.dev/maqqie/apis/maqqie-public-api/docs/public/onboarding/v1/invite-worker/post.ts> (a function with typed inputs; its response is checked against the schema)

Invite a worker to join Maqqie. If freelance properties are provided, the API will also create a freelance company for the worker.
This is intended for company users to onboard workers.

## Request body

- InviteWorkerRequestV1
  - `emailAddress` string, email, required: The email address of the worker.
  - `firstName` string, required: The first name of the worker.
  - `gender` 'MALE' | 'FEMALE': The gender of the worker.
  - `initials` string: The initials of the worker.
  - `lastName` string: The last name of the worker.
  - `shouldNotifyWorkerOfAccountCreation` boolean: Whether to send an invitation email and SMS to the worker.
  - `mobileNumber` string, required: The mobile number of the worker. * Must include a country code (e.g. +31 or 0031). * Must be a number that can exist in practice. Examples of numbers that **cannot** exist include phone numbers that are too long for their country or Dutch cell phone numbers starting with +3169. * The phone number type must be supported. This excludes phone numbers that are not suitable for the application's use cases, such as voicemail access numbers. * The phone number must be parsable. This means the format of the phone number is valid and can be be interpreted as a valid phone number.
  - `city` string: The city where the worker resides.
  - `dateOfBirth` string, date: The date of birth of the worker.
  - `houseNumber` string: The house number of the worker.
  - `houseNumberAddition` string: The house number addition of the worker.
  - `iban` string: The IBAN for worker payments.
  - `nationality` 'DUTCH' | 'OTHER': The nationality of the worker.
  - `middleName` string: The middle name of the worker.
  - `paymentPeriod` 'FOUR_WEEKLY' | 'WEEKLY': The payment period for the worker.
  - `street` string: The street where the worker resides.
  - `wageTaxRebate` boolean: Whether the worker wants to apply wage tax rebate.
  - `zip` string, required: The zip code of the worker.
  - `freelanceChamberOfCommerceNumber` string: Chamber of Commerce number for freelance workers.
  - `freelanceVatNumber` string: VAT number for freelance workers.
  - `freelanceVatType` 'HIGH' | 'LOW' | 'SHIFTED' | 'NONE' | 'KOR': VAT type for freelance workers.

## Response `200`

Successfully invited a worker

- InviteWorkerResponseV1
  - `message` string, required: Success message.
  - `workerId` string, uuid, required: The external ID of the created worker.

## Other responses

- `400`: The request could not be processed. Possible error codes: * `INVALID_EMAIL` - The email address format is invalid. * `INVALID_PHONE_NUMBER` - The mobile number format is invalid or not supported. * `INVALID_ZIP_CODE` - The zip code format is invalid. * `INVALID_IBAN` - The IBAN format is invalid. * `EMAIL_ADDRESS_IN_USE` - A worker with this email address already exists for this company.
- `401`: The request did not contain credentials identifying the caller, or the provided credentials were invalid.
- `403`: The data that the request referred to is inaccessible to the caller. This typically means the authenticated user is not a company user.

## Changes

- **2026-09-29** `f9510f3f4b22`: 7 breaking, 19 info
  - added the new required request property `emailAddress`
  - added the new required request property `firstName`
  - added the new required request property `mobileNumber`
  - added the new required request property `zip`
  - …22 more
- **2026-09-29** `3352b56bb8fe`: 5 breaking, 21 warning, 14 info
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `200`
  - the response's body type changed from `string` to no type for status `400`
  - removed the required property `message` from the response with the `200` status
  - …36 more
- **2026-09-16** `ccf9834e5006`: 7 breaking, 19 info
  - added the new required request property `emailAddress`
  - added the new required request property `firstName`
  - added the new required request property `mobileNumber`
  - added the new required request property `zip`
  - …22 more
- **2026-09-15** `8085d4c1ab80`: 5 breaking, 21 warning, 14 info
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `200`
  - the response's body type changed from `string` to no type for status `400`
  - removed the required property `message` from the response with the `200` status
  - …36 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/maqqie/apis/maqqie-public-api/changes/public/onboarding/v1/invite-worker/post.md)

---

[API](https://skmtc.dev/maqqie/apis/maqqie-public-api.md) - [All operations](https://skmtc.dev/maqqie/apis/maqqie-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/maqqie/apis/maqqie-public-api/revisions/13ed331da2b2?raw)