Partner-API · v1

API documentation

Everything you need to integrate. Version 1 · Base URL: https://hops24.de/api/v1

Download OpenAPI file No key yet? Request access

GET /api/v1/listings/900001
Authorization: Bearer hk_test_…

{ "data": {
    "id": 900001,
    "title": "Sandbox: Hüpfburg Ritterburg 4×4 m",
    "category": "huepfburgen",
    "prices": { "from": 89, "delivery": 25 },
    "url": "https://hops24.de/…",
    "attribution": "via HOPS24"
} }

Authentication

Send your key in a header with every request. Never put keys in URLs or public code – for browser calls we whitelist your domains.

Authorization: Bearer hk_live_…
# or
X-API-Key: hk_live_…

Sandbox

Keys starting with hk_test_ return fixed sample data (listings 900001–900003), so you can integrate before going live. Live keys start with hk_live_.

Response format

Successful responses contain data (and meta with paging for lists); errors contain error with code and message. Prices in euros as numbers; if missing, price_on_request is true.

{ "data": [ … ], "meta": { "page": 1, "per_page": 20, "total": 14, "pages": 1 } }

{ "error": { "code": "quota_exceeded", "message": "…" } }

Error codes

HTTP	Code
400	`invalid_parameter`
401	`unauthorized`
403	`insufficient_scope · no_provider_account · provider_approval_required · origin_not_allowed · client_suspended`
404	`not_found`
409	`idempotency_conflict`
412	`version_conflict`
428	`precondition_required`
429	`rate_limited · quota_exceeded`
503	`temporarily_unavailable`
500	`server_error`

Limits & quotas

Every request counts towards the monthly quota. The X-Quota-Limit and X-Quota-Remaining headers show your status. When the quota is used up, the API responds with 429 – no extra charges.

Plan	Requests / month	Requests / second
Free	1.000	2
Starter	25.000	10
Business	250.000	30
Partner	by agreement	50

Endpoints

GET `/api/v1/status`

Checks the key and shows plan, scopes and usage for the current month.

Example

curl "https://hops24.de/api/v1/status" \
  -H "Authorization: Bearer hk_test_…"

GET `/api/v1/categories`

All categories with translations (de, en, es, fr, nl, it).

Scope: listings:read

Example

curl "https://hops24.de/api/v1/categories" \
  -H "Authorization: Bearer hk_test_…"

GET `/api/v1/changes`

Public changes and removals after a cursor. Poll about every 60 seconds; reload details. Events are kept for 90 days – if your cursor is older, meta.resync_required asks for a full resync.

Scope: listings:read

Parameter	Type	Description
`after`	int	Last processed change ID, initially 0
`limit`	int	Up to 200 changes

Example

curl "https://hops24.de/api/v1/changes" \
  -H "Authorization: Bearer hk_test_…"

GET `/api/v1/listings`

Search public listings. Same logic as the search on hops24.de.

Scope: listings:read

Parameter	Type	Description
`q`	string	Free text (title, city, description)
`country`	string	Country (DE, AT, CH, FR, BE, LU, NL, ES, IT); default DE. Returns listings of providers in or serving this country
`postal_code`	string	Postcode or city; respects delivery areas
`lat, lng`	number	Coordinates; finds providers whose delivery radius covers the point
`category`	string	Category key from /categories
`date`	YYYY-MM-DD	Only listings available on this day
`max_price`	number	Maximum “from” price in euros
`placement`	1	Only listings offering long-term placement
`self_pickup`	1	Only with self pickup
`sort`	string	newest (default), price, distance (requires lat/lng)
`page, per_page`	int	Page (from 1) and results per page (1–50, default 20)

Example

curl "https://hops24.de/api/v1/listings?category=huepfburgen&postal_code=33100&sort=price" \
  -H "Authorization: Bearer hk_test_…"

GET `/api/v1/listings/{id}`

Listing details incl. description, all images and technical details.

Scope: listings:read

Example

curl "https://hops24.de/api/v1/listings/900001" \
  -H "Authorization: Bearer hk_test_…"

GET `/api/v1/listings/{id}/availability`

Unavailable days of a listing from today.

Scope: availability:read

Parameter	Type	Description
`months`	int	Period in months (1–12, default 3)

Example

