Planaday Public API

Overview ¶

Last updated ¶

See the changelist at the end of this documentation for a full history of changes.

API URL ¶

Replace apitest in the example URLs with your own company code. Your company code is the same prefix used in your Planaday environment URL.

Example: if your Planaday URL is https://mycompany.planaday.nl, then your API base URL is:

https://mycompany.api.planaday.nl/v1

Example request:

GET https://mycompany.api.planaday.nl/v1/course/list?start=20260101&end=20260331

Notational Conventions ¶

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

Authentication ¶

All API requests require authentication via an API key. API keys are managed in the Planaday application under Beheer → API keys. See the support documentation for setup instructions: Handleiding Publieke API.

The API key MUST be provided in the X-Api-Key header on every request:

X-Api-Key: 5113F6314DC7A397323EA383B0D65B39CD03FC9F77F30CDA6E0C9523543DF8B8

Requests without a valid API key will receive a 401 Unauthorized response.

Consumer Identification ¶

The API uses the User-Agent header to identify your application. Always include a descriptive User-Agent so we can identify your integration in our logs when troubleshooting.

Example:

User-Agent: MyBookingWebsite/2.1 (https://www.example.nl)

HTTP Methods ¶

This API uses standard HTTP methods:

Media Type ¶

All requests and responses use JSON. Set the following headers on every request:

Content-Type: application/json
Accept: application/json

Omitting these headers may result in a 415 Unsupported Media Type error.

Representation of Date and Time ¶

All dates and times use the Europe/Amsterdam timezone.

Names in API vs Planaday ¶

Planaday’s user interface is in Dutch. The table below maps API resource names to their Dutch equivalents in the application, so you can find the right section in Planaday when configuring or troubleshooting your integration.

Status Codes and Errors ¶

The API uses standard HTTP status codes. Every response includes one of these codes to indicate the result of your request.

Success codes:

Client error codes:

Server error codes:

Note: Some endpoints also return a custom error code in the response body (e.g. "error": 402). These are internal application codes, not HTTP status codes. Refer to the error tables in each endpoint’s documentation for their meaning.

Ratelimiting ¶

The API enforces rate limits to ensure fair usage. Every response includes headers that tell you your current rate limit status:

X-RateLimit-Limit: 720000
X-RateLimit-Remaining: 719999
X-RateLimit-Reset: 1610536876

When you exceed the limit, the API returns a 503 Rate Limit Reached response. Wait until the X-RateLimit-Reset timestamp before retrying.

Best practices:

• Monitor the X-RateLimit-Remaining header to avoid hitting the limit

• Use batch endpoints (e.g. ?batch=) where available to reduce the number of calls

• Cache responses that don’t change frequently (e.g. course templates, labels, locations)

Pagination ¶

List endpoints return paginated results. The response includes two extra blocks — meta for pagination info and links for navigation URLs.

Meta block

The meta block tells you where you are in the result set and how many results exist:

{
    "meta": {
        "page": {
            "current": 1,
            "offset": 1,
            "limit": 100,
            "total": 4
        },
        "records": 393
    }
}

Example: paging through results

To fetch records 201-300, set ?offset=200&limit=100:

{
    "meta": {
        "page": {
            "current": 3,
            "offset": 200,
            "limit": 100,
            "total": 4
        },
        "records": 393
    }
}

Links block

The links block provides ready-to-use URLs for navigating between pages. Empty strings indicate no further pages in that direction.

{
    "links": {
        "self": "https://apitest.api.planaday.nl/v1/course/1/dayparts?limit=20&offset=20",
        "first": "https://apitest.api.planaday.nl/v1/course/1/dayparts?limit=20&offset=1",
        "last": "https://apitest.api.planaday.nl/v1/course/1/dayparts?limit=20&offset=40",
        "next": "https://apitest.api.planaday.nl/v1/course/1/dayparts?limit=20&offset=40",
        "previous": "https://apitest.api.planaday.nl/v1/course/1/dayparts?limit=20&offset=1"
    }
}

VAT codes ¶

Cost fields in the API include a vat (percentage) and vat_code (category). The following VAT codes are used throughout the API:

These codes appear in cost blocks for courses, dayparts, course templates, locations, materials, and vouchers.

Attribute blocks ¶

Notice: attribute blocks can only be used when a Planaday employee has enabled this feature for your account.

Attributes are configurable options attached to course templates, courses, and dayparts. They allow customers to make selections during booking — for example, choosing a course language, selecting exam options, or picking equipment variants. When attributes have prices, they can affect the total booking cost.

Attribute blocks appear in the responses of:

• Course templates (GET /coursetemplate/{id})

• Courses (GET /course/{id} and GET /course/list)

• Dayparts within courses (GET /course/{id}/dayparts and GET /daypart/{id})

Structure

Each attribute has a unique code (GUID), a list of possible values, and flags indicating whether the attribute is required, allows multiple selections, or has financial impact:

{
    "Take exam": {
        "code": "{E27A0D46-AAF1-BDB8-A667-D3C0510F0A5E}",
        "values": {
            "ja": {
                "value": "50",
                "description": "display tekst"
            },
            "nee": {
                "value": "0",
                "description": "display tekst"
            }
        },
        "is_required": false,
        "multiple_values_allowed": false,
        "is_financial": false
    }
}

Fields explained

code — The unique identifier (GUID) for this attribute. Use this code when posting attribute selections in the booking call.

values — The possible options for this attribute. Each option is keyed by its name and has a value (price component or identifier) and description (display text). Four structures are possible:

is_required — When true, this attribute must be included in the booking POST. Bookings without required attributes will be rejected with error code 424.

multiple_values_allowed — When true, the customer can select multiple options. Pass them as an array of values in the booking call. When false, only one value is allowed.

is_financial — When true, the attribute affects the booking price. The vat and vat_code fields will be included alongside the values:

{
    "Equipment": {
        "code": "{E27A0D46-AAF1-BDB8-A667-D3C0510F0A5E}",
        "values": {
            "EPT": {
                "value": null,
                "description": "Elektrische pallettruck"
            },
            "Heftruck": {
                "value": "25",
                "description": "Heftruck opleiding"
            },
            "Reachtruck": {
                "value": "50",
                "description": null
            }
        },
        "is_required": false,
        "multiple_values_allowed": false,
        "is_financial": true,
        "vat": 21,
        "vat_code": 2
    }
}

See the Booking documentation for examples of how to post attribute selections.

Booking ¶

Create, manage, and cancel course bookings (enrollments) for students. This is the core integration endpoint — use it to let students book courses from your website, portal, or external system. Bookings appear in Planaday under “Cursus → Openstaande aanvragen” where they can be reviewed and processed by staff.

Company ¶

Manage companies (bedrijven) in Planaday. Companies are organizations that enroll students for courses. They can be organized in a parent-child hierarchy (e.g. holding company → subsidiaries). Use these endpoints to synchronize company data from an external HR or CRM system.

Course ¶

Courses are scheduled instances of course templates with specific dates, locations, and availability. A course contains one or more dayparts (sessions) and can be part of an education (training program). Use these endpoints to build a course catalog, display available courses on your website, and show detailed course information before booking.

Coursetemplate ¶

A course template is the blueprint for a course. It defines the structure (number of dayparts, costs, labels, attributes) that individual course instances inherit. For example, a “BHV Herhaling” template defines a 1-day course with specific pricing — each planned instance of that course in the calendar is based on this template.

Daypart ¶

A daypart (dagdeel) is a single session within a course — for example, “Morning session: Theory” or “Day 2: Practical exam”. Each daypart has its own date, time, location, instructor, and optionally its own costs and attributes. Daypart IDs are returned by the course list and course detail endpoints.

Education ¶

An education (opleiding) is a training program that groups multiple courses together into a structured learning path. For example, an “EHBO Instructor” education might consist of a theory course, a practical course, and an exam. Use these endpoints to display available education programs and their details on your website.

Extrafields ¶

Extra fields are custom fields defined in the Planaday application. They extend the standard data model with organization-specific information (e.g. a custom “Certificate number” field for students, or a “Category” dropdown).

Extra fields are grouped by entity type (student, company, etc.) and each field has a type that determines how it should be rendered and validated.

Possible types

• textfield — single-line text input

• textarea — multi-line text input

• datefield — date picker

• checkbox — boolean on/off toggle

• radiobutton — single selection from options

• select — dropdown selection from options

Image ¶

Retrieve image files (photos, logos) associated with courses. Image IDs and URLs are returned by the course detail and course images endpoints.

Instructor ¶

Manage instructors (trainers/teachers) and their assignments to courses and dayparts. Use these endpoints to look up instructor details, list all active instructors, and programmatically schedule or unschedule instructors for specific sessions or entire courses.

Label ¶

Labels are tags that can be attached to courses, dayparts, and other entities in Planaday. They are commonly used to categorize and filter content (e.g. “BHV”, “EHBO”, “CODE95”).

Location ¶

Locations are venues where courses and dayparts take place. A location can be an internal training room, an external venue, a virtual classroom, or even a company address (for incompany courses). Location IDs are returned by the course and daypart detail endpoints.

Ping ¶

Health check endpoint to verify the API is up and running.

Student ¶

Manage student (cursist/medewerker) records in Planaday. Students are always linked to a company. Use this endpoint to synchronize employee/student data from an external HR or LMS system. The external_id field (typically the employee ID in your system) is used as the unique key for create-or-update logic.

Voucher ¶

Vouchers provide discounts on courses. They can be percentage-based or fixed-amount, optionally limited to specific course templates, and have an availability count and expiration date. Use these endpoints to validate a voucher before applying it to a booking, and to mark it as used after a successful booking.