API resources

Access code lists

An access code list (Zugangscodes in the admin) holds codes that families redeem for their children. An application phase of an edition can require a list: during that phase, only participants who redeemed a code of the list may apply. Use it for a programme that is open to a group of families only, such as the children of a school or of a company's staff.

All access code list endpoints need ROLE_SUPER_ADMIN, reading included: the codes are what keeps the programme closed. In the admin, the lists are kept under Einstellungen → Anmeldung → Zugangscodes.

How codes are used

You create a list and hand out its codes, for example one per family.
In the admin, you pick the list for an application phase: open the edition's Zeiträume, and on the application phase (Anmeldung) choose it under Anmeldung nur mit Zugangscode. The API can't attach a list to a phase, since it doesn't manage phases.
Families enter a code for each child on the website, exactly as it is listed, upper and lower case included. The code is then linked to that participant, and counts as used once.
During the phase, only participants with a code of the list can apply. Everyone else is told they need an access code.

max decides how many participants can redeem the same code: 1 makes every code single-use, 0 lets a code be used any number of times.

The access code list model

Name
uuid
Type
string
Description
The list's identifier.
Name
name
Type
string
Description
The name, which helps you find the list again, such as Osterferienpass.
Name
max
Type
integer
Description
How many participants can redeem each code. 0 means no limit.
Name
codes
Type
string[]
Description
The codes of the list.
Name
createdAt
Type
timestamp
Description
When the list was created.

GET/access-code-lists

List all access code lists

Returns a page of access code lists, ordered by name.

Optional filters

Name
q
Type
string
Description
Only lists whose name contains this text.
Name
page, itemsPerPage
Type
integer
Description
See Pagination.

Request

GET·/access-code-lists

curl "https://ferienpass-musterstadt.de/api/access-code-lists?q=oster" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Response

[
  {
    "uuid": "0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31",
    "name": "Osterferienpass Grundschule Nord",
    "max": 1,
    "codes": ["NORD-4821", "NORD-7735", "NORD-9150"],
    "createdAt": "2026-09-14T09:00:00+02:00"
  }
]

GET/access-code-lists/{uuid}

Retrieve an access code list

Returns one access code list with all its codes.

Request

GET·/access-code-lists/{uuid}

curl https://ferienpass-musterstadt.de/api/access-code-lists/0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/access-code-lists

Create an access code list

Creates an access code list. Super admins only. To put it to use, pick it for an application phase in the admin (see How codes are used).

Every code is trimmed. A blank code, or a code that is in the list twice, is a 422. Codes that differ only in upper and lower case count as the same code.

Required attributes

Name
name
Type
string
Description
The name, up to 255 characters.

Optional attributes

Name
max
Type
integer
Description
How many participants can redeem each code: 0 or more, where 0 means no limit. Defaults to 1.
Name
codes
Type
string[]
Description
The codes, up to 255 characters each. Defaults to none.

Request

POST·/access-code-lists

curl -X POST https://ferienpass-musterstadt.de/api/access-code-lists \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Osterferienpass Grundschule Nord",
    "codes": ["NORD-4821", "NORD-7735", "NORD-9150"]
  }'

Response (201 Created)

{
  "uuid": "0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31",
  "name": "Osterferienpass Grundschule Nord",
  "max": 1,
  "codes": ["NORD-4821", "NORD-7735", "NORD-9150"],
  "createdAt": "2026-09-14T09:00:00+02:00"
}

PATCH/access-code-lists/{uuid}

Update an access code list

Changes an access code list. Super admins only. The attributes and their rules are the same as for creating a list; send only what you want to change. An empty body is a 422.

codes replaces the whole list. To add a code, send the codes you have plus the new one:

A code that is still in the list keeps its uses: the participants who redeemed it keep it. A code sent in different upper and lower case is the same code with a new spelling.
A code that is no longer in the list is deleted. Participants who redeemed it lose it, and can't apply in a phase that requires the list until they redeem another code.
"codes": [] (or null) deletes every code.

Lowering max doesn't take codes away from participants who redeemed them already; it only stops further uses.

Request

PATCH·/access-code-lists/{uuid}

curl -X PATCH https://ferienpass-musterstadt.de/api/access-code-lists/0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31 \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"codes": ["NORD-4821", "NORD-7735", "NORD-9150", "NORD-2264"]}'

Response

{
  "uuid": "0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31",
  "name": "Osterferienpass Grundschule Nord",
  "max": 1,
  "codes": ["NORD-4821", "NORD-7735", "NORD-9150", "NORD-2264"],
  "createdAt": "2026-09-14T09:00:00+02:00"
}

DELETE/access-code-lists/{uuid}

Delete an access code list

Deletes an access code list with all its codes. Super admins only. Responds with 204 No Content.

While an application phase requires the list, it can't be deleted (409): deleting it would open the phase to everyone. The message names the editions. Pick another list, or none, for those phases in the admin first.

Participants who redeemed a code of the list lose it.

Request

DELETE·/access-code-lists/{uuid}

curl -X DELETE https://ferienpass-musterstadt.de/api/access-code-lists/0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31 \
  -H "Authorization: Bearer $FEPLI_TOKEN"