Loket.nl API

Loket.nl API (V2)

Download OpenAPI specification:Download

Is this your first time here? Please check out our introduction to Loket (API)

The initial loading time of this developer portal may be very long due to the large number of endpoints designs being rendered when loading the page. We are looking into an alternative solution but for now please bear in mind.

General

The Loket.nl API is a RESTful API that exposes the data and features of the Loket.nl platform. The API accepts and returns JSON and can only be accessed by registered users. This documentation describes version 2 of the API.

Are you looking to partner up and start building an integration based on the Loket RESTful API? Please check out the steps for partners on our website .

Have you received your client and user credentials from us? Check out the following Postman collection to help you start making your first API calls on our acceptance environment. We would recommend to install the Postman desktop app.

Run in Postman

Do you want to contact us with any further questions or remarks regarding the Loket RESTful API? Please send an email to api@loket.nl, and we will get back to you.

Environments

The Loket.nl API has two different environments. The first environment is the "acceptance" environment which is used during development and returns test data. The second environment is the production environment which is to be used exclusively by approved applications. Both environments have their own URLs.

OpenAPI documentation

The endpoints are defined using the OpenAPI 3.1 specification, an industry-wide recognized standard for describing REST API's.

Please note: the endpoint documentation in this portal is not designed to be fully compatible with any automatic code generation tools.

Change policy

Over the course of time the API, and policies regarding the API can and will change. These changes are subject to the following guidelines.

The following states hold true for the change policy for this API.

  • Loket.nl may sometimes introduce changes to the API and policies without advance notice.
  • Loket.nl will try to inform users of any (breaking) change in advance.
  • Loket.nl will not be liable to you or any third party for such modifications or any adverse effects resulting from such modifications.
  • Loket.nl will try to avoid breaking changes as much as possible.

Notification periods

In regard to changes Loket.nl will strive to adhere to the following notification periods per type of change. Due to our versioning strategy at resource level this API has the possibility to run multiple versions of the same resource at one time. This allows for a window in which both the old and new version are available. Allowing for a gradual move to the new version.

Type of change Notification period Support period old version
Non breaking change 2 weeks no new version
Breaking change 2 weeks 6 months
Critical Due to the nature of these changes we might not be able to follow the normal procedure for change managment depends on the severity of the issue

We define a non breaking change as follows. Any change to the API that does not cause failures in the applications that consume that API.

  • Introducing a new optional field to an existing resource
  • Introducing a new endpoint
  • Introducing a new operation (GET/PUT/POST/PATCH/DELETE)
  • Introducing a new optional parameter to an endpoint
  • Introducing a new version for a resource

We define a breaking change as follows. any change to an API that could potentially cause failures in the applications that consume that API.

  • Changing an existing JSON element (name, datatype, pattern, min/max length etc)
  • Removing a JSON element, endpoint, operation or parameter
  • Introducing a required JSON element
  • Introducing a required parameter to an endpoint
  • Passing the obsoleteDate of a version for a resource

Versioning

The Loket API uses two types of versioning. API versioning and resource versioning.

API versioning

API versioning is done via the path where after the domain URL (api.loket.nl) the path starts with the API version. The current version of the API is V2. The API version is expected to change rarely as resource versioning is available to tackle most issues that need versioning.

Resource versioning

Every JSON resource in the API is versioned via the Accept header. Allowing users of the API to influence what version is returned by setting the mandatory accept header. The Accept header of request should have a value like application/json;version=2018-01-01. Here, the second part of the header is used to refer to a specific version of the resource (2018-01-01). When calling the API it is possible to supply other dates rather than the exact resources version(s). The businesslogic will select the version that is ON or BEFORE the given date. If no accept header with a resource version is given the newest version of the resource is returned

For example: let's say there are two versions of a resource. These are 2018-01-01 and 2018-09-01. When calling the API you supply application/json;version=2018-08-01, in that case the API will use the version 2018-01-01 as its the nearest version in the past.

A response returns what resourceVersion was used and the 'obsoleteDate' of that version (in most cases this is NULL). The obsoleteDate indicates when the resources version will no longer be available via the API. With the introduction of a new version of a resource the obsoleteDate for the old version will be set to 6 months after the introduction of the new resource. Allowing consumers of the resource 6 months to incorporate the change. Failure to do so will likely lead to failure in the implementation.

In this developer portal you can find the service contracts for each, active, version of a resource. If, only if, there are multiple versions of a resource you can select the corresponding schema at that resource.

Changelog

The changelog for this API can be found here.

We strongly advise every user ofthe Loket REST API the subscribe to the email feed. Please check out the link on the changelog page.

Legal notices

Your use and access to the API is expressly conditioned on your compliance with the policies and restrictions related to the API. If Loket.nl believes that you have or attempted to violate any term, condition, or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.

Authentication

Authorization in the Loket API is based on the industry-standard OAuth 2.0 protocol. For general information on OAuth 2.0 we kindly refer to the publicly-available documentation, https://oauth.net/2/

