Idempotency keys

A timeout does not tell you whether a create succeeded. Send an Idempotency-Key header on POST /patients, POST /requests and POST /appointments, and retry with the same value: the API replays the first response rather than creating a second record.

curl -X POST https://api.clarirad.com/api/external/v1/patients \
  -H "Authorization: Bearer cr_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c9a10-5c1e-4a55-9d0b-2f8e6b1d4a77" \
  -d '{"firstName":"Ada","lastName":"Lovelace","dateOfBirth":"1990-04-12"}'

The rules

• The header is optional, and its value is 1 to 255 characters. A UUID per record works well.
• A key is remembered for 24 hours, within your tenant and that route.
• The same key with a different body is refused with 422. That is a bug in the caller, not a retry.
• If the first attempt failed, nothing is stored and you can retry with the same key.
• Concurrent duplicates wait for the first to finish, then receive its response.