curl "https://hops24.de/api/v1/listings/900001/availability?months=3" \
  -H "Authorization: Bearer hk_test_…"

POST `/api/v1/inquiries`

Submit a customer enquiry to the provider. It arrives in the provider’s HOPS24 inbox; the customer receives a confirmation. Returns 201. The Idempotency-Key header is required (also in the sandbox): retries with the same key return the same response for 30 days.

Scope: inquiries:create

Parameter	Type	Description
`listing_id`	int	Listing (required)
`name, email`	string	Customer name and email (required)
`event_date`	YYYY-MM-DD	Requested date or placement start (required)
`event_end_date`	YYYY-MM-DD	End date for multi-day events
`request_type`	string	event (default) or placement (only if placement_available)
`placement_location`	string	Placement location (required for placement)
`phone, message`	string	Optional
`lang`	string	Language of the confirmation email to the customer: de, en, es, fr, nl, it (default de)
`consent`	bool	Must be true: the customer agreed to the submission

Example

curl -X POST "https://hops24.de/api/v1/inquiries" \
  -H "Authorization: Bearer hk_test_…" \
  -H "Idempotency-Key: example-request-001" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":900001,"name":"Erika Muster","email":"erika@example.de","event_date":"2026-11-02","message":"Kindergeburtstag, 15 Kinder","consent":true}'

GET `/api/v1/webhooks`

Your webhooks with delivery status.

Scope: webhooks

Example

curl "https://hops24.de/api/v1/webhooks" \
  -H "Authorization: Bearer hk_live_…"

POST `/api/v1/webhooks`

Create a webhook. The signing secret is only shown in this response.

Scope: webhooks

Parameter	Type	Description
`url`	string	Target URL (https only, publicly reachable)
`events`	array	inquiry.created, inquiry.replied

Example

curl -X POST "https://hops24.de/api/v1/webhooks" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://partner.de/hops24-webhook","events":["inquiry.created","inquiry.replied"]}'

POST `/api/v1/webhooks/{id}/test`

Send a webhook.test event.

Scope: webhooks

Example

curl -X POST "https://hops24.de/api/v1/webhooks/7/test" \
  -H "Authorization: Bearer hk_live_…"

DELETE `/api/v1/webhooks/{id}`

Delete a webhook.

Scope: webhooks

Example

curl -X DELETE "https://hops24.de/api/v1/webhooks/7" \
  -H "Authorization: Bearer hk_live_…"

GET `/api/v1/me/listings`

Provider integration: your own listings incl. inactive ones (key must be linked to a provider account).

Scope: own:listings:write | own:inquiries:read

Example

curl "https://hops24.de/api/v1/me/listings" \
  -H "Authorization: Bearer hk_live_…"

PATCH `/api/v1/me/listings/{id}`

Update your own listing using If-Match (version from GET /me/listings). Provider approval required. Activation requires the same minimum details as in the dashboard.

Scope: own:listings:write

Parameter	Type	Description
`title, description`	string	Title (3–150 chars), description
`prices`	object	from, daily, weekend, delivery, setup, deposit, placement_monthly, hourly (euros, null clears; hourly only for services)
`is_active`	bool	Activate/deactivate the listing

Example

curl -X PATCH "https://hops24.de/api/v1/me/listings/123" \
  -H "Authorization: Bearer hk_live_…" \
  -H 'If-Match: "VERSION_FROM_GET_ME_LISTINGS"' \
  -H "Content-Type: application/json" \
  -d '{"prices":{"from":99,"weekend":149},"is_active":true}'

GET `/api/v1/me/inquiries`

Your enquiries with status (new, waiting, answered, booked, closed) and customer details.

Scope: own:inquiries:read

Parameter	Type	Description
`status`	string	Filter by status

Example

curl "https://hops24.de/api/v1/me/inquiries" \
  -H "Authorization: Bearer hk_live_…"

GET `/api/v1/me/bookings`

Your orders within a period.

Scope: own:inquiries:read

Parameter	Type	Description
`from, to`	YYYY-MM-DD	Period (default: today to +12 months)

Example

curl "https://hops24.de/api/v1/me/bookings" \
  -H "Authorization: Bearer hk_live_…"

GET `/api/v1/me/blocked-dates`

Blocked days from today with source (manual, calendar_import, api) and deletable.