An authorized user is required to call the Loket API.

Note: This is an SSL-only API.

Note: Only TLS 1.2 is supported.

Environment TokenUrl
Acceptance https://oauth.loket-acc.nl/token
Production https://oauth.loket.nl/token

The following OAuth 2.0 flows are supported

  • Authorization Code flow (standard)
  • Refresh Token flow (extension on the Authorization Code Flow)
  • SSO flow (single sign-on)
  • Password flow

Authorization code flow

For most clients only the authorization_code (and thus refresh_token) will be supported. Password grant type is not available for an external client.

Please click the link below to see documentation on implementing the authorization code flow by external clients.

Documentation on implementing the OAuth 2.0 authorization code flow

Refresh token flow

After the authorization code flow yields a refresh token the refresh_token grant can be used to obtain an access/bearer token. The expire time of the access/bearer is also returned in the response please take this into account. With the refresh token flow the two factor step will be skipped.

Refresh token request example:

POST /token 
grant_type=refresh_token&refresh_token={RefreshToken123}&client_Id={Client123}&client_secret={Secret123}

Refresh token response example:

{
  "access_token": "JESJDhMBy0NPTM9SiXmYAzW45clOiQ5wSyDq3VWluguGNoKym4WPSiJoTDx67TQ",
  "token_type": "bearer",
  "expires_in": 3599,
  "refresh_token": "nGJtF6j6SeQbHAg",
  "two_factor_state": "None"
}

SSO flow

The SSO (single sign-on) flow is based on OAuth 2.0 and requires the authorization flow to be completed.

For more information see: Documentation on OAuth 2.0 SSO flow (for allowed clients)

Please note: Among other things, it is possible to set up an SSO flow with both Loket en Werknemerloket.

Password flow

The password flow is typically NOT enabled for external clients. Only by exception will the password flow be enabled for security (and practical) reasons.

Password token request examples:

POST /token 
grant_type=password&username={UserName123}&password={Password123}&client_Id={Client123}&client_secret={Secret123}

Whether client_secret is required is dependent on the configuration of the client.

Authorization

In this section we explain how the API authorization service determines if a request is authorized or not.

The authorization entities

Entity Description
Client Loket.nl used the client as an additional authorisation entity. By linking clients to activities clients can only perform those activities they are linked to.
User Is linked to a client (by performing the authorization code flow) and to a set of rechten (configuration in loket.nl)
Module (product) Enables certain functionality for the provider/employer. Modules can be enabled and disabled on both provider and employer level.
Role Influences if certain "rechten" are available to the users with said role. It can also influence the scope of the data returned. For example: the API will deny an "afdelings manager" access to employee's that are not in the "afdeling" (department) that user is manager of
Activity Every action in the API has its own activity. Using the Open API 3.0 standard these activity names are incorporated in the documentation using the operationId and in most cases are named in the description of an endpoint.
Rights (rechten) Represent a group of activities.

The authorization process

This flow assumes that both user and client are correctly configured and have access to the API.

  1. Does the client have access to the activity?
  2. Does the user have access to the activity (through "recht")?
  3. Does the role have access to the activity (through "recht")?
  4. Does the provider/employer have the required module enabled for the activity?
  5. Does the user have access to the specified entity/ID?

If the answer to all the questions above is yes then the request is authorized otherwise the request is denied with a HTTP status code 403 (Forbidden). See the simplified authorization flow in the figure below.

Side note: users are linked to rechten and clients are linked to activities. This leaves room for discrepancies. Where a client cannot perform the activity because the client is not authorized to call that activity even though the user does have the "recht" granting access to the activity.

Loket authorization flow

Which users can use the API

In almost all use-cases a Loket user should meet the following requirements to successfully setup an integration with that user.

  • The user must be a normal Loket user (so NOT a webservice user)
  • The user must be active (not blocked)
  • The user must have access to an employer
    • For provider users this is done by assigning the user to the appropriate Team(s)
    • For employer users this is done by creating a user for or linking the user to the appropriate employer(s)
  • The user must have all appropriate rights
    • For provider users this is done by assigning appropriate rights via Team (or alternatively, directly to the user)
    • For employer users this is done by assigning appropriate rights to the user on employer level

How to setup an integration is described in the Authentication section.

Side notes:

  • A user can have access to multiple employers with different rights per employer.
  • Please note that users set up to use the SOAP webservices (webservicegebruikers) are in no way suited to perform calls to the RESTful API, these require entirely different user set-ups.
  • User management on production is typically done by the provider (i.e. the accountant) and sometimes the employer. This is NOT something Loket.nl itself can do.

Data

Data types

The Loket.nl API accepts and returns JSON. Comform the OpenAPI 3.0 specification the following data types are supported:

  • string
  • number (point is used to separate the integer part from the fractional part of a number)
  • integer (from OpenAPI)
  • object
  • array
  • boolean

