Onboarding flow

Invite a worker to join Maqqie

Changed on Sep 29, 2026

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.

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)
Auth
OAuth 2
Client credentials
Token URLhttps://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.

Request body

emailAddressstring email required

The email address of the worker.

firstNamestring required

The first name of the worker.

gender'MALE' | 'FEMALE'

The gender of the worker.

initialsstring

The initials of the worker.

lastNamestring

The last name of the worker.

shouldNotifyWorkerOfAccountCreationboolean

Whether to send an invitation email and SMS to the worker.

mobileNumberstring 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.

citystring

The city where the worker resides.

dateOfBirthstring date

The date of birth of the worker.

houseNumberstring

The house number of the worker.

houseNumberAdditionstring

The house number addition of the worker.

ibanstring

The IBAN for worker payments.

nationality'DUTCH' | 'OTHER'

The nationality of the worker.

middleNamestring

The middle name of the worker.

paymentPeriod'FOUR_WEEKLY' | 'WEEKLY'

The payment period for the worker.

streetstring

The street where the worker resides.

wageTaxRebateboolean

Whether the worker wants to apply wage tax rebate.

zipstring required

The zip code of the worker.

freelanceChamberOfCommerceNumberstring

Chamber of Commerce number for freelance workers.

freelanceVatNumberstring

VAT number for freelance workers.

freelanceVatType'HIGH' | 'LOW' | 'SHIFTED' | 'NONE' | 'KOR'

VAT type for freelance workers.

Example request

{
  "emailAddress": "example@domain.com",
  "firstName": "John",
  "gender": "MALE",
  "initials": "J.D.",
  "lastName": "Doe",
  "shouldNotifyWorkerOfAccountCreation": true,
  "mobileNumber": "+31612345678",
  "city": "Amsterdam",
  "dateOfBirth": "1990-01-01",
  "houseNumber": "123",
  "houseNumberAddition": "A",
  "iban": "NL91ABNA0417164300",
  "nationality": "DUTCH",
  "middleName": "van",
  "paymentPeriod": "WEEKLY",
  "street": "Main Street",
  "wageTaxRebate": true,
  "zip": "1234AB",
  "freelanceChamberOfCommerceNumber": "62114395",
  "freelanceVatNumber": "NL001197903B02",
  "freelanceVatType": "HIGH"
}

Response

Successfully invited a worker

messagestring required

Success message.

workerIdstring uuid required

The external ID of the created worker.

Example response

{
  "message": "Worker invited successfully",
  "workerId": "0193df2c-d020-7860-b171-d9d915252704"
}

Changes

Sep 29, 2026f9510f3f4b22 Revision changes
- breaking
  added the new required request property
- breaking
  added the new required request property
- breaking
  added the new required request property
- breaking
  added the new required request property
- breaking
  the request's body type changed from no type to object
- breaking
  the response's body type changed from no type to object for status
- breaking
  the response's body type changed from no type to string for status
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
Sep 29, 20263352b56bb8fe Revision changes
- breaking
  the request's body type changed from object to no type
- breaking
  the response's body type changed from object to no type for status
- breaking
  the response's body type changed from string to no type for status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- info
  response schema application/json enum value removed COUNTRY_ADDRESS_NOT_SUPPORTED
- info
  response schema application/json enum value removed EMAIL_ADDRESS_IN_USE
- info
  response schema application/json enum value removed INVALID_BSN
- info
  response schema application/json enum value removed INVALID_COUNTRY
- info
  response schema application/json enum value removed INVALID_DOCUMENT
- info
  response schema application/json enum value removed INVALID_EMAIL
- info
  response schema application/json enum value removed INVALID_HOUSE_NUMBER_ADDITION
- info
  response schema application/json enum value removed INVALID_IBAN
- info
  response schema application/json enum value removed INVALID_NATIONALITY
- info
  response schema application/json enum value removed INVALID_NON_EER_WORKER_AND_NATIONALITY_COMBINATION
- info
  response schema application/json enum value removed INVALID_PHONE_NUMBER
- info
  response schema application/json enum value removed INVALID_ZIP_CODE
- info
  response schema application/json enum value removed LEGAL_WORK_CATEGORY_NOT_SUPPORTED
- info
  response schema application/json enum value removed WORKER_ALREADY_HAS_AN_ACCOUNT

Operation history (8 revisions)