Offers

Offers are the core resource of the Ferienpass API. Each offer represents an activity in the holiday programme — a course, excursion, workshop, or similar event run by a host organization.

The offer model

Properties

Properties marked authenticated only are only included in responses when using a personal access token.

Name
name
Type
string
Description
The name of the offer.
Name
alias
Type
string
Description
A unique, URL-friendly slug for the offer, typically in the format {id}-{name}.
Name
description
Type
string
Description
A full description of the activity. May contain HTML.
Name
requiresApplication
Type
boolean
Description
Whether participants need to apply for this offer.
Name
onlineApplication
Type
boolean
Description
Whether online registration is enabled. Only relevant when requiresApplication is true.
Name
applicationDeadline
Type
datetime
Description
The deadline for applications. null if no deadline is set. Timezone: Europe/Berlin.
Name
minAge
Type
integer
Description
Minimum participant age in years. null if no minimum is set.
Name
maxAge
Type
integer
Description
Maximum participant age in years. null if no maximum is set.
Name
fee
Type
integer
Description
Participation fee in euro cents. For example, 500 means €5.00. null if free.
Name
meetingPoint
Type
string
Description
The address or description of where participants should meet. null if not set.
Name
applyText
Type
string
Description
Additional text shown during the registration process. null if not set.
Name
bring
Type
string
Description
What participants should bring to the activity. null if not set.
Name
dates
Type
array
Description
An array of date objects representing the scheduled sessions of this offer. Each object has begin and end datetime strings (ISO 8601, timezone: Europe/Berlin).
Name
accessibility
Type
array
Description
Accessibility features of the offer. null if not specified.
Name
wheelchairAccessible
Type
boolean
Description
Whether the offer is wheelchair accessible. null if not specified.
Name
url
Type
string
Description
The full URL to this offer on the Ferienpass frontend website.
Name
media
Type
array
Description
An array of absolute image URLs for this offer. Images are served at a maximum size of 3000×3000 pixels.
Name
hosts
Type
array
Description
An array of host objects. Each host has a name field with the organization's name.
Name
id
Type
integer
Access
authenticated only
Description
The internal numeric ID of the offer.
Name
createdAt
Type
datetime
Access
authenticated only
Description
Timestamp of when the offer was created (ISO 8601).
Name
modifiedAt
Type
datetime
Access
authenticated only
Description
Timestamp of when the offer was last modified (ISO 8601).
Name
status
Type
object
Access
authenticated only
Description
The current workflow state of the offer as a JSON object. Keys are state names (e.g. published, draft, cancelled), values are timestamps of when the state was entered.
Name
minParticipants
Type
integer
Access
authenticated only
Description
Minimum number of participants required to run the offer. null if not set.
Name
maxParticipants
Type
integer
Access
authenticated only
Description
Maximum number of participants accepted. null if no limit.
Name
edition
Type
object
Access
authenticated only
Description
The edition (holiday programme) this offer belongs to. Contains a name field.

GET/api/offers

List all offers

Returns a paginated list of offers. Without authentication, only published offers from active editions are returned. Authenticated host users receive offers from their own organization.

Results are paginated — see the pagination guide for details.

Filters

Name
edition.id
Type
integer
Description
Filter by the numeric edition ID. Strategy: exact match.
Name
edition.alias
Type
string
Description
Filter by the edition's alias (slug). Strategy: exact match.
Name
edition.name
Type
string
Description
Filter by the edition's name. Strategy: partial match.
Name
hosts.alias
Type
string
Description
Filter by a host's alias. Strategy: exact match.
Name
hosts.name
Type
string
Description
Filter by a host's name. Strategy: partial match.
Name
fee[lte]
Type
integer
Description
Filter offers with a fee less than or equal to the given value (in cents).
Name
fee[gte]
Type
integer
Description
Filter offers with a fee greater than or equal to the given value (in cents).
Name
fee[lt]
Type
integer
Description
Filter offers with a fee strictly less than the given value (in cents).
Name
fee[gt]
Type
integer
Description
Filter offers with a fee strictly greater than the given value (in cents).
Name
fee[between]
Type
string
Description
Filter offers with a fee in a range, e.g. 0..500.
Name
meetingPoint
Type
string
Description
Filter by meeting point. Strategy: partial match.
Name
dates.begin[after]
Type
date
Description
Filter offers that have a session starting on or after the given date (e.g. 2024-07-01).
Name
dates.begin[before]
Type
date
Description
Filter offers that have a session starting on or before the given date.
Name
dates.begin[strictly_after]
Type
date
Description
Filter offers that have a session starting strictly after the given date.
Name
dates.begin[strictly_before]
Type
date
Description
Filter offers that have a session starting strictly before the given date.