For most of these types, further specifications can be found in the format and pattern specifications in the service contract. For example a format: date added to a string field indicates a valid date must be supplied.

Metadata

Fields of the type 'metadata' are fields for which the possible values can be acquired via the metadata endpoint of the resource.

The metedata can be obtained by appending /metadata to the current endpoint. Using the GET verb the endpoint will return a JSON output with "all" the metadata for the given resource. In some cases multiple requests are needed to obtain all the metadata required, an exmple is given below. Typically different metadata endpoints are availalbe for the POST and the PUT endpoint.

If metadata endpoints are avaible for a given endpoint/resource is mentioned in the description of that endpoint.

Example response

{[
  {
      "field": "gender"
      options: [
          {
          "key": 1,
          "value":"Man"
          }
          {
          "key": 2,
          "value":"Vrouw"
          }
      ]
   },
   {
      "field": "country"
      options: [
          {
          "isoCode":"NL",
          "key": 530,
          "value":"Nederland"
          }
          {
          "isoCode":"BE",
          "key": 540,
          "value":"België"
          }
      ]
   }

]}

Example urls

Acquiring metadata for a POST Wage

/v2/providers/employers/employees/employments/{employmentId}/wages/metadata

Acquiring metadata for a PUT employee

/v2/providers/employers/employees/{employeeId}/metadata

Multiple requests to get all the metadata

In some cases there are metadata fields dependant on the selected value off another metadata field. Such is the case when adding a new concept employee. This is done in the employer context while several of the metadata fields are dependant on the payrollAdministration context.

For example:

Request 1, first of a normal metadata request is performed. The response for this request will contain a list of payrolladministration for the given employer.

/v2/providers/employers/b869ded6-0659-4d8d-9a8a-f9e22425ec9c/jobapplicant/metadata

Request 2, when a payrolladministration is selected perform a second request to acquire the payrolladministration specific metadata.

/v2/providers/employers/jobapplicant/metadata/payrolladministration/54369214-14a1-41ab-892a-ea8438e34d6f

Request 3, if a payScale is selected perform a third request to acquire the payGrade for that payScale.

/v2/providers/employers/jobapplicant/metadata/salaryScaleType/54369214-14a1-41ab-892a-ea8438e34d6f

Types of metadata

We diferentiate between two types of metadata.

  1. Generic metadata field. The possible values for these fields are the same for every object no matter the provider, employer or employee etc. Examples are: country, gender and nationality.
  2. Context specific metadata field. Examples of contexts are employer, payroll administration, provider and Loket.nl. In most cases the possible values for these field are resources in themselves and can be managed via the API. If a metadata field is context specific the context is given in the description of the field. Examples are: function, department and leaveType.

Note: some context specific metadata field can have multiple contexts.

For example: it is possible to define an export set in the provider context. Making that export set available for all payroll administrations linked to the provider. It is also possible to add an export set in the payroll administration context. That export set is only available to that payroll administration. When requesting the metadata of export set the user will be presented with a combined list of the provider and payroll administration export sets.

Default values

Many fields in the API have a default value. In order to assist our API users to adhere to these defaults when creating a record (POST) we provide /defaults endpoints.

  • An object returned by the defaultsendpoint resembles a fully expanded GET-object of that resource. The only case when a part of the object is NOT fully expanded is for a metaData-object that does not have a default value (for example '"gender":NULL').
    • Whether an object within the resource is of the type metaData is indicated in the service contracts of that resource.
  • Context is determined by the GUID given in the Path. Examples are employer, payroll administration, employee and employment.
  • A scope is sometimes required to determine the defaults values. A scope could be a date by which Loket.nl can determine what default was active on that date. The scope can be set by supplying additional paraments in the request. If a scope is required but none is given the currently active or last know value is returned.
  • The fields with no default will be set to null (even if the field is normally non-nullable).
  • Because the GET-object is returned the readonly fields are also returned.

An example endpoint would be:

/v2/providers/employers/employees/employments/{employmentId}/payrollperioddata/defaults

resulting in the following output:

{
  "payrollPeriod": null,
  "shift": {
      "shiftNumber": 1
  },
  "payslipType": {
      "key": 2
  },
  "payslipText": null,
  "distributionUnit": {
      "key": "b14acd0d-75d7-4fc8-8b22-4a3924585cab"
  },
  "costCenter": {
      "key": 2
  },
  "costUnit": {
      "key": 2
  },
  "payrollComponents": []
}

Note: Defaults endpoints are not yet generically available. If a Defaults endpoint exists this will be explicitly stated at that specific resource.

Date chains

For most of the resources with a startDate and endDate a chain is maintained. Chain meaning that no records can overlap in time. Loket.nl has two types of chains.

  1. Broken chain: It is possible for gaps te exist between the records. It is also possible to add new records in between or before existing records aslong as no overlap occures.

  2. Linked chain: No gaps between records are allowed. Its only possible to add new records to the end of the chain resulting in the closing of the reviouse record with the start date -1 as end date.

