For different types of integrations there are certain things to take into consideration when starting to develop such an integration based on the Loket RESTful API. On this page we will mention a few of them to give external parties a bit more insight on what to expect when developing. The following categories of integrations are listed: - [1. General remarks regarding the Loket RESTful API](#1-general-remarks-regarding-the-loket-restful-api) - [2. Planning and time registration: send actual hours or other periodic payroll components to Loket](#2-planning-and-time-registration-send-actual-hours-or-other-periodic-payroll-components-to-loket) - [3. Information and dashboarding: acquire Employee- and Employment-related information from Loket](#3-information-and-dashboarding-acquire-employee--and-employment-related-information-from-loket) - [4. Financial information: acquire results from payroll and/or journal runs from Loket](#4-financial-information-acquire-results-from-payroll-andor-journal-runs-from-loket) - [5. Advanced interfaces: inserting and updating Employee and/or Employment information in Loket](#5-advanced-interfaces-inserting-and-updating-employee-andor-employment-information-in-loket) - [6. Single sign-on: set up an SSO link to Loket or Werknemerloket](#6-single-sign-on-set-up-an-sso-link-to-loket-or-werknemerloket)

# 1. General remarks regarding the Loket RESTful API __Goal:__ enable external software parties to build valuable integrations for (mutual) end-users __Prerequisites:__ an external party will need to apply for a client and user in order to start developing. This request can be put forward through the form on this page (Dutch): https://www.loket.nl/koppelingen/koppelen-met-loket/ . We will get back to you. __General remarks:__ * We highly recommend to truely consider your requirements and accessory test scenarios in an early stage of your development. If you are not yet familiar with Loket we would recommend to take your time to get acquainted with by clicking through the application and reading articles on the helpdesk portal: https://helpdesk.loket.nl/hc/nl (Dutch, authorized access) * Generally speaking, as an external party is building an application to our API we consider this party to be leading (!) in this process. Loket.nl will provide support to the party during the process, this support will be primarily technical. * Questions and/or remarks are welcomed and may be sent to api@loket.nl __Technical remarks:__ * The OAuth2 standard is used. External parties will need set up authorization for users based on the OAuth2 Authorization Code flow. Details can be found on this portal. * The Loket RESTful API is heavily based on global unique identifiers (GUIDs) for almost all resources, this is shown in the service contracts of the endpoints * All parties using the Loket RESTful API are expected to subscribe to the API changelog as that is the channel used for announcing any changes * Client credentials will be provided by Loket, as well as test user credentials. However production user credentials are NOT provided by Loket.nl itself. * Make use of the [GetAuthorizationsByEmployerId](/#tag/Authorizations) endpoint to check, per employer, if the user identified by the bearer token has the necessary authorizations to perform the required calls. If not please abort the process and notify the user of the missing authorizations.

# 2. Planning and time registration: send actual hours or other periodic payroll components to Loket __Goal:__ enable applications that are specialized in time registration and/or personnel planning to send their actuals to Loket so that these are included in the (semi-)automated payrolling proces. __Prerequisites:__ a client with access to the required activites is available. Most commonly these actuals refer to hours worked but may also refer to any other payroll components such as travel expenses, meal compensation or any other payroll component for that matter. __General remarks:__ * The resource Payroll Period data https://developer.loket.nl/#tag/Payroll-period-data should be used in this context. (Dutch name: Variabele Gegevens) * Within this resource it is possible to send actuals (for example hours worked) *per payroll period* for the given Employment * If this information is sent succesfully to Loket than this will be included the further payrolling process in Loket. __Technical remarks:__ * Please consider the data model of Loket.nl https://developer.loket.nl/ERD * An Employee (Persoon) has one or more Employments (Dienstverband). Payroll period data is sent to the Employment. * The configuration of the payroll administration (that the given Employment is linked to) determines what payroll components should be used to send the information to Loket * Accessory metadata and defaults endpoints will provide a lot of the required information * Please note that a payroll administration has one of three types of payroll periods: 1-month, 4-weeks and 1-week. Payroll periods of one month are most widely used. _A possible sequence of calls:_ Step 1: acquire Employment information from Loket * Acquire list Employers (GET Employers) * Optional: Acquire list of Employees (GET Employees) * Acquire list of Employments either per Employer or Employee (GET Employments) * Optional: Aqcuire any desired additional Employment information (e.g. GET WorkingHours, GET Wages) Step 2: send the actuals data to Loket * Acquire Metadata and Defaults information for Payroll Period Data (see Payroll Period Data resource) * Send actuals data for the Employment via Payroll Period Data (PATCH Payroll Period Data) * Optional: Check results (GET Payroll Period Data)

# 3. Information and dashboarding: acquire Employee- and Employment-related information from Loket __Goal:__ enable a system to acquire Employee and Employment information from Loket so this can be used for either dashboarding or any other further processing. Prerequisites: a client with access to the required activites is available. __General remarks:__ * Within this section we will only consider the 'one way street' integrations i.e. the external application only acquires information from Loket and does not send (insert or update) any information to Loket. __Technical remarks:__ * Please consider the data model of Loket.nl https://developer.loket.nl/ERD * An Employee (Persoon) has one or more Employments (Dienstverband). HR-related information is mostly related to the Employee, while payroll-related information is mostly related to the Employment. * Information related to Employee: Absences, Leave, Partner etc. * Information related to the Employment: WorkingHours, Wages, Organizational Entity (function, department), Payslips, Year-end Statements etc. * The citizen service number is separately authorized and is only provided to external parties if there is a reasonable cause to do so * Please consider the fact that time-dependent entities use so-called 'date chains' based on a start- and endDate https://developer.loket.nl/#section/Data/Default-values * If you are an external party and you are interested in the normal numbers of hours per week for that employment, you probably want to use the read-only field of aggregatedHoursPerWeek in the workingHours-resource (please see endpoint documentation for more details)

_A possible sequence of calls:_ Option 1: Acquire Employee information * Acquire list Employers (GET Employers) * Acquire list of Employees (GET Employees) * Acquire any additional entities for the Employee (GET Absence, GET Leave, GET Partner etc) Option 2: Acquire Employment information * Acquire list Employers (GET Employers) * Optional: Acquire list of Employees (GET Employees) * Acquire list of Employments either per Employer or Employee (GET Employments) * Aqcuire any additional entities for the Employment (e.g. GET WorkingHours, GET Wages, GET Payslips etc)

# 4. Financial information: acquire results from payroll and/or journal runs from Loket __Goal:__ enable applications that specialize in financial administration and/or accounting to extract results from the payrolling or journalization proces in Loket __Prerequisites:__ a client with access to the required activites is available. __General remarks:__ * The payrolling process in Loket is basically based on payroll runs that produce so-called payroll results. These payroll results are the numbers on which all of corresponding payslips, tax return, pension return etc are based. These results may be extracted from Loket. * Next to that, if that module is active, it is possible to perform a journal run for a payroll run. The functionality of journalization consists primarily of calculating the financial accounts (generalLedgerAccount, costCenter, costUnit). These results may be extracted from Loket. _A possible sequence of calls:_ Option 1: Acquire Payroll Run Results * Acquire list Employers (GET Employers) * Acquire list of Payroll Administrations for the Emloyer (GET Payroll Administrations) * Acquire list of Payroll runs for a Payroll Administration (GET Payroll Runs) * Acquire results for a Payroll Run (GET Payroll Run Results) Option 2: Acquire Journal Run Results * Acquire list Employers (GET Employers) * Acquire list of Payroll Administrations for the Emloyer (GET Payroll Administrations) * Acquire list of Journal runs for a Payroll Administration (GET Journal Runs) * Acquire results for a Journal Run (GET Journal Run Results)

# 5. Advanced interfaces: inserting and updating Employee and/or Employment information in Loket __Goal:__ enable applications build advanced integrations with Loket.nl __Prerequisites:__ a client with access to the required activites is available. A well-founded understanding of Loket.nl and its entities. __General remarks:__ * All remarks for the dashboard-type of integrations also apply here * This type of integration is the most complex one. A well-founded understanding of Loket is crucial to build a succesful interface, as an external party it is very highly advised to reserve time to get familiar with the functionalities of Loket and any points of attention. * One point of consideration is the fact that the payrolling configuration of Loket.nl is quite extensive and may differ for each payroll administration. __Technical remarks:__ * All possible validation messages for each activity are listed in the developer portal * Please adhere to the best-practices regarding RESTful objects. Avoid hard-coding especially when updating (PUT) existing resources. * Please note the technical difference between creating and updating Employee information (!). * Updating information for an existing Employee is relatively straight-forward in the sense that you can perform GET, PUT, POST, DELETE on the different resources you are interested in. * However for creating a new Employee a different approach is applied. Loket works in such a way that creating an Employee (with an Employment and its underlying entities) requires a rather large number of fields to be known in order to create an Employee. Loket needs this information in order for the payroll process to function correctly. * When an Employee is succesfully created then also a number of different underlying resources are created at the same time. These resources include Employee, Employment, WorkingHours, Wages, Fiscal Properties, Organizational Entity, Social Security, Healthcare Insurance Act, Other Payroll Variables and Payment Information SEPA. * The API facilitates the following process of creating a new Employee: * Create and update a jobApplicant (see the Job Applicant resource in the documentation). The job applicant may also be seen as a kind of 'concept employee' as it is not yet included in payrolling or any other process, and may be incomplete. ** Option a: enrich the jobApplicant information in the Loket GUI and manually convert it to an actual Employee (recommended) ** Option b: sufficiently enrich the jobApplicant and convert it to an actual Employee, all using the API. This is technically possible but in many cases not recommended because the external application will have to supply required information for the payrolling proces and in many cases they do not have all information required. * If a job applicant (concept employee) is converted to an actual employee than the unique identifier (GUID) will be copied over(jobApplicant.id == employee.id ) __General advice: create conceptEmployee using the API, then manually enrich and convert it to an actual Employee (!)__ To perform correct payrolling for an Employee, Loket.nl requires a large number of fields regarding to the Employee. Among other things, this is due to constantly evolving laws and regulations. The fields that are registered also have to pass a large number of input validations e.g. correct IBAN number. If an other system is leading in employee registration then quite often there is a wish to also (automatically) send this employee information to Loket.nl . However in that case, that system will have to provide all required fields in the correct manner. Because these systems (such as HR systems) often do not have all required payroll-related and regulation-related information available of an employee available. On top of that, the constantly evolving (government) regulations mean that there will be additional required fields almost yearly, everytime the integration would have to redeveloped to keep up. The changes in 2020 regarding the 'Wet Arbeidsmarkt in Balans' are on obvious example of that. A very much recommended alternative solution to that scenario is the conceptEmployee. A concept employee can be created and maintained (using the API), when creating the concept employee the other system (e.g. HR systems) will provide the employee information that is available to them at that point and send it to Loket.nl . After that, the accountant will be able to enrich the information of that concept employee and when sufficiently complemented convert it to an actual Employee (and with that include in the payrolling process). # 6. Single sign-on: set up an SSO link to Loket or Werknemerloket __Goal:__ enable an external application to set up a single sign-on flow that allows end-users to switch from that system to Loket without having to provide user credentials each time. __Prerequisites:__ a client will have to be available that is configured to perform SSO-calls to either Loket or Werknemerloket. * Loket is the identity provider. In other words a Loket user will need to be present in order to be able to set up the flow. * There is currenlty NO support for shared identity management services such as Azure Active Directory * The SSO flow is based on OAuth2 in is described in detail on the developer portal