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.**
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 test 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 [email protected]
, and we will get back to you.
The Loket.nl API has two different environments.
The first environment is the "test" 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.
The test environment can be accessed at https://api.loket-test.nl/v2/
The production environment can be accessed at https://api.loket.nl/v2/
The endpoints are defined using the OpenAPI 3.0 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.
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.
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
The Loket API uses two types of versioning. API versioning and resource 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.
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.
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.
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.
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.
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 |
| -------------------- | -------------------------------- |
| Test | https://oauth.loket-test.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)
Authorization code flow
For most clients only the authorizationcode (and thus refreshtoken) 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:
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.
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.
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, ConcurrencyViolation 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.
etag header is returned with every GET of a detail (single resource). This header is used for concurrency controle
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. |
| 409 | The give if-match header in a PUT request no longer represents the current state of the object. Please acquire the current state off the object, via a GET, and resolve the differences then try again. |
| 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.
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.