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_…"
Partner API · v1
API documentation
Everything you need to integrate. Version 1 · Base URL: https://hops24.de/api/v1
Authentication
Send your key in a header with every request. Never put keys in URLs or public code – you add domains for browser calls yourself in your API account.
Authorization: Bearer hk_live_… # or X-API-Key: hk_live_…
Sandbox
Keys starting with hk_test_ return fixed sample data (listings 900001–900004), so you can integrate before going live. Live keys start with hk_live_ and return real listings from 20 Oct 2026.
Response format
Successful responses contain data (and meta with paging for lists); errors contain error with code and message. Prices as numbers in the currency given in currency (EUR; CHF in Switzerland, GBP in the United Kingdom); 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
GET /api/v1/categories
All categories with translations (de, en, es, fr, nl, it, pt).
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, GB, IE); default DE. Returns listings of providers in or serving this country |
postal_code | string | Postcode or city; respects delivery areas (venues: location of the venue) |
lat, lng | number | Coordinates; finds providers whose delivery radius covers the point and venues within 25 km |
category | string | Category key from /categories |
date | YYYY-MM-DD | Only listings available on this day |
max_price | number | Maximum “from” price in the listing currency |
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. If the provider has several identical units for the listing, a day is only unavailable once no unit is free.
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, pt (default: language of the instance) |
consent | bool | Must be true: the customer agreed to the submission |
review_consent | bool | Optional: the customer agrees to be asked once by email for a review after the date |
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-05","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, listing.updated, availability.changed, listing.removed (inquiry.replied discontinued since 2026-10-05) |
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","listing.updated"]}'
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 (in the listing currency, 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, open, booked, closed) and customer details. Since 2026-10-05 open replaces the former values waiting and answered (still accepted as filters).
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-20"],"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-20"],"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 | Discontinued since 2026-10-05 – no longer sent (providers reply directly by email) |
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: verify signature
[$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.