Partner-API · v1

API-documentatie

Alles wat je nodig hebt voor de integratie. Versie 1 · Basis-URL: https://hops24.de/api/v1

OpenAPI-bestand downloaden Nog geen sleutel? Toegang aanvragen

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"
} }

Authenticatie

Stuur je sleutel bij elke aanvraag mee in de header. Zet sleutels nooit in URL’s of openbare code – voor browseraanroepen geven we je domeinen vrij.

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

Sandbox

Sleutels met hk_test_ geven vaste voorbeeldgegevens (aanbod 900001–900003), zodat je kunt integreren voordat je live gaat. Live-sleutels beginnen met hk_live_.

Antwoordformaat

Succesvolle antwoorden bevatten data (en meta met paginering bij lijsten); fouten bevatten error met code en message. Prijzen in euro als getal; ontbreekt een prijs, dan is price_on_request true.

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

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

Foutcodes

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`

Limieten & quota

Elke aanvraag telt mee voor het maandquotum. De headers X-Quota-Limit en X-Quota-Remaining tonen de stand. Is het quotum op, dan antwoordt de API met 429 – zonder extra kosten.

Pakket	Verzoeken / maand	Verzoeken / seconde
Free	1.000	2
Starter	25.000	10
Business	250.000	30
Partner	in overleg	50

Endpoints

GET `/api/v1/status`

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

Voorbeeld

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).

Recht: listings:read

Voorbeeld

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.

Recht: listings:read

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

Voorbeeld

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.

Recht: listings:read

Parameter	Type	Beschrijving
`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)

Voorbeeld

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.

Recht: listings:read

Voorbeeld

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.

Recht: availability:read

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

Voorbeeld

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.

Recht: inquiries:create

Parameter	Type	Beschrijving
`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

Voorbeeld

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.

Recht: webhooks

Voorbeeld

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.

Recht: webhooks

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

Voorbeeld

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.

Recht: webhooks

Voorbeeld

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

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

Delete a webhook.

Recht: webhooks

Voorbeeld

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).

Recht: own:listings:write | own:inquiries:read

Voorbeeld

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.

Recht: own:listings:write

Parameter	Type	Beschrijving
`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

Voorbeeld

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.

Recht: own:inquiries:read

Parameter	Type	Beschrijving
`status`	string	Filter by status

Voorbeeld

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

GET `/api/v1/me/bookings`

Your orders within a period.

Recht: own:inquiries:read

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

Voorbeeld

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.

Recht: own:calendar:write

Voorbeeld

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).

Recht: own:calendar:write

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

Voorbeeld

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.

Recht: own:calendar:write

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

Voorbeeld

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}'

Softwarepartners met veel aanbiedersaccounts: multi-accounttoegang op aanvraag in het pakket Partner.

Webhooks

Webhooks melden gebeurtenissen direct aan je server (pakket Business of hoger). We sturen een POST met JSON naar je URL; antwoord met een 2xx-status. Mislukte leveringen herhalen we na 1, 5 en 30 minuten en 2, 6 en 24 uur.

Code	Beschrijving
`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)

Handtekening controleren (secret uit 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);

Weergaveregels

Toon bij elk aanbod een link naar de url uit het antwoord. Bij Free en Starter ook ‘via HOPS24’. Gegevens maximaal 24 uur cachen en niet doorgeven. Contactgegevens van aanbieders worden bewust niet geleverd – aanvragen lopen via HOPS24.

De API-gebruiksvoorwaarden zijn van toepassing (Duits).

API-documentatie

Authenticatie

Sandbox

Antwoordformaat

Foutcodes

Limieten & quota

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

Weergaveregels

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`