The Qouh API

Getting started

1. Make a key under Setup → Integrations (on Starter, Pro and during the trial). Keys start with qh_ and are shown once.
2. Test it: GET /v1/me answers with your organization’s name.
3. Build on the reference below, or connect Zapier without writing code.

curl "https://qouh.com/api/v1/me" \
  -H "Authorization: Bearer $ROUTE_TRIM_KEY"

Keys and permissions

Send the key in the Authorization: Bearer header of every request, over https. A key can do only what you allowed when you made it:

• bookings:read: See bookings and free times
• bookings:write: Make, move and cancel bookings
• customers:read: See customers
• customers:write: Add and update customers
• webhooks:manage: Set up webhooks (for Zapier)

Each key may make 120 requests a minute; beyond that the API answers 429 with a Retry-After header. A key you revoke on the Integrations page stops working at once.

Times and pages

Times are ISO 8601 in UTC. Lists come a page at a time: pass the answer’s nextCursor as cursor until it is null.

Errors

An error answers with an HTTP status and a body holding a stable code and a readable message:

{
  "error": {
    "code": "slot_unavailable",
    "message": "This time is not offered (any more). Pick one from GET /v1/slots."
  }
}

• 400 The query or body is not valid (invalid_request).
• 401 No key, or a key that is not valid or was revoked (unauthorized).
• 403 The plan has no API (plan_required) or the key lacks the permission (insufficient_scope).
• 404 Not found, or it belongs to another organization (not_found).
• 409 The time is not offered (slot_unavailable), the booking is cancelled or has started (not_changeable), another customer has the email (email_taken), the webhook limit is reached (limit_reached), or a request with this Idempotency-Key is still running (idempotency_in_progress).
• 422 The address could not be found (address_not_found), or the Idempotency-Key was used for another request (idempotency_key_reused).
• 429 More than 120 requests a minute with this key (rate_limited); see Retry-After.
• 503 Address lookup or routing is unavailable for a moment (unavailable).

Retrying safely

Writes take an optional Idempotency-Key header (a UUID, for example). The same key sent again within 24 hours gets the first answer back, marked Idempotent-Replayed: true, so a retry never books twice.

Webhooks

Add an endpoint under Setup → Integrations, or subscribe through the API, to hear about bookings and customers as they change. Each event is POSTed as JSON with these headers. A failed delivery is tried again for about a day; an endpoint that keeps failing for 3 days is turned off and the owners are emailed.

Check the signature (Standard Webhooks) before trusting an event, refuse timestamps more than 5 minutes off, and use webhook-id to skip repeats. In Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto'

// secret: the whsec_… shown when you added the endpoint
// rawBody: the request body exactly as received, before parsing
function verify(secret, headers, rawBody) {
  const id = headers['webhook-id']
  const timestamp = headers['webhook-timestamp']
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const key = Buffer.from(secret.slice('whsec_'.length), 'base64')
  const expected = Buffer.from(
    createHmac('sha256', key).update(id + '.' + timestamp + '.' + rawBody).digest('base64'),
  )
  return headers['webhook-signature'].split(' ').some((part) => {
    const given = Buffer.from(part.slice('v1,'.length))
    return part.startsWith('v1,') && given.length === expected.length && timingSafeEqual(given, expected)
  })
}

Zapier

Our Zapier app is private for now: ask us for an invitation on the contact page. Connect it with a “Full access” key. Zaps can start when a booking is made, changed or cancelled or a customer is added, and can add or update a customer, find a customer and book the first free time.