---
title: "Create a new worker"
method: POST
path: "/public/onboarding/v1/create-worker"
tags: ["Onboarding flow"]
---

# Create a new worker

`POST /public/onboarding/v1/create-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/create-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/create-worker/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- WorkerCreationRequestV1
  - `firstName` string, required
  - `emailAddress` string, email, required
  - `mobilePhoneNumber` 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.
  - `verificationDocumentDetails` VerificationDocumentDetailsV1, required: ID verification details.
    - `firstNameFormal` string, required: The formal first name of the worker.
    - `middleName` string: The middle name of the worker.
    - `lastName` string, required: The last name of the worker.
    - `initials` string, required: The initials of the worker.
    - `dateOfBirth` string, date, required: The date of birth of the worker.
    - `placeOfBirth` string, required: The place of birth of the worker.
    - `gender` 'Male' | 'Female', required: The gender of the worker.
    - `nationality` string, required: The country code in ISO 3166-1 alpha-2 format.
    - `nonEerWorkCategory` NonEerWorkCategory: This object contains the legal work category of the worker for non-EER residents. This is only required for non-EER residents.
      - `legalWorkCategory` 'NON_EER_RESIDENCE_PERMIT', required: The legal work categories that are currently supported.
      - `rightToWorkUntil` string, date, required: The date when the workers right to work expires. This is not inclusive.
    - `identityDocument` IdentityDocumentV1, required
      - `bsnDocument` string: The base64-encoded image of the bsn document.
      - `base64DocumentBack` string, required: The base64-encoded image of the back of the identity document.
      - `base64DocumentFront` string, required: The base64-encoded image of the front of the identity document.
      - `documentType` 'IDENTITY_CARD' | 'PASSPORT' | 'RESIDENCE_PERMIT', required
      - `documentNumber` string, required: The identification document number.
      - `documentExpiryDate` string, date, required: The expiration date of the identification document.
      - `documentNationality` string, required: The country code in ISO 3166-1 alpha-2 format.
    - `identificationBy` string, required: The method used for worker identification.
    - `idCheckDate` string, date, required: The date when the identification document was checked.
    - `BSN` string, required: The BSN (citizen service number).
  - `paymentDetails` PaymentDetailsV1, required: Payment details.
    - `IBAN` string, required: The IBAN of the worker.
  - `address` AddressDetailsV1, required: Address details.
    - `street` string, required: The street name of the address.
    - `houseNumber` integer, required: The house number of the address, excluding suffix. For a house number 123A, this would be 123.
    - `houseNumberAddition` string: House number suffix (if any). For a house number 123A, this would be 'A'.
    - `zipCode` string, required: The postal code of the address. Must be a post code that actually exists in the Netherlands.
    - `city` string, required: The city of the address.
    - `countryCode` string, required: The country code in ISO 3166-1 alpha-2 format.

## Response `200`

Successfully created a worker

- WorkerCreationResponseV1
  - `workerId` string, uuid

## Other responses

- `400`: The request could not be processed. This could be due to a number of reasons: * The request does not have all required data. * Data in the request is invalid. * Data in the request is inconsistent. * The operation is not allowed given the current state of the data.
- `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.

## Changes

- **2026-09-29** `f9510f3f4b22`: 9 breaking, 1 info
  - added the new required request property `address`
  - added the new required request property `emailAddress`
  - added the new required request property `firstName`
  - added the new required request property `mobilePhoneNumber`
  - …6 more
- **2026-09-29** `3352b56bb8fe`: 3 breaking, 7 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 request property `address`
  - …20 more
- **2026-09-16** `ccf9834e5006`: 9 breaking, 1 info
  - added the new required request property `address`
  - added the new required request property `emailAddress`
  - added the new required request property `firstName`
  - added the new required request property `mobilePhoneNumber`
  - …6 more
- **2026-09-15** `8085d4c1ab80`: 3 breaking, 7 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 request property `address`
  - …20 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/maqqie/apis/maqqie-public-api/changes/public/onboarding/v1/create-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)