Documentatie Frontoffice (EF2GO) API

About our API
Costs for using the API
Moving from GraphQL to the new API
New API access
How to access the API documentation
Testing the API
Required field: from
Rate limiting
Sorting
Filtering
Including related resources
Pagination with per_page and cursor
Webhooks
API response codes
Need help or have any questions about the API?

About our API

Our API is designed following the principles of REST (Representational State Transfer). This means:

It uses standard HTTP methods like GET, POST, PUT, and DELETE.
Resources (such as locations, companies, customers) are accessed via intuitive URLs.
It supports stateless communication, so each request contains all the information needed.
Responses are typically in JSON format, making it easy to integrate with modern applications.

Whether you’re a developer, partner, or just curious, our API documentation is openly available and can be accessed by anyone.

Costs for using the API

You can use the new API free of charge until June 30, 2026. This period serves as our pilot phase, so please feel free to share any feedback or suggestions.

Moving from GraphQL to the new API

Please note that our GraphQL API is no longer maintained and will not receive updates or support. To ensure stable and secure integrations, we strongly recommend migrating to the new Frontoffice (EF2GO) REST API.

New API access

To access the new Frontoffice (EF2GO) API, you must create a new API key (Bearer token).
API keys can be generated via Beheer > Koppelingen > API.

Important: The key is displayed only once at the time of creation. Make sure to store it securely, as it cannot be retrieved later.

Each API key must now be linked to one or more IP addresses or IP ranges using CIDR notation. This ensures that only requests coming from approved locations can access the API, adding an extra layer of security.

You can configure the following options for your API key:

IP Filters – Specify which IP addresses (e.g., 203.0.113.5) or IP ranges in CIDR format (e.g., 203.0.113.0/24) are allowed to use this key. Requests from any other address will be blocked. (Defining at least one IP address is required.)
Token Type – Choose between:
- Tenant token: Applies to all users in the tenant. With this type you are allowed GET requests only.
- User token: Linked to a specific user. With this type you may perform GET, PUT, POST and DELETE requests.

Location restrictions

When using a user token, location restrictions are applied by default.

What does this mean?

When location restrictions are configured in EF2GO, a user associated with a specific user token will only have access to the data of the location(s) to which that user is assigned.

Impact

Increased data security and improved protection of location data
Users only see information relevant to their assigned location(s)
No access to data from other locations when location restrictions are active

Action required?

No action is required if location restrictions are already configured correctly. However, it is recommended to verify that the correct locations are assigned to users (and their corresponding tokens) to prevent unintended access limitations.

In the documentation you can see which key type is needed for each endpoint, but in general a tenant token covers all read-(GET) operations, while a user token grants full access.

Authorization Scopes – Control what actions the key can perform by defining which API operations are allowed or denied.

Please note:

Once a token type is saved, you cannot change it later. If you need a different type, you must create a new key.
Once a user is linked to a user‑token, you cannot change that user. If you need to switch the user, you must create a new key.
You can only link yourself as the user to a key. If you want to create keys for multiple users, each user will need to create their own key.

Before activating your API key, make sure your configuration matches your security policies and integration setup.

With an old API key, you can still use the following endpoints:

/v1/candidate/{candidate}/link-flexworker
/v1/candidate
/v1/candidate/{id}
/v1/ats/vacancies/publications/{publicVacancyPublication}/apply
/v1/ats/applications
/v1/ats/job-boards
/v1/ats/vacancies/publications
/v1/ats/vacancies/publications/{vacancyPublicationId}/job-boards/{jobBoardId}/stats
/v1/ats/files/upload

If you were already using these endpoints, no changes are required.

However, if you want to use the new endpoints, you will need to generate a new API key.

How to access the API documentation

Our API documentation is publicly accessible and can be viewed by anyone — whether you are an API user or just exploring.

To access the documentation, simply append /docs/api to the base URL of your environment.

For example, if your environment URL is:

https://your-environment.easyflex2go.nl

then the API documentation can be found at:

https://your-environment.easyflex2go.nl/docs/api

This interface provides detailed information about available endpoints, request formats, response schemas, authentication requirements, and example requests — everything you need to get started or integrate smoothly.

Feel free to bookmark this URL for quick reference during your development process.

Testing the API

Would you like to test the API in a test environment first? Please complete the order confirmation below and send it to koppelingen@easyflex.nl. Once we have processed your request, we will provide you with the required access details.

Good to know:

Test company in production:
Testing is performed using a test company within the production environment.
Shared environment:
This is a shared environment used by multiple developers. We advise against entering any sensitive personal data.
Costs:
There are no costs associated with using the test environment.
Testing over multiple days:
The environment is not refreshed or overwritten (unless done so by other testing parties). This means your data will remain available, allowing you to test over multiple days.
Access:
Access is granted by Easyflex for a period of 3 months.

Required field: from

Every API request must include a from HTTP header containing the email address of the user making the request.

This header allows us to:

Identify which system or integration is sending the request.
Provide more efficient and targeted support when issues occur.
Contact the responsible party if questions arise regarding API usage.

Requests that do not include a valid From header will be rejected with an error.

Example:

From: api@your-organisation.com
Authorization: Bearer {your-api-token}

Rate limiting

To keep the service stable and fair for everyone, there’s a limit to how many requests you can make within a certain period of time. This is called a rate limit.

When you make requests to the API, the response includes a few headers that tell you how close you are to that limit. This helps you understand your current usage and avoid temporary access blocks.

X-RateLimit-Limit — The total number of requests you’re allowed to make in the current time window.
X-RateLimit-Remaining — How many requests you still have left before you reach the limit.
X-RateLimit-Reset — The time when your limit will reset and you’ll be able to make requests again.