Scope: own:calendar:write

Example

curl "https://hops24.de/api/v1/me/blocked-dates" \
  -H "Authorization: Bearer hk_live_…"

POST `/api/v1/me/blocked-dates`

Block days (for one listing or all).

Scope: own:calendar:write

Parameter	Type	Description
`dates`	array	List of dates YYYY-MM-DD (max. 366)
`listing_id`	int	Optional; omitted = all listings
`reason`	string	Optional reason

Example

curl -X POST "https://hops24.de/api/v1/me/blocked-dates" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"dates":["2026-10-17"],"listing_id":123,"reason":"Wartung"}'

DELETE `/api/v1/me/blocked-dates`

Release only API blocks created by this connection; manual and imported blocks stay.

Scope: own:calendar:write

Parameter	Type	Description
`dates`	array	List of dates YYYY-MM-DD
`listing_id`	int	Optional

Example

curl -X DELETE "https://hops24.de/api/v1/me/blocked-dates" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"dates":["2026-10-17"],"listing_id":123}'

Software partners with many provider accounts: multi-account access on request in the Partner plan.

Webhooks

Webhooks notify your server about events instantly (Business plan or higher). We send a POST with JSON to your URL; respond with a 2xx status. Failed deliveries are retried after 1, 5 and 30 minutes and 2, 6 and 24 hours.

Code	Description
`listing.updated`	Public listing changed
`availability.changed`	Availability changed
`listing.removed`	Remove listing from partner feed
`inquiry.created`	New customer enquiry for the linked provider account
`inquiry.replied`	Provider replied to an enquiry you submitted (without content)
`webhook.test`	Test event (triggered manually)

Verify the signature (secret from POST /webhooks)

POST https://partner.de/hops24-webhook
X-HOPS24-Event: inquiry.created
X-HOPS24-Signature: t=1760000000,v1=5f2c…

{ "id": 812, "event": "inquiry.created", "created_at": "2026-10-02T18:00:00+00:00",
  "data": { "inquiry_id": 4711, "listing_id": 123, "event_date": "2026-11-01", "source": "website" } }

// PHP: Signatur prüfen
[$t, $v1] = sscanf($_SERVER['HTTP_X_HOPS24_SIGNATURE'], 't=%d,v1=%s');
$body = file_get_contents('php://input');
$ok = abs(time() - $t) < 300
   && hash_equals(hash_hmac('sha256', $t . '.' . $body, $secret), $v1);

Display rules

Show a link to the url from the response for every listing. On Free and Starter also show “via HOPS24”. Cache data for at most 24 hours and do not pass it on. Provider contact details are intentionally not provided – enquiries go through HOPS24.

The API terms of use apply (German).

API documentation

Authentication

Sandbox

Response format

Error codes

Limits & quotas

Endpoints

GET /api/v1/status

GET /api/v1/categories

GET /api/v1/changes

GET /api/v1/listings

GET /api/v1/listings/{id}

GET /api/v1/listings/{id}/availability

POST /api/v1/inquiries

GET /api/v1/webhooks

POST /api/v1/webhooks

POST /api/v1/webhooks/{id}/test

DELETE /api/v1/webhooks/{id}

GET /api/v1/me/listings

PATCH /api/v1/me/listings/{id}

GET /api/v1/me/inquiries

GET /api/v1/me/bookings

GET /api/v1/me/blocked-dates

POST /api/v1/me/blocked-dates

DELETE /api/v1/me/blocked-dates

Webhooks

Display rules

GET `/api/v1/status`

GET `/api/v1/categories`

GET `/api/v1/changes`

GET `/api/v1/listings`

GET `/api/v1/listings/{id}`

GET `/api/v1/listings/{id}/availability`

POST `/api/v1/inquiries`

GET `/api/v1/webhooks`

POST `/api/v1/webhooks`

POST `/api/v1/webhooks/{id}/test`

DELETE `/api/v1/webhooks/{id}`

GET `/api/v1/me/listings`

PATCH `/api/v1/me/listings/{id}`

GET `/api/v1/me/inquiries`

GET `/api/v1/me/bookings`

GET `/api/v1/me/blocked-dates`

POST `/api/v1/me/blocked-dates`

DELETE `/api/v1/me/blocked-dates`