API resources

Organisers

An organiser (Veranstalter, a host in the API) is a club, a company or a municipal department that runs offers. Organisers have contact details, a public description and a team of member accounts.

The organiser model

Name
uuid
Type
string
Description
The organiser's identifier.
Name
name
Type
string
Description
The organiser's name.
Name
alias
Type
string
Description
A URL-safe name. Accepted wherever an organiser is named, as in ?host=stadtjugendring-musterstadt.
Name
email
Type
string
Description
The public e-mail address.
Name
phone
Type
string
Description
The phone number.
Name
mobile
Type
string
Description
The mobile number.
Name
fax
Type
string
Description
The fax number.
Name
website
Type
string
Description
The website.
Name
address
Type
object
Description
The postal address, with street, postalCode, city and country (a two-letter code such as de).
Name
text
Type
string
Description
The public description of the organiser.
Name
logo
Type
string
Description
The URL of the organiser's logo.
Name
offersCount
Type
integer
Description
The number of offers of this organiser, across all editions.
Name
members
Type
reference[]
Access
admins only
Description
The accounts of the organiser's team. See Add a team member and Invitations.
Name
createdAt
Type
timestamp
Description
When the organiser was created.

GET/hosts

List all organisers

Returns a page of organisers, ordered by name. Admins see every organiser; organiser users see those they are a member of.

Optional filters

Name
q
Type
string
Description
Only organisers whose name or e-mail address contains this text.
Name
edition
Type
string
Description
Only organisers with an offer in this edition (UUID or alias).
Name
page, itemsPerPage
Type
integer
Description
See Pagination.

Request

GET·/hosts

curl "https://ferienpass-musterstadt.de/api/hosts?edition=herbstferien-2026" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Response

[
  {
    "uuid": "01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02",
    "name": "Stadtjugendring Musterstadt e.V.",
    "alias": "stadtjugendring-musterstadt",
    "email": "info@sjr-musterstadt.de",
    "phone": "0123 456780",
    "website": "https://sjr-musterstadt.de",
    "address": {
      "street": "Jugendweg 4",
      "postalCode": "12345",
      "city": "Musterstadt",
      "country": "de"
    },
    "text": "Der Stadtjugendring ist der Dachverband der Jugendverbände in Musterstadt.",
    "logo": "https://ferienpass-musterstadt.de/files/logos/sjr-musterstadt.png",
    "offersCount": 23,
    "members": [
      {
        "uuid": "0190f1e2-3a4b-7c5d-8e6f-7a8b9c0d1e15",
        "name": "Jonas Becker"
      }
    ],
    "createdAt": "2024-02-19T11:05:31+01:00"
  }
]

GET/hosts/{uuid}

Retrieve an organiser

Returns one organiser. Organiser users can retrieve only the organisers they are a member of; any other is a 404.

Request

GET·/hosts/{uuid}

curl https://ferienpass-musterstadt.de/api/hosts/01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/hosts

Create an organiser

Creates an organiser. Admins only. The alias is generated from the name.

To add team members, add their accounts or invite them by e-mail.

Required attributes

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

Optional attributes

Name
email
Type
string
Description
A valid e-mail address.
Name
phone, mobile, fax
Type
string
Description
Up to 64 characters each.
Name
website
Type
string
Description
A full URL, such as https://example.org.
Name
address
Type
object
Description
street, postalCode, city and country (two letters, defaults to de).
Name
text
Type
string
Description
The public description.

Request

POST·/hosts

curl -X POST https://ferienpass-musterstadt.de/api/hosts \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kunstschule Musterstadt",
    "email": "kontakt@kunstschule-musterstadt.de",
    "website": "https://kunstschule-musterstadt.de",
    "address": {
      "street": "Atelierstraße 7",
      "postalCode": "12345",
      "city": "Musterstadt"
    }
  }'

The response (201 Created) holds the new organiser.

PATCH/hosts/{uuid}

Update an organiser

Changes an organiser. Admins can change any organiser, organiser users their own. The attributes are the same as for creating an organiser; send only what you want to change. An empty body is a 422.

address is replaced as a whole: send all its fields, since the ones you leave out are cleared (and country falls back to de). "address": null removes the address.

Request

PATCH·/hosts/{uuid}

curl -X PATCH https://ferienpass-musterstadt.de/api/hosts/01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02 \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "0123 456789", "fax": null}'

DELETE/hosts/{uuid}

Delete an organiser

Deletes an organiser. Admins only. Responds with 204 No Content.

An organiser that still has offers can't be deleted (409). Move the offers to another organiser or delete them first.

Request

DELETE·/hosts/{uuid}

curl -X DELETE https://ferienpass-musterstadt.de/api/hosts/0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/hosts/{uuid}/add-member

Add a team member

Adds an existing account to the organiser's team straight away, as the admin does when it assigns an account to an organiser. Admins only. No invitation and no e-mail: the person simply finds the organiser in the admin the next time they sign in. The account gets ROLE_HOST if it didn't have it, just like setting hosts on the account. Responds with 200 OK and the organiser, whose members now include the account.

To ask someone who should decide for themselves, or who has no account yet, send an invitation instead.

An unknown account is a 422. An account you may not change is a 403: an admin's account needs a super admin, and accounts whose personal data is masked for you can't be changed. An account that is a member already is a 409.

Required attributes

Name
account
Type
string
Description
The account to add, by UUID or e-mail address.

Request

POST·/hosts/{uuid}/add-member

curl -X POST https://ferienpass-musterstadt.de/api/hosts/0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18/add-member \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account": "m.schneider@kunstschule-musterstadt.de"}'

Response (excerpt)

{
  "uuid": "0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18",
  "name": "Kunstschule Musterstadt",
  "members": [
    {
      "uuid": "0193c9e4-8f9a-7b0c-9d1e-2f3a4b5c6d21",
      "name": "Mira Schneider"
    }
  ],
  "…": "…"
}

POST/hosts/{uuid}/remove-member

Remove a team member

Ends an account's access to the organiser, as Zugang entfernen does in the admin. Admins only. The account leaves the team, and loses the single offers of this organiser that were shared with it (sharedOffers). Its access to other organisers stays, and so does ROLE_HOST. Nobody is notified. Responds with 200 OK and the organiser.

An unknown account is a 422, an account you may not change a 403. An account that has neither a membership nor a shared offer of this organiser is a 409.

Required attributes

Name
account
Type
string
Description
The account to remove, by UUID or e-mail address.

Request

POST·/hosts/{uuid}/remove-member

curl -X POST https://ferienpass-musterstadt.de/api/hosts/0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18/remove-member \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account": "0193c9e4-8f9a-7b0c-9d1e-2f3a4b5c6d21"}'