If you reach your limit, you’ll need to wait until the reset time before making more requests. By checking these headers, you can keep track of your usage and make sure your app continues to run smoothly.

Sorting

You can sort the results by specifying one or more fields in the sort query parameter. By default, sorting is in ascending order. To sort in descending order, prefix the field name with a minus sign (-).

Possible fields to sort by vary per endpoint and are documented accordingly.

Example:

sort=id,-created_at

This example sorts the results first by id in ascending order, then by created_at in descending order.

Filtering

You can filter the results by specifying one or more filters using the filter[$field] query parameter. Replace $field with the name of the field you want to filter on. Multiple filters can be applied simultaneously to narrow down the results.

Possible fields for filtering vary per endpoint and are documented accordingly.

Example:

filter[name]=Acme
filter[created_after]=2024-01-01

In this example, the results will be filtered to include only those with the name “Acme” and that were created after January 1, 2024.

Including related resources

The include parameter allows you to specify related resources (relations) to be included in the API response. This helps reduce the number of API calls by retrieving related data in a single request.

You can include one or more related entities by listing them as an array of strings.

Possible includes vary per endpoint and are documented accordingly.

Example:

include=locations,customers

This request will include related locations and customers data along with the primary resource in the response.

Pagination with per_page and cursor

The per_page parameter controls the maximum number of items returned in a single API response. By default, this value is set to 25, and the maximum allowed value is 50.

When combined with the cursor parameter, you can navigate through large datasets efficiently by specifying how many items you want per page and where to continue fetching results from.

Parameters:

per_page (integer):
Sets the number of items to return per page. Default is 25, maximum is 50.
cursor (string):
A cursor hash that points to the start position of the next or previous page of results.

Example:

GET /api/v1/operating-companies?per_page=15&cursor=a45bac5f

This request fetches up to 15 items starting from the position indicated by the cursor a45bac5f.

Webhooks

Webhooks allow your system to automatically receive notifications whenever specific events occur within our platform.

By registering a webhook, you can define a destination URL that we will call (via an HTTP POST request) whenever one of your subscribed events is triggered.

This enables real-time integrations — for example, to automatically update data, trigger workflows, or synchronize information across systems.

Available endpoints:

POST /api/webhooks

Register a new webhook URL and immediately link it to one or more events.
Use this to start receiving notifications for specific system events.

POST /api/webhooks/{webhook_url_id}/subscriptions

Add one or more event subscriptions to an existing webhook URL.
This lets you expand what types of events a registered webhook will receive.

PUT /api/webhooks/{webhook_url_id}

Update the webhook URL or its configuration details.
Use this when the destination endpoint changes or needs adjustment.

DELETE /api/webhooks/{webhook_url_id}/subscriptions/{subscription_id}

Remove a single event subscription from a webhook.
This keeps the webhook active for other events but stops delivery for the specified one.

DELETE /api/webhooks/{webhook_url_id}

Completely delete a webhook URL and all associated event subscriptions.
After deletion, no further event notifications will be sent to that URL.

GET /api/webhooks/{webhook_url_id}

Retrieve the details of a specific webhook configuration.
You can include related data such as its event subscriptions using the include parameter.

GET /api/webhooks/subscription-types

Get a list of all possible event types that can be subscribed to.
These correspond to the values defined in the SubscriptionType enumeration.

Usage example:

Create a webhook with your destination URL using POST /api/webhooks.
Subscribe it to the desired events using POST /api/webhooks/{webhook_url_id}/subscriptions.
Monitor and manage it using the provided GET, PUT, and DELETE endpoints.

Once webhook delivery is enabled, your endpoint will start receiving real-time event data as JSON payloads whenever subscribed events are triggered.

API response codes

he API uses standard HTTP status codes to indicate the outcome of a request. Below are common response codes you might encounter, along with example response bodies:

200 OK
The request was successful, and the requested data is returned.

Example body:

{
  "data": { /* resource data here */ }
}

400 Bad Request
The request is invalid or malformed (e.g., missing required parameters).

Example body:

{
  "error": "Invalid request parameters",
  "details": "Parameter 'id' is required."
}

403 Forbidden
You do not have permission to access the requested resource.

Example body:

{
  "error": "Access denied",
  "message": "You are not authorized to access this resource."
}

404 Not Found
The requested resource could not be found.

Example body:

{
  "error": "Resource not found",
  "message": "Operating company with ID 123 does not exist."
}

422 Unprocessable Entity
The request was well-formed, but contains semantic errors (e.g. invalid data that cannot be processed according to business rules).

Example body:

{
  "error": "Unprocessable Entity",
  "message": "Bsn must be a valid BSN."
}

429 Too Many Requests
You have exceeded your rate limit. Please wait before making more requests.

Example headers:

X-Ratelimit-Limit: 10000
X-Ratelimit-Remaining: 0
X-Ratelimit-Reset: 1750172062

Example body:

{
  "error": "Rate limit exceeded",
  "message": "You have reached the maximum number of requests allowed."
}

500 Internal Server Error
An unexpected error occurred on the server.

Example body:

{
  "error": "Internal server error",
  "message": "An unexpected error occurred. Please try again later."
}

Need help or have any questions about the API?

If you have any questions or need assistance with our API, please feel free to contact us by email at:

koppelingen@easyflex.nl

To help us support you as efficiently as possible, please include the following information in your message:

Which Easyflex client the web service and/or data service is being called for
What you are trying to achieve with the service
Which REST call you are using (if applicable)
The exact body you are sending
A description of the issues or errors you are encountering

Providing these details will allow our support team to understand your situation quickly and provide you with the best possible assistance.

We look forward to helping you!