Conventions

Idempotency

Send an Idempotency-Key on writes you may need to retry. The same key with the same body replays the stored response instead of creating a duplicate.

Semantics

The Idempotency-Key header is optional on every POST, PATCH and DELETE, except the /v1/webhooks endpoints, which ignore it. Any unique string works; UUIDs are recommended. Keys are scoped to your account and stored for about 24 hours.
Same key + same body → the stored response is replayed (same status code and body) and no duplicate resource is created. The replay is semantically identical, not byte-identical: fields that were empty objects may be omitted.
Same key + different body → 422.
No key, or a new key → the request is processed fresh.
Use it to retry safely when you never saw the response: timeouts, dropped connections.

422 Idempotency key reuse detail: "Idempotency-Key was already used with a different request body"

Example

curl

# both invocations return the same 201 and create exactly one booking
curl -X POST https://platform.getproperly.com/v1/bookings \
  -H "x-api-key: $PROPERLY_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f8a33a2-bd60-4c1e-9c11-booking-55871" \
  -d @booking.json

For API-initiated webhook events the envelope's clientRequestId echoes the key you sent, which lets you correlate fan-out deliveries with your own writes.