Idempotency

All POST (create) endpoints support the Idempotency-Key header for safe retries. This prevents duplicate resources when a request succeeds but the response is lost due to network issues.

How It Works

Include an Idempotency-Key header with a unique value (UUID recommended) on any create request:

curl -X POST \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"first_name": "Sarah", "last_name": "Johnson", "date_of_birth": "1985-03-15"}' \
  "https://api.jumpehr.com/api-v1/patients"

Behaviour

Scenario	Result
First request with this key	Processed normally, response cached
Same key + same body	Cached response returned (no new resource created)
Same key + different body	`409 CONFLICT` error
No key provided	Request processed without deduplication

Scoping

Keys are scoped to (organisation, key, endpoint) — the same key value can be safely reused across different endpoints or organisations. Keys expire after 24 hours.

Supported Endpoints

Endpoint	Description
`POST /patients`	Create a patient
`POST /appointments`	Create an appointment
`POST /episodes`	Create an episode
`POST /episodes/{id}/events`	Add an event to an episode
`POST /questionnaire-responses`	Submit a questionnaire response
`POST /appointment-templates`	Create an appointment template
`POST /pathway-rules`	Create a pathway rule
`POST /webhooks`	Create a webhook endpoint

Error Response

If you reuse a key with a different request body:

{
  "data": null,
  "meta": { "request_id": "req_abc123" },
  "error": {
    "code": "CONFLICT",
    "message": "Idempotency key already used with a different request body"
  }
}

Best Practices

Generate a new UUID for each logical operation. Do not reuse keys across unrelated requests.

Use UUIDs — crypto.randomUUID() in JavaScript, uuid.uuid4() in Python
Store the key alongside your request so you can retry with the same key if needed
Don't reuse keys across different logical operations — each create intent should have its own key
The header is optional — omit it if you don't need deduplication

Rate Limits & Errors Overview