Skip to content

Open Beta – help us make WOHNO even better!

WOHNO

Quickstart

Create an API key and make your first authenticated WOHNO API call in under five minutes.

This quickstart takes you from zero to a successful API call in under five minutes. You will create an API key in your dashboard and use it to read your listings over https://wohno.de/api/v1.

Before you start

You need a WOHNO account and an organization. If you do not have one yet, create an account first — every API key belongs to an organization, and every call runs in that organization's context.

Two prerequisites gate API access today:

  • Closed beta — the API is in a closed beta. Your organization must be enabled for it before any key can be created (otherwise key creation returns BETA_NOT_ENABLED).
  • Integrations add-on — since the two-plan model, API access on professional no longer comes from the plan but from the "Integrations" add-on (€89/month, only bookable together with professional); without it, professional has 0 API keys and 0 monthly requests, while professional with the add-on grants 3 keys and 25,000 requests/month. The enterprise plan and existing business accounts (legacy plan) keep API access without the add-on.

Step 1 — Create an API key

  1. Open Dashboard → Settings → API at https://wohno.de/dashboard/settings.
  2. Click Create API key.
  3. Choose the key type:
    • Secret key (sk_…) — for server-to-server use. It can carry any scope (read, write, delete). Pick this for the quickstart.
    • Publishable key (pk_…) — for browser/embed use. Read-only, and it requires an origin allowlist. See the authentication guide to decide which one fits your use case.
  4. Grant the listings:read scope (enough for this quickstart).
  5. Copy the secret value now — a secret key is shown exactly once and stored only as a hash. If you lose it, create a new key.

Your key looks like sk_live_xxxxxxxxxxxxxxxxxxxxxxxx. Treat it like a password: never commit it to git and never ship it in a browser bundle.

Step 2 — Make your first call

Send a GET request to /api/v1/listings with your key in the X-API-Key header:

curl https://wohno.de/api/v1/listings \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

You should get an HTTP 200 with a JSON body. A successful response looks like this (truncated):

{
  "data": [
    {
      "id": "9f1c2a3b-...",
      "title": "Bright 2-room apartment",
      "status": "published"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6...",
    "has_more": true,
    "limit": 20
  }
}

That is it — you have made your first authenticated WOHNO API call.

Step 3 — Understand the response

  • Envelope — list endpoints wrap results in data. GET /api/v1/listings uses cursor pagination: keep passing pagination.next_cursor as the next ?cursor= while pagination.has_more is true. (Some endpoints, like GET /api/v1/organizations, use offset pagination with a meta object instead — see the conventions reference.)
  • Rate-limit headers — every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. The limit is 1000 requests per hour per key.
  • Quota headers — X-Quota-Limit, X-Quota-Used, X-Quota-Reset and X-Quota-Status report your organization's monthly usage. Quotas are enforced: exceeding your plan's monthly limit returns 429 QUOTA_EXCEEDED.
  • Errors — on failure the body is { "error": { "code", "message", "status" } }. Always branch on the stable code, not the message text.
  • Before the marketplace launch — the marketplace-facing data endpoints (listings reads, discovery, applications, appointment create/update/cancel/book, matching) return 403 LAUNCH_PENDING until the public launch. The non-marketplace endpoints (webhooks, members, usage, WBS, listings write, and reading or deleting your keys) are not launch-gated — key creation still needs the closed-beta opt-in noted above — so the GET /api/v1/listings call above may return 403 LAUNCH_PENDING in the pre-launch phase.

Try another endpoint

Listing your organizations works the same way (offset pagination here):

curl "https://wohno.de/api/v1/organizations?page=1&per_page=20" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Next steps

  • Authentication guide — key types, scopes, origin allowlists, rotation and auth errors.
  • API Reference — the full, interactive endpoint reference.
  • Use-case guides — end-to-end walkthroughs for common integrations.