--- title: "Create a new employee in Loket" method: POST path: "/v2/providers/employers/{employerId}/employee" tags: ["Employee"] --- # Create a new employee in Loket `POST /v2/providers/employers/{employerId}/employee` ## Request - Base URL: `https://api.loket.nl` - URL: `https://api.loket.nl/v2/providers/employers/{employerId}/employee` - Auth: none required __Activity name :__ PostEmployeeByEmployerId This endpoint 'creates' an employee in Loket with its corresponding entities. This means creating a number of records including Employee, Employment, WorkingHours, Wage etc. Before doing performing these steps, quite a number of validations are performed to ensure that the provided information can be used to create a functionally valid employee. ## Path parameters - `employerId` string, uuid, required ## Headers - `Authorization` string, required - `Accept` string, required ## Request body - Employee20241113 - `employeeData` Employee - `employeeNumber` integer, nullable: The employee number to uniquely identify an employee within an employer. - `personalDetails` object: The personal details of the employee. e.g. Name, civil status en gender - `firstName` string, nullable: The first name of the employee. - `lastName` string: The last name of the employee. - `prefix` string, nullable: The prefix to the last name of the employee. - `initials` string, nullable: The initials of the employee. - `formattedName` string, nullable: Formatted name of the employee based on the value of `howToFormatLastName` - `lastNamePartner` string, nullable: The last name of the employee`s partner. - `prefixPartner` string, nullable: The prefix to the last name of the employee"s partner. - `dateOfBirth` string, date, nullable: The date of birth of the employee. - `placeOfBirth` string, nullable: Place of birth of the employee - `howToFormatLastName` object, nullable: Indicates how the system will format `formattedName`. - `key` integer - `value` string - `title` object, nullable: The title to be used (if any). - `key` integer - `value` string - `gender` object, nullable: The gender of the employee - `key` integer - `value` string - `nationality` object, nullable: The nationality of the employee - `key` integer - `value` string - `civilStatus` object, nullable: The civil status of the employee - `key` integer - `value` string - `contactInformation` object, nullable: Contact information for the employee - `phoneNumber` string, nullable: The phone number of the employee. - `mobilePhoneNumber` string, nullable: The mobile phone number of the employee. - `faxNumber` string, nullable: The fax number to contact this individual - `emailAddress` string, nullable: The e-mail address of the employee. - `identityDocument` object, nullable: The identification document of the employee - `typeOfDocument` object, nullable - `key` integer: The key for the type of document. Possible values can be acquired via the metadata endpoint - `value` string: Description of the type of document - `documentIdentification` string, nullable: Description of the type of document - `address` object, nullable: The address of the employee - `street` string, nullable: Streetname of the address - `city` string, nullable: City of the address - `houseNumber` integer, nullable: House number of the address - `houseNumberAddition` string, nullable: An addition to further specify the house/door/postbox. For example used to specifty a room of floor number in addition to the house number. - `furtherIndication` object, nullable: Futher indication of the address for example onboard (a ship) or living in a trailer - `key` integer - `value` string - `postalCode` string, nullable: The postal code of the address - `location` string, nullable: The location like to further specify the address - `country` object, nullable: The country of residence of the employee - `key` integer - `value` string - `isoCode` string - `deviatingPostalAddress` object, nullable: The deviating address of the employee (used as a postal address) - `street` string, nullable: Streetname of the address - `city` string, nullable: City of the address - `houseNumber` integer, nullable: House number of the address - `houseNumberAddition` string, nullable: An addition to further specify the house/door/postbox. For example used to specifty a room of floor number in addition to the house number. - `furtherIndication` object, nullable: Futher indication of the address for example onboard (a ship) or living in a trailer - `key` integer - `value` string - `postalCode` string, nullable: The postal code of the address - `location` string, nullable: The location like to further specify the address - `country` object, nullable: The country of residence of the employee - `key` integer - `value` string - `isoCode` string - `iban` string, nullable: International Bank Account Number. Only IBAN without spaces are accepted. - `employmentData` Employment, nullable - `startDate` string, date, nullable: The date on which this employment starts. - `historicalStartDate` string, date, nullable: The historical date on which the employee was first employed. This field is used when an employee has multiple employments in time. In most cases this field should be used as the date on which the employee started working for the company. - `payrollAdministration` object, nullable: An administration used for payrolling. This field can not have a value at the same time as `nonPayrollAdministration` `payrollAdministration` is a metadata field within the employer context. Possible values can be managed by the user. - `id` string, uuid: The unique identifier of an object (GUID/UUID) - `name` string: Name of the administration - `clientNumber` integer: The client number is a unique number for administrations that are used for payrolling. This field has no value if the administration is not used for payrolling. - `description` string: Description of the administration - `nonPayrollAdministration` object, nullable: An administration that can not be used for payrolling. This field can not have a value at the same time as `payrollAdministration` `nonPayrollAdministration` is a metadata field within the employer context. Possible values can be managed by the user. - `id` string, uuid: The unique identifier of an object (GUID/UUID) - `name` string, nullable: Name of the administration - `description` string: Description of the administration - `commissionUntilDate` string, date, nullable: The date on which the employment will end. - `incomeRelationshipNumber` integer, nullable: The income relationship number that is required in the tax return. Together with the citizen service number (burgerservicenummer, BSN) and wage tax number, the income relationship number uniquely identifies an employment. - `employeeProfileId` object, nullable: References to an employeeprofile that is specified in the payroll administration level `employeeProfileId` is a metadata field within the payroll administration context. Possible values can be managed by the user. - `key` integer - `value` string - `employmentDurationType` object, nullable: A selection of pre defined durations for the employment. - `key` integer - `value` string - `startDateContractOfIndefiniteDuration` string, date, nullable: When did the value of `employmentDurationType` change for definite to indefinite. This value should be te samen as the `startDate` if the contract was indefinite from the start. - `employmentContractType` object, nullable: The type of employment applicable for the employment. - `key` integer - `value` string - `typeOfEmployee` object, nullable: A selection of pre defined employee-types for the employment. - `key` integer - `value` string - `cancellationPeriodEmployee` integer, nullable: The notice period an employee is required to give the employer when resigning. The unit of time that applies to this field is described in the noticePeriodTimeUnit property. - `cancellationPeriodEmployer` integer, nullable: The notice period an employer is required to give the employee when terminating the contract. The unit of time that applies to this field is described in the noticePeriodTimeUnit property. - `cancellationPeriodTimeUnit` object, nullable: The unit of time used for the noticePeriodeEmployee and noticePeriodEmployer properties. - `key` integer - `value` string - `cancellationNoticeDate` string, date, nullable: The date on which the notice was given by either the employee or the employer. - `startCancellationNoticePeriod` string, date, nullable: The date on which the term of notice period starts. If the agrement states that a notice periode always starts on the first day of the month and the notice was given on the 15th the start notice periode will be the first day of the next month. - `isDirectorAndMajorShareholder` boolean, nullable: Indicates whether the employment can be classiefied as a director and major shareholder (Dutch --> directeur-grootaandeelhouder or DGA). This field can be `null` in cases where it is unknown whether the employment can be classified as a director and major shareholder. - `isOnCallEmployment` boolean, nullable: Indicates whether the employment is an on-call employment. - `hasOnCallAppearanceObligation` boolean, nullable: In the case of an on-call employment this field indicates whether the employment has an appearance obligation. This field can be `null` in cases where it is unknown whether the employment has an appearance obligation. - `vacationCoupons` object, nullable: Indication for vacation coupons (vakantiebonnen). This is only applies to a limited set of CLA`s. - `key` integer - `value` string - `specialIncomeRatio` object, nullable: Indicates the special income ratio - `key` integer - `value` string - `isAnonymousEmployee` boolean, nullable: Indicates whether employee is anonymous - `isPreviousOwner` boolean, nullable: Indicates whether the employment can be classified as a previous owner. This field can be `null` in cases where it is unknown whether the employment can be classified as a director and major shareholder. - `isFamilyOfOwner` boolean, nullable: Indicates whether the employment can be classified as a previous owner. This field can be `null` in cases where it is unknown whether the employment can be classified as a director and major shareholder. - `isGemoedsbezwaardNationalInsurance` boolean, nullable: Gemoedsbezwaard Volksverzekering - `isGemoedsbezwaardEmployeeInsurance` boolean, nullable: Gemoedsbezwaard Werknemerverzekering - `namePayslip` string, nullable: Name that is visible on payslips for the employment - `calculateWorkingHours` boolean, nullable: Automatically calculate working hours for the employment if the option automatically calculate hours is selected for a given period. - `essMutationSet` object, nullable: References to a specified set of payrollcomponents that are to accessible via ESS for employee mutations `essMutationSet` is a metadata field within the werkgever/provider context. Possible values can be managed by the user. - `key` integer - `value` string - `exemptionInsuranceObligation` object, nullable: Indicates whether an exemption applies for the insurance obligation. If NULL than there is no exemption, thus insurance obligation applies in that case (verzekingsplicht) - `key` integer - `value` string - `firstDayNotification` boolean, nullable: Indicates whether first-day notification (EersteDagsMelding) is applicable for the employment - `sendMdvNotification` boolean, nullable: Indicate if a Mdv (melding dienstverband) should be send. - `periodPayGradeAdjustment` integer, nullable: The values is used for two processes. First off, a message can be configured to notify the user(s) of a upcoming wage raise/negotiation based on the value of this field. Second, the value, in combination with `signalSalaryScaleAdjustment`, is used to signal a wage raises based on the `payScale` and ‘payGrade’. - `signalPayGradeAdjustment` boolean, nullable: Indicates whether signaling regarding salary scale adjustments are enabled for the employment - `typeOfParticipation` object, nullable: The type of participation (aard van deelnemerschap) is only applicable in case the person related to this employment is eligible for pension - `key` integer - `value` string - `valueOfParticipation` object, nullable: The value of participation (waarde van deelnemerschap) is only applicable in case the person related to this employment is eligible for pension - `key` integer - `value` string - `professionCode` integer, nullable: A code field for a profession. - `deviatingCLATaxReturn` integer, nullable: CLA (CAO) code in case of a deviating CLA for tax returns . - `participation55plusRegulationUWV` boolean, nullable: Indicates whether the 55 plus regulation (55 plus regeling) is applicable for the employment - `emailLeaveRequest` string, nullable: Recipient e-mail adress for notification in case of leave requests. - `writtenEmploymentContract` boolean, nullable: Dit the employment and employer make a written contract? - `workingHoursData` WorkingHours, nullable - `shift` object, nullable: The shift determines the full-time hours and bonus percentage. `shift` is a metadata field within the payroll administration context. Possible values can be managed by the user. - `shiftNumber` integer: The number for the shift. - `fullTimeHoursPerWeek` number: The full time hours for an employment that is linked to this shift. - `bonusPercentage` number: The bonus percentage used in wage calculations for the hours made in this shift. - `deviatingHoursPerWeek` number, double, nullable: Fulltime hours are normally based as defined by the shift, this optional field is used to register a deviating value. The value can be less or more then the fulltime hours a week. - `deviatingSvDaysPerPeriod` number, nullable: Sv (social insurance) days are normally calculated by hours per shift, this optional field is used to register a deviating value. - `averageParttimeFactor` number, double, nullable: This field is used to register the deviating value of the parttimefactor. The parttimefactor is normally calculated by workinghours dividing by shifthours multplied by 100 - `regularWorkPattern` boolean, nullable: When the employee works the same amount of hours per day every week, then the workpattern is regular. - `flexibleHoursContract` object, nullable: The field indicates the type of flexible contract. If not applicable, please set to NULL. - `key` integer - `value` string - `contractCode` object, nullable: This field is specialy made for convenience stores. The field is the type of contract. `contractCode` is a metadata field within the employer context. Possible values can be managed by the user. - `key` string, uuid: The unique identifier of an object (GUID/UUID) - `code` integer - `description` string - `calculateUsingWorkPattern` object: Indications in this objects determine whether specific values should be calculated based on the bi-weekly workPattern (specified in the `workPattern` object). - `leaveHours` boolean, nullable: Indicates whether then leave balances (verlof) are to be calculated based on the workpattern. - `hoursBrokenPeriod` boolean, nullable: Indicates whether the hours for the payrolling should be calculated based on the workpattern in broken periods. These are periods of in or out of service. - `hoursPeriod` boolean, nullable: Indicates whether the hours for the payrolling should be calculated based on the workpattern for regular periods. - `daysDailyRate` boolean, nullable: Indicates whether the number of days of dailyrate should be calculated based on the workpattern. The number of days are normally calculated by the working hours. - `deviatingDaysAndHours` boolean, nullable: Indication whether the deviating hours per week and deviating SV-days per period are to be automatically calculated based on the workpattern. Please note (!) that any values in the deviatingHoursPerWeek and deviatingSvDaysPerPeriod fields (of this workingHours record) will be overwritten based on this calculation if true (and endDate=NULL)! - `workPattern` object, nullable: The applicable work pattern for a period of 2 weeks can be stored in this object. Each field contains the number of work hours for that day in the 2-week period.
Please note that the workPattern should be left NULL if no data is present (as opposed to filling all fields with 0)
Each field represent the number of hours the employee normally works on that day. - `oddWeeks` object - `monday` number, double - `tuesday` number, double - `wednesday` number, double - `thursday` number, double - `friday` number, double - `saturday` number, double - `sunday` number, double - `evenWeeks` object - `monday` number, double - `tuesday` number, double - `wednesday` number, double - `thursday` number, double - `friday` number, double - `saturday` number, double - `sunday` number, double - `wageData` Wage, nullable - `grossWage` number, double, nullable: The gross wage for the employee - `grossWageType` object, nullable: Indicates whether the `grossWage` is an hourly wage or a periodic wage. Periodic can represent a week, four weeks or a month. Which period is active for the employment can be found in wagePeriodType. - `key` integer - `value` string - `netWage` number, double, nullable: Net wage for the employment - `netWageType` object, nullable: Indicates whether the net wage is an hourly wage or a periodic wage. Periodic can represent a week, four weeks or a month. Which period is active for the employment can be found in the payroll administration resource. - `key` integer - `value` string - `payScale` object, nullable: A pay scale (also known as a salary structure) is a system that determines how much an employee is to be paid as a wage or salary, based on one or more factors such as the employee"s level, rank or status within the employer"s organization, the length of time that the employee has been employed, and the difficulty of the specific work performed. After selecting a pay scale a pay grade needs to be selected to determine the actual wage. Only works with `grossWage`. The value of `grossWage` will be updated server side after the submit. `payScale` is a metadata field within the payroll administration/payScale context. Possible values can be managed by the user. - `key` integer - `value` string - `payGrade` object, nullable: The pay grade indicates on what level (cel) of the paygrade the employment is. The level is multi dimensional where the description indicates both the level and for example the number of years of service within the given level. `payGrade` is a metadata field within the payroll administration/payScale context. Possible values can be managed by the user. - `key` integer - `value` string - `applyPayGrade` boolean, nullable: Apply pay grade indicates that after submitting the record the server will replace the value of `grossWage` with the value represented by the selected `payGrade`. A pay grade contains time based values, the value that is active on the `start date` of the record will be selected. - `organizationalEntityData` OrganizationalEntity, nullable - `function` object, nullable: The function of the employment. `function` is a metadata field within the employer context. Possible values can be managed by the user. - `key` string, uuid: The unique identifier of an object (GUID/UUID) - `description` string - `group` string - `deviatingFunctionGroup` string, nullable: The deviating functiongroup description of the employment. - `deviatingFunctionDescription` string, nullable: The deviating function description of the employment. This description deviates from the value of the `function` field. - `standardFunction` object, nullable: The standard (cao)function of the employment. `standardFunction` is a metadata field within the payroll administration context. Possible values can be managed by the user. - `key` integer - `value` string - `code` string, nullable - `category` integer, nullable - `department` object, nullable: The department of the employment. `department` is a metadata field within the employer context. Possible values can be managed by the user. - `key` string, uuid - `code` integer - `description` string - `distributionUnit` object, nullable: Distribution unit, used in several reports and the "basic wage journal" functionality. Commonly used as a cost center. `distributionUnit` is a metadata field within the employer context. Possible values can be managed by the user. - `key` string, uuid - `code` integer - `description` string - `placeOfEmployment` string, nullable: The place of employment (standplaats) for the employment. - `internalTelephoneExtensionNumber` string, nullable: The phone extention number for the employment. - `socialSecurityData` SocialSecurity, nullable - `isInsuredForSicknessBenefitsAct` boolean, nullable: Will contributions for the Sickness Benefits Act (ZW) be payed for this employment - `isInsuredForUnemploymentInsuranceAct` boolean, nullable: Will contributions for the Unemployment Insurance Act (WW) be payed for this employment - `isInsuredForOccupationalDisabilityInsuranceAct` boolean, nullable: Will contributions for the Occupational Disability Insurance Act (WAO) be payed for this employment - `healthCareInsuranceActType` object, nullable: Indicates what type of Health Care Insurance Act (Zvw) is applicable for this employment - `key` integer - `value` string - `fiscalData` Fiscal, nullable - `annualSalary` number, double, nullable: The fiscal annual salary - `deviatingPayrollTaxTableColour` object, nullable: Indicates if there is a deviating payroll tax table is applicable (green vs white table) - `key` integer - `value` string - `applyDayTables` boolean, nullable: Indicates whether the value of the day table is used for the calculation of payroll tax - `deviatingPayrollTaxPercentage` number, double, nullable: Indicates a deviating payroll tax percentage is to be applied - `applyDeviatingPayrollTaxPercentageOn` object: Indicates on what type of payroll calculation the deviating payroll tax percentage is applicable - `key` integer - `value` string - `applyPayrollTaxDeduction` boolean, nullable: Indicates whether payroll tax deduction is appliclable (loonheffingskorting) - `applyStudentDeduction` boolean, nullable: Apply the "Scholierenregeling" - `deviatingCalculationRulePayrollTax` object, nullable: Indicates if, while calculating payroll taxes and social security contributions, certain deviations are applicable. NL; Herleidingsregel - `key` integer - `value` string - `residentOf` object, nullable: Related to the fiscal country of residence of the employee. This might affect the calculation of any applicable loonheffingskortingen. - `key` integer - `value` string: Description of the type of document - `otherPayrollVariablesData` OtherPayrollVariables, nullable - `deviatingPremiumGroup` object, nullable: Indicates what deviating premie sector fonds should apply for the employment. Do not specify if there is no deviation from the premium group for the payroll administration the employment is linked to. - `key` integer - `value` string - `selfService` SelfService - `status` 'HasAccessToClient' | 'NoAccessToClient' | 'UserIsBlocked' | 'AccessToClientIsBlocked' | 'InvitePending' | 'InviteFailed' | 'InviteCancelled' | 'InviteExpired': Description of the status - `clientName` string: The name of the Client - `citizenServiceNumber` CitizenServiceNumber2 - `citizenServiceNumber` string, nullable: The social security number of the employee used in communication with the Dutch tax authorities. The number has to be a valid Dutch citizen service number (BSN). ## Response `201` OK - object - `employeeId` string, uuid: The unique identifier of an object (GUID/UUID) - `employmentId` string, uuid: The unique identifier of an object (GUID/UUID) ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `500`: Internal Server Error --- [API](https://skmtc.dev/loket/apis/loket-api.md) - [All operations](https://skmtc.dev/loket/apis/loket-api/llms.txt) - [OpenAPI document](https://skmtc.dev/loket/apis/loket-api/revisions/32170564148f?raw)