---
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`

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.

---

[API](https://skmtc.net/maqqie/apis/maqqie-public-api.md) · [All operations](https://skmtc.net/maqqie/apis/maqqie-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maqqie/maqqie-public-api/revisions/41e5cd97d4d7/schema)