Request

GET

/api/offers

curl https://ferienpass-musterstadt.de/api/offers

Response

[
  {
    "name": "Fahrradtour durch den Stadtpark",
    "alias": "42-fahrradtour-durch-den-stadtpark",
    "description": "Eine geführte Fahrradtour durch den Stadtpark für Kinder ab 8 Jahren.",
    "requiresApplication": true,
    "onlineApplication": true,
    "applicationDeadline": "2024-06-30T00:00:00+02:00",
    "minAge": 8,
    "maxAge": 14,
    "fee": 500,
    "meetingPoint": "Haupteingang Stadtpark, Parkstraße 1",
    "applyText": null,
    "bring": "Fahrrad und Helm",
    "dates": [
      {
        "begin": "2024-07-10T09:00:00+02:00",
        "end": "2024-07-10T12:00:00+02:00"
      }
    ],
    "accessibility": null,
    "wheelchairAccessible": false,
    "url": "https://ferienpass-musterstadt.de/angebote/sommer-2024/42-fahrradtour-durch-den-stadtpark",
    "media": [
      "https://ferienpass-musterstadt.de/assets/images/fahrradtour_abc123.jpg"
    ],
    "hosts": [
      { "name": "Stadtjugendring Musterstadt e.V." }
    ]
  }
]

Filter examples

Filter by edition alias to get all offers for a specific holiday programme.

Filter by edition

curl "https://ferienpass-musterstadt.de/api/offers?edition.alias=sommerferienprogramm-2024"

Filter by date range to find offers with sessions in July 2024.

Filter by date range

curl "https://ferienpass-musterstadt.de/api/offers?dates.begin%5Bafter%5D=2024-07-01&dates.begin%5Bbefore%5D=2024-07-31"

Filter by fee to find free offers (fee of 0 cents).

Filter free offers

curl "https://ferienpass-musterstadt.de/api/offers?fee%5Blte%5D=0"

GET/api/offers/:id

Retrieve an offer

Retrieve a single offer by its numeric ID. The same access rules apply as for the collection endpoint — unauthenticated users can only access published offers.

Request

GET

/api/offers/42

curl https://ferienpass-musterstadt.de/api/offers/42

Response

{
  "name": "Fahrradtour durch den Stadtpark",
  "alias": "42-fahrradtour-durch-den-stadtpark",
  "description": "Eine geführte Fahrradtour durch den Stadtpark für Kinder ab 8 Jahren.",
  "requiresApplication": true,
  "onlineApplication": true,
  "applicationDeadline": "2024-06-30T00:00:00+02:00",
  "minAge": 8,
  "maxAge": 14,
  "fee": 500,
  "meetingPoint": "Haupteingang Stadtpark, Parkstraße 1",
  "applyText": null,
  "bring": "Fahrrad und Helm",
  "dates": [
    {
      "begin": "2024-07-10T09:00:00+02:00",
      "end": "2024-07-10T12:00:00+02:00"
    }
  ],
  "accessibility": null,
  "wheelchairAccessible": false,
  "url": "https://ferienpass-musterstadt.de/angebote/sommer-2024/42-fahrradtour-durch-den-stadtpark",
  "media": [
    "https://ferienpass-musterstadt.de/assets/images/fahrradtour_abc123.jpg"
  ],
  "hosts": [
    { "name": "Stadtjugendring Musterstadt e.V." }
  ]
}