ClickToGoo B2B API

All endpoints live under /api/v1. The machine-readable OpenAPI 3.1 spec is served live — use it to generate clients/SDKs.

Every request needs an API key. Send it as a Bearer token in the Authorization header, or in the X-API-Key header. Keys are issued by ClickToGoo (there is no self-service sign-up) — contact us to request access.

Each key carries one or more scopes; an insufficient scope returns 403, a missing/invalid key returns 401.

With an API key, create a quote, then book the vehicle-class offer you choose by sending its quoteId and offerSnapshotId. Pickup dates and times are the airport's local time (Europe/Istanbul for airports in Türkiye), at least 3 hours and at most 365 days ahead; the quote and the booking name that zone in timeZone. The full request and response schemas are in the OpenAPI spec above.

Each endpoint enforces a per-client, per-minute limit, and each client has daily and monthly quotas that reset at 00:00 UTC on each calendar day and month. Failed or unauthenticated requests count against a separate abuse limit; successfully authenticated requests do not consume that abuse budget. Exceeding an applicable limit returns 429 with a Retry-After header.

Create a quote first (POST /api/v1/quotes) — the response contains per-vehicle-class offer snapshots. Then create a booking with the chosen snapshot (POST /api/v1/bookings). You can read, cancel, or open a payment session for a booking.

POST /api/v1/bookings and POST /api/v1/webhooks require an Idempotency-Key header of 8–200 characters with no spaces. Replaying the same key with the same body returns the original resource with status 200 and X-Idempotency-Replayed: true (the first call returns 201). Reusing the key with a different body returns 409.

Events: api.quote_created, api.booking_created, api.booking_cancelled, api.booking_completed, api.booking_pickup_amended. Manage subscriptions via /api/v1/webhooks. Listing is cursor-paginated: limit defaults to 20 (maximum 100); when hasMore is true, pass nextCursor as the next cursor value.

Signing follows the Standard Webhooks spec. Each delivery carries webhook-id, webhook-timestamp and webhook-signature headers. The signature base is the string webhook-id.webhook-timestamp.<raw-json-body>; the signature is v1,<base64(hmac_sha256)> verified with your subscription secret (whsec_...).

Protect against replays: reject deliveries whose webhook-timestamp deviates more than 5 minutes from your clock (retries are re-signed with a fresh timestamp), and deduplicate on webhook-id with a window covering the full retry horizon — up to 10 attempts over roughly 76 hours (about 3.2 days) of cumulative backoff, so keep processed ids for at least 4 days. Operator replays and fanout deliveries can reuse a webhook-id beyond that schedule, so treat a remembered id as already processed.

Rotate the signing secret without downtime via POST /api/v1/webhooks/{webhookId}/rotate-secret. The new secret is returned exactly once. For 24 hours after rotation (previousSecretExpiresAt) each delivery's webhook-signature header carries two space-delimited v1 signatures — one per secret — and the delivery is authentic if either verifies. Disabling a subscription revokes the grace secret immediately.

Every error returns the same JSON shape — a stable code plus a human-readable message. 400 validation errors add a fieldErrors map keyed by field path; 429 responses add a Retry-After header (in seconds).