Documentação da API

GET /api/v1/status

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

Exemplo

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

GET /api/v1/categories

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

Escopo: listings:read

Exemplo

curl "https://hops24.net/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.

Escopo: listings:read

Exemplo

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

GET /api/v1/listings

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

Escopo: listings:read

Exemplo

curl "https://hops24.net/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.

Escopo: listings:read

Exemplo

curl "https://hops24.net/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.

Escopo: availability:read

Exemplo

curl "https://hops24.net/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.

Escopo: inquiries:create

Exemplo

curl -X POST "https://hops24.net/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-08","message":"Kindergeburtstag, 15 Kinder","consent":true}'

GET /api/v1/webhooks

Your webhooks with delivery status.

Escopo: webhooks

Exemplo

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

POST /api/v1/webhooks

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

Escopo: webhooks

Exemplo

curl -X POST "https://hops24.net/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.

Escopo: webhooks

Exemplo

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

DELETE /api/v1/webhooks/{id}

Delete a webhook.

Escopo: webhooks

Exemplo

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

GET /api/v1/me/listings

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

Escopo: own:listings:write | own:inquiries:read | own:listings:sync

Exemplo

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

POST /api/v1/me/listings/sync

Create and sync your own listings from your software (free on all plans, one call counts once). Matched by external_ref (SKU): create, update, and with mode full take listings no longer sent offline – never deleted. Only fields you send are changed. New listings go online once the minimum details are met (otherwise draft, see problems), unless active: false. Photos are loaded by URL (once per address, max. 5 per listing, 200 new per day). The Idempotency-Key header is required. More than 200 listings: send mode full in parts, pass sync_session from the first response and set complete: true in the last part.

Escopo: own:listings:sync

Exemplo

curl -X POST "https://hops24.net/api/v1/me/listings/sync" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Idempotency-Key: example-request-001" \
  -H "Content-Type: application/json" \
  -d '{"mode":"full","listings":[{"external_ref":"HB-001","title":"Piraten-Hüpfburg XXL","category":"huepfburgen","city":"Berlin","description":"Große Piraten-Hüpfburg mit Rutsche und Netzen, ideal für Geburtstage und Sommerfeste.","prices":{"from":199,"weekend":299,"delivery":35},"images":["https://www.example.com/bilder/piraten-1.jpg"],"active":true}]}'

PUT /api/v1/me/listings/by-ref/{external_ref}

Create or update one listing by its reference (same fields as an entry of /me/listings/sync). Returns 201 when created, otherwise 200, with ETag. If-Match is optional; when set and the listing has changed meanwhile, 412 follows.

Escopo: own:listings:sync

Exemplo

curl -X PUT "https://hops24.net/api/v1/me/listings/by-ref/HB-001" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Piraten-Hüpfburg XXL","prices":{"from":189},"active":true}'

GET /api/v1/me/sync/runs

The last 20 syncs of this connection with counts and notes (codes per external_ref). Reports are kept for 90 days.

Escopo: own:listings:sync

Exemplo

curl "https://hops24.net/api/v1/me/sync/runs" \
  -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.

Escopo: own:listings:write

Exemplo

curl -X PATCH "https://hops24.net/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).

Escopo: own:inquiries:read

Exemplo

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

GET /api/v1/me/bookings

Your orders within a period.

Escopo: own:inquiries:read

Exemplo

curl "https://hops24.net/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.

Escopo: own:calendar:write

Exemplo

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

POST /api/v1/me/blocked-dates

Block days (for one listing or all).

Escopo: own:calendar:write

Exemplo

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

DELETE /api/v1/me/blocked-dates

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

Escopo: own:calendar:write

Exemplo

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