Developer guide

Idempotency

Retry a write safely, and what a replayed enrollment returns.

Never send patient information to a sandbox key.

On this deployment: Headless Connect API: Not available in this environment

Headless Connect API: Not available in this environment. What runs now: Sandbox-key calls to /api/v1 on the nonproduction deployment with synthetic data: claims scan, formulary, rulebook, the sandbox order preview, delivery reads and replay, and the MCP endpoint, on a deployment whose database has the 20261101090000-range migrations applied (a hard deploy-order dependency the merge gate enforces; ahead of them the rulebook, claims scan, MCP and replay answer 503).

The Idempotency-Key header

Every write needs an Idempotency-Key of 16 to 255 characters. Generate a new one (a UUID works) for each operation you mean, store it with your own record before you send, and reuse it only to retry that same operation.

What a key's reuse returns
You send	You get
The same key and the same body within 24 hours	The original answer, applied once.
The same key with a different body	`409 idempotency_conflict`. Nothing is applied.
The same key while the first request is still running	`409 idempotency_in_progress` with `Retry-After`. Nothing is applied twice.
No key, or one of the wrong length	`400 idempotency_key_required`.
A key the record could not be checked for	`503 idempotency_unavailable`. Nothing was processed; retry with the same key.

The key is reserved before the request runs, so two concurrent requests with one key cannot both apply.

Replaying POST /enrollments

A replay of an enrollment returns the same enrollment id with a freshly minted launch link and meta.replayed: true. The earlier link stays valid until it expires or is used, because a launch link is single use and the answer that carried it may never have reached you. If the enrollment has since closed, the replay answers 409 enrollment_closed: start a new one with a new key. If the person has already started intake, it answers 409 enrollment_link_unavailable, whatever the enrollment's state: they continue by signing in on your care host.