Note: Chains are sometimes maintained with an additional context. For example, For benefits and deductions the broken chain is maintained per payrollComponent. It is possible to have multiple active records for different payrollComponent never two active records for the same payrollComponent.

Custom export

For some GET (list) endpoints the API supports exporting (part of) the output JSON as a XML/CSV file. This is done by setting the X-ReportInput and Accept header.

The Accept header supports the following 2 options:

  • CSV (text/csv;version=yyyy-MM-dd)
  • Excel (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;version=yyyy-MM-dd)

The X-ReportInput is a custom header that requires a JSON object with the following structure as input.

  1. fileNameWithoutExtension --> The filename without extension for the report 'FileNameWithoutExtension'
  2. delimiter --> The delimiter to be used. If not set "," is used
  3. decimalSeparator --> The decimalSepartor for number fields. If not set "." is used.
  4. fields --> Array of fields.

The 'fields' object contains one or more fields with the following properties:

  1. fieldName --> A Xpath reference to the field to be included in the export
  2. reportColumnName --> The column name for the field
  3. format --> Allows only for date formatting. e.g. dd-MM-yyyy for csv or dd-mm-yyyy for Excel (Excel only usses lowercase)

3.1 For CSV: see https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings

3.2 For Excel: https://support.microsoft.com/en-us/office/number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68

Example X-ReportInput:

{
"fileNameWithoutExtension":"MyExport",
"delimiter": ";",
"decimalSepartor": ",",
"fields":
  [
    {
      "fieldName": "startDate",
      "reportColumnName": "In dienst datum",
      "format": "dd-MM-yyyy"
    },
    {
      "fieldName": "personalDetails.firstName",
      "reportColumnName": "First Name"
    },
    {
      "fieldName": "personalDetails.lastName",
      "reportColumnName": "Last Name"
    }
  ]
}

Example request:

curl 
--location 
--request GET 'https://api.loket.nl/v2/providers/employers/155c8440-8ff6-4776-98db-5d2243a073e3/employees?orderby=employeeNumber' \
--header 'Content-Type: application/json' \
--header 'Accept: text/csv;version=2020-08-18' \
--header 'X-ReportInput: {"FileNameWithoutExtension":"MyExport","Fields":[{"fieldName":"personalDetails.initials","reportColumnName":"Initials"},{"fieldName":"personalDetails.firstName","reportColumnName":"First name"},{"fieldName":"personalDetails.lastName","reportColumnName":"Last name"}]}' \--header 'Authorization: Bearer ZKoiC_g_NfYA3v0' \

Request

A request to the Loket.nl API consists of several components. Each of these components are discussed in this section.

Base URL

The API can be accessed at https://api.loket.nl. The version of the API is specified in the URL. The current version of the Loket.nl API is version 2. To access version 2 of the API, one simply appends v2 to the base URL. The full base URL of the API is therefore https://api.loket.nl/v2.

Endpoints

The endpoints defined in the OpenAPI definition of the Loket.nl API are appended to the base URL. For example, the endpoint /providers/employers/{employerId}/employees can be accessed at https://api.loket.nl/v2/providers/employers/{employerId}/employees.

Path parameters

Most endpoints require path parameter(s) in order to specify the context of the request. For example, the endpoint /providers/employers/{employerId}/employees contains the employerId path parameter. A path parameter is a unique identifier that identifies a specific resource, in this case an employer.

Pagination

The API supports two query parameters to control the pagination of the results: pageNumber and pageSize. Both of these query parameters only apply to endpoints that return lists of entities.

The pageNumber query parameter specifies which page of the collection to return. By default pageNumber is set to 1 which returns the first page of the collection. Note: the pageNumber refers to the page (with a given number of entities), NOT to a specific entity within a page!

The pageSize query parameter influences the number of entities per page. By default pageSize is set to 250. Note that this default may change in the future. It is not recommended to depend on this default when developing for the Loket.nl API.

Examples:

  • ?pageNumber=2 to return the second page
  • ?pageSize=2 to set the page size to two

Filtering

The API supports output filtering via the querystring parameter filter.

Filtering is possible on all fields of the following datatypes:

  • string
  • integer
  • boolean
  • date-time
  • decimals

The following operators are available:

Operator Description Example
Comparison Operators
eq Equal city eq 'Redmond'
ne Not equal city ne 'London'
lk Like city lk 'Lond'
gt Greater than price gt 20
ge Greater than or equal price ge 10
lt Less than price lt 20
le Less than or equal price le 100
Logical Operators
and Logical and price le 200 and price gt 3.5
or Logical or price le 3.5 or price gt 200

Both field names and values are case insensitive. It is possible to filter on nested fields by adding the parent object before the field with a '.' to separate them. Do remember to URL encode the filter parameters.

Examples

All employments with a cancellation periode in months (the value 4 corresponds to months time unit).


/v2/providers/employers/{{employerId}}/employees/employments?filter=cancellationPeriodTimeUnit.key eq 4

All employments with no endDate.s


/v2/providers/employers/{{employerId}}/employees/employments?filter=enddate eq null

All employments with an end date less or equal to 2017-01-01


/v2/providers/employers/{{employerId}}/employees/employments?filter=enddate le '2017-01-01'

All employees with a employee number greater or equal 1 and less or equal 5


/v2/providers/employers/{{employerId}}/employees?filter=employeeNumber ge 1 and employeeNumber le 5

Ordering

All Loket.nl API resources support ordering of the elements in the response on a specific field. All fields can be used in ordering. The list can be ordered in ascending or descending order, with ascending being the default one. Ordering on multiple fields is also by using a ',' as a separator.

Examples

Order employers by company name ascending


/v2/providers/employers?orderBy=companyName

Order employers by company name descending


/v2/providers/employers?orderBy=-companyName

Order employers by company name descending then by house number ascending


/v2/providers/employers?orderBy=-companyName,address.houseNumber

Headers

In order to access the endpoints of the Loket.nl API, at least two request headers need to be set.

1) the Authorization header is required in order to authorize the API call. The value of this header is the word Bearer followed by a space and the access token acquired from the /token endpoint. For example, if the acquired access token is AbCdEf123456, the value of the Authorization headers would be:

Authorization: Bearer v69uloc3wcEFLePw2unot0FfAJfBocrvSwsrCo75JLUG7aE54zqSUnU

2) The second header that is required for proper usage of the API, is the Accept header. This header is used for the resource versioning feature and is therefore crucial for making sure the response remains the same when new resource versions are introduced. The value of the Accept header differs per endpoint is defined in the OpenAPI documentation of the endpoints.

Accept: application/json;version=2018-01-01

Response

In addition to the responses defined in the OpenAPI documentation, the Loket.nl API also provides additional fields that give more information about the response and the entities requested. This section will explain the full response given by the Loket.nl API by examining the example response below.

Example 400 response


{
    "version": {
        "obsoleteDate": null,
        "versionNumber": "2018-01-01,
    },
    "messages": [
        {
            "code": 83,
            "id": null,
            "type": "BrokenBusinessRule",
            "description": "[field] has an invalid length",
            "properties": []
        }
    ],
    "_embedded": []
}

Example 200 response


  {
      "totalSize": 1,
      "pageSize": 250,
      "totalPages": 1,
      "currentPage": 1,
      "version": {
          "obsoleteDate": null,
          "resourceVersion": "2018-01-01"
      },
      "messages": [],
      "content": {
          "id": "2b4c119c-527c-4cbb-a5b2-f3a11e4b76cx",
          ...
      }
  }

Paging

  • totalSize has an integer value indicating the total number of entities irrespective of the page size.

  • pageSize has an integer value indicating the maximum number of entities returned per page. The page size can be influenced by setting the pageSize query parameter. See the section Query Parameters for more information.

  • totalPages has an integer value indicating the number of pages the requested collection holds given the specific pagesize.

  • currentPage has an integer value indicating the current page number. The current page number can be influenced by setting the pageNumber query parameter. See the section Query Parameters for more information.

Version

The version object provides information regarding the resource version of the entity requested.

  • obsoleteDate contains the date of discontinuation for the requested resource version. The value of this field can be null indicating that the requested resource version is not planned to be obsoleted at the time of the request.

  • resourceVersion shows the version of the requested entity. The resource version can be influenced by setting the Accept header.

Messages

The messages field contains a list of message objects related to the request made. Any warnings and errors will be communicated in this list of messages

  • type has a string value indicating the type of message. At this time the Loket.nl API supports five types of messages: BrokenBusinessRule, Warning, Exception and NotFound .

  • description has a string value that describes the message that has occurred.

  • code is an identifying code for the message. Please note that this code may change in the future. See the documentation portal for possible message codes for an endpoint.

  • id relates the message to a specific entity in the reponse list. For example, in cases where a warning occurs for one of the entities in a list, the value of this field can be used to identify to which entity the warning applies. Currently implemented for endpoints where a multi-patch is performed (multiple actions are performed within one call) for example updating the status of one or more leaveRequests.

  • properties an array that can contain additional information regarding the message. Currently not yet fully implemented.

  • _embedded contains the list of entities as defined for each endpoint in the OpenAPI documentation. Please refer to that documentation for the contents of the _embedded field for each endpoint. For endpoints that return only one entity (detail endpoints) the _embedded field is replaced with a content field. The content of this field can also be found in the documentation for each endpoint.

Headers

  • Expires header is returned with every response to indicate how long a response can be cached
  • Content-Disposition header is used in case of downloads to provide a file name

HTTP status codes

The Loket.nl API supports the following http status codes.

Code Is returned when
200 The request to GET, PUT, PATCH or DELETE and object was recived and processed succesfully. The response might still contain messages of the type warning.
201 The request to insert (POST) a new object was recived and processed succesfully. The response might still contain messages of the type warning.
400 The request was received but could not be processed. The reason(s) will be given in the response. The content type of the response may be text/plain for API-level error messages, such as when trying to call the API without SSL otherwise the content will be application/json.
401 The bearer token provided in the authorization header is invalid. Do not retry the request until a new (valid) bearer token is acquired.
403 The user is not authorized to access the resource. The reason will be given in the response. Do not retry the request until the, configuration, issue is resolved.
404 The resource requested was not found/does not exist.
50* A unforseen error occurred. Please check the request if everything seems te be in order on your side contact the support team. Provide as much information as possible to resolve the issue.

Note: for a limited number of endpoint a so-called multi-patch may be performed (multiple actions within one call). In that case the status code will be 200 if at least on of the actions succeeds, if other any action(s) in that call fail(s) a message will be returned including the given id of that entity.

Caching

The API uses the Expires header to indicate how long the item can be reused from the local cache. In most cases caching is not allowed for resources. Exceptions excist, such as pictures like the employer logo and the employee photo, in these cases the cache duration is mentioned in the description of the resource.

Provider

NL: Provider (i.e. accountant) Provider related endpoints.

List of providers

Activity name : GetProvidersByUser

Get a list of all providers accessible to the current user. Note: With the current functioning of Loket, the list will always contain 1 provider.

Note: This endpoint is typically not relevant for most external parties, as the GetEmployerByUser endpoint will be much more relevant as starting point.

query Parameters
filter
string
Example: filter=cancellationPeriodTimeUnit.key eq 4

Filter the collection

orderBy
string^-?\w+(,-?\w+)*$
Example: orderBy=-companyName,address.houseNumber

Order the collection on one or more fields

pageNumber
integer <int32>
Default: 1
Example: pageNumber=2

Specifies which page should be returned

pageSize
integer <int32>
Default: 250
Example: pageSize=20

Specifies the number of objects per page

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json;version=2018-01-01
{
  • "totalSize": 650,
  • "pageSize": 250,
  • "totalPages": 3,
  • "currentPage": 2,
  • "version": {
    },
  • "messages": [
    ],
  • "_embedded": [
    ]
}

Download the provider logo

Activity name : GetProviderLogo

This activity is listed twice in the documentation due to the specified version caching path parameter. Including or exluding this parameter results in slightly different behaviour.

Caching: This resource changes very infrequently and can be cached for a longer time.

Get the logo of the provider of the user. In case no logo is know the service will return a 404.

path Parameters
providerId
required
string <uuid>

The unique identifier of a provider

version
required
string <uuid>

An guid generated for caching. The value does not influence the output of this function. The provider/logo endpoint returns the URI of the current logo with the version.

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json
{
  • "message": "Authorization has been denied for this request."
}

Logos at providerlevel

Activity name : GetProviderLogosByProviderId

Get a list of all logos that are available at providerlevel. Other endpoints can be used to set the logo as default for all employers or to set the logo as a aberrant provider logo at employer level.

path Parameters
providerId
required
string <uuid>

The unique identifier of a provider

query Parameters
filter
string
Example: filter=cancellationPeriodTimeUnit.key eq 4

Filter the collection

orderBy
string^-?\w+(,-?\w+)*$
Example: orderBy=-companyName,address.houseNumber

Order the collection on one or more fields

pageNumber
integer <int32>
Default: 1
Example: pageNumber=2

Specifies which page should be returned

pageSize
integer <int32>
Default: 250
Example: pageSize=20

Specifies the number of objects per page

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json;version=2018-01-01
{
  • "totalSize": 650,
  • "pageSize": 250,
  • "totalPages": 3,
  • "currentPage": 2,
  • "version": {
    },
  • "messages": [
    ],
  • "_embedded": []
}

Upload a logo for the provider

Activity name : PostProviderLogoByProviderId

Upload a logo at providerlevel. Other endpoints can be used to set the logo as default for all employers or to set the logo as a aberrant provider logo at employer level.

path Parameters
providerId
required
string <uuid>

The unique identifier of a provider

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Request Body schema: application/json;version=2018-01-01
required

Logo to be uploaded for the provider.

attribute
string <= 10 characters

the attribute of the logo.

name
string <= 50 characters

The name of the logo.

data
string

base64 encoded document file.

mimeType
string

The mimetype of the data.

Responses

Request samples

Content type
application/json;version=2018-01-01
{
  • "attribute": "Logo 1",
  • "name": "ProviderLogo",
  • "data": "YQ==",
  • "mimeType": "image/jpeg"
}

Response samples

Content type
application/json;version=2018-01-01
{
  • "version": {
    },
  • "messages": [
    ],
  • "content": {
    }
}

Logo at providerlevel

Activity name : GetProviderLogoByLogoId

Get a logo that is available at providerlevel. Other endpoints can be used to set the logo as default for all employers or to set the logo as a aberrant provider logo at employer level.

path Parameters
logoId
required
string <uuid>

The unique identifier of a logo

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json;version=2018-01-01
{
  • "version": {
    },
  • "messages": [
    ],
  • "content": {
    }
}

Edit a provider logo

Activity name : PutProviderLogoByLogoId

Edit a logo at providerlevel. Other endpoints can be used to set the logo as default for all employers or to set the logo as a aberrant provider logo at employer level.

path Parameters
logoId
required
string <uuid>

The unique identifier of a logo

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Request Body schema: application/json;version=2018-01-01
required
attribute
string <= 10 characters

the attribute of the logo.

name
string <= 50 characters

The name of the logo.

data
string

base64 encoded document file.

mimeType
string

The mimetype of the data.

Responses

Request samples

Content type
application/json;version=2018-01-01
{
  • "attribute": "Logo 1",
  • "name": "ProviderLogo",
  • "data": "YQ==",
  • "mimeType": "image/jpeg"
}

Response samples

Content type
application/json;version=2018-01-01
{
  • "version": {
    },
  • "messages": [
    ],
  • "content": {
    }
}

Delete a logo at providerlevel

Activity name : DeleteProviderLogoByLogoId

path Parameters
logoId
required
string <uuid>

The unique identifier of a logo

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json
{
  • "version": {
    },
  • "messages": [
    ],
  • "content": { }
}

Logo without properties at providerlevel

Activity name : GetProviderLogoOnlyByLogoId

Get the logo that is available at providerlevel, without additional properties. Other endpoints can be used to set the logo as default for all employers or to set the logo as a aberrant provider logo at employer level.

path Parameters
logoId
required
string <uuid>

The unique identifier of a logo

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json
{
  • "message": "Authorization has been denied for this request."
}

Employer

NL: Werkgever. Manage an employer

List of employers

Activity name : GetEmployersByUserId

Get a list of all employers accessible to the current user

Please note the following general remark regarding the Loket API. If an id is required as a path parameter, in almost all cases the UUID of the specific resource should be used. In the employer resource this corresponds to the the 'id' field, as is typical. (so do NOT use employerNumber as your path parameter for any following requests)

query Parameters
filter
string
Example: filter=cancellationPeriodTimeUnit.key eq 4

Filter the collection

orderBy
string^-?\w+(,-?\w+)*$
Example: orderBy=-companyName,address.houseNumber

Order the collection on one or more fields

pageNumber
integer <int32>
Default: 1
Example: pageNumber=2

Specifies which page should be returned

pageSize
integer <int32>
Default: 250
Example: pageSize=20

Specifies the number of objects per page

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json;version=2018-01-01
{
  • "totalSize": 650,
  • "pageSize": 250,
  • "totalPages": 3,
  • "currentPage": 2,
  • "version": {
    },
  • "messages": [
    ],
  • "_embedded": [
    ]
}

List of employers with fewer fields for performance reasons

Activity name : GetEmployersMinimizedByUser

Get a list of all employers accessible to the current user. With this endpoint we introduced the "Minimized" resource which contains fewer fields then /providers/employers. This version should increase performance when requesting employments for large employers.

query Parameters
filter
string
Example: filter=cancellationPeriodTimeUnit.key eq 4

Filter the collection

orderBy
string^-?\w+(,-?\w+)*$
Example: orderBy=-companyName,address.houseNumber

Order the collection on one or more fields

pageNumber
integer <int32>
Default: 1
Example: pageNumber=2

Specifies which page should be returned

pageSize
integer <int32>
Default: 250
Example: pageSize=20

Specifies the number of objects per page

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json;version=2018-01-01
{
  • "totalSize": 650,
  • "pageSize": 250,
  • "totalPages": 3,
  • "currentPage": 2,
  • "version": {
    },
  • "messages": [
    ],
  • "_embedded": []
}

Create an employer

Activity name : PostEmployerByProviderId

Create an employee for the provider (administratiekantoor) identified by the given providerId. Please take note of the following; a newly created Employer is not immediately accessible for the user. As this would require adding the Employer to a specific Loket team (which is a separate activity)

Metadata : Possible options for fields of the type 'metadata' can be acquired (GET) by adding /metadata to the POST URL.

Defaults : Default values for a new object can be acquired by adding `/defaults' to the POST URL.

path Parameters
providerId
required
string <uuid>

The unique identifier of a provider

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Request Body schema: application/json;version=2018-01-01
required

Employer to be created.

companyName
string (companyName) <= 70 characters

Name of the company

chamberOfCommerceNumber
string or null (chamberOfCommerceNumber) <= 35 characters

Chamber of commerce number. In Dutch "Kamer van koophandel" number

object or null <metadata> (sbi)

The 'Standard Industrial Classifications (Dutch SBI 2008, NACE and ISIC)' as defined bij the Dutch chamber of commerce

object or null <metadata> (legalForm)
object or null <metadata> (branch)
object (providerSettings)
object or null (contact)
object or null (components-schemas-contactInformation)
object (address)
object or null (deviatingPostalAddress)

Responses

Request samples

Content type
application/json;version=2018-01-01
{
  • "companyName": "Voorbeeld B.V.",
  • "chamberOfCommerceNumber": "18124676",
  • "sbi": {
    },
  • "legalForm": {
    },
  • "branch": {
    },
  • "providerSettings": {
    },
  • "contact": {
    },
  • "contactInformation": {
    },
  • "address": {
    },
  • "deviatingPostalAddress": {
    }
}

Response samples

Content type
application/json;version=2018-01-01
{
  • "version": {
    },
  • "messages": [
    ],
  • "content": {
    }
}

Details of an employer

Activity name : GetEmployerByEmployerId

Get the details of a single employers

path Parameters
employerId
required
string <uuid>

The unique identifier of the employer

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json;version=2018-01-01
{
  • "version": {
    },
  • "messages": [
    ],
  • "content": {
    }
}

Edit the details of an employer

Activity name: PutEmployerByEmployerId

Edit the details of an employer

Possible options for fields of the type 'metadata' can be acquired (GET) by adding /metadata to the PUT URL.

path Parameters
employerId
required
string <uuid>

The unique identifier of the employer

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Request Body schema: application/json;version=2018-01-01
required

Employer

companyName
string (companyName) <= 70 characters

Name of the company

chamberOfCommerceNumber
string or null (chamberOfCommerceNumber) <= 35 characters

Chamber of commerce number. In Dutch "Kamer van koophandel" number

object or null <metadata> (sbi)

The 'Standard Industrial Classifications (Dutch SBI 2008, NACE and ISIC)' as defined bij the Dutch chamber of commerce

object or null <metadata> (legalForm)
object or null <metadata> (branch)
object (providerSettings)
object or null (contact)
object or null (components-schemas-contactInformation)
object (address)
object or null (deviatingPostalAddress)

Responses

Request samples

Content type
application/json;version=2018-01-01
{
  • "companyName": "Voorbeeld B.V.",
  • "chamberOfCommerceNumber": "18124676",
  • "sbi": {
    },
  • "legalForm": {
    },
  • "branch": {
    },
  • "providerSettings": {
    },
  • "contact": {
    },
  • "contactInformation": {
    },
  • "address": {
    },
  • "deviatingPostalAddress": {
    }
}

Response samples

Content type
application/json;version=2018-01-01
{
  • "version": {
    },
  • "messages": [
    ],
  • "content": {
    }
}

List of child employers accessible to the current user

Activity name : GetChildEmployersByEmployerId

Get a list of all employers accessible to the current user which are a child of the provided employer.

path Parameters
employerId
required
string <uuid>

The unique identifier of the employer

query Parameters
filter
string
Example: filter=cancellationPeriodTimeUnit.key eq 4

Filter the collection

orderBy
string^-?\w+(,-?\w+)*$
Example: orderBy=-companyName,address.houseNumber

Order the collection on one or more fields

pageNumber
integer <int32>
Default: 1
Example: pageNumber=2

Specifies which page should be returned

pageSize
integer <int32>
Default: 250
Example: pageSize=20

Specifies the number of objects per page

includeParent
boolean
Example: includeParent=true

Determines whether the information of the parent employer should be included in the response. If not provided, this parameter defaults to false and the response will not include the information of the parent.

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json;version=2018-01-01
{
  • "totalSize": 650,
  • "pageSize": 250,
  • "totalPages": 3,
  • "currentPage": 2,
  • "version": {
    },
  • "messages": [
    ],
  • "_embedded": [
    ]
}

Logo of an employer

Activity name : GetEmployerLogoByEmployerId

This activity is listed twice in the documentation due to the specified version caching path parameter. Including or exluding this parameter results in slightly different behaviour.

Caching: This resource changes very infrequently and can be cached for a longer period.

Get the logo of the employer. In case no logo is know the service will return a 404.

path Parameters
employerId
required
string <uuid>

The unique identifier of the employer

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json
{
  • "message": "Authorization has been denied for this request."
}

Delete the employer logo

Activity name: DeleteEmployerLogoByEmployerId

Delete the logo of an employer

path Parameters
employerId
required
string <uuid>

The unique identifier of the employer

header Parameters
Authorization
required
string^Bearer\s[\w-]+$
Example: Bearer <TOKEN>

A valid Bearer token for authorizing the request.

Accept
required
string
Example: application/json;version=2018-01-01

The accept header is used to influence what type of output is returned and in most cases the version of the output

Responses

Response samples

Content type
application/json
{
  • "version": {
    },
  • "messages": [
    ],
  • "content": { }
}

Upload a logo for the employer

Activity name : PostEmployerLogoByEmployerId

Upload a logo f