Requirements and synthetic reference · 2026-11-05.1
Claims-intake API requirements and reference tests
Define policy context, authority, idempotency, review and recovery for a claims-intake API. Inspect an OpenAPI contract and run 15 synthetic cases locally.
Start with a notice of loss and one receiving team.
A useful claims-intake API connects a notice to the applicable policy period, its named insured and the supporting document. Agree which system owns each identifier, how periods are selected and which team receives a pending-review item. The reference here models personal-auto intake with synthetic records. Registering a notice does not decide coverage, liability, settlement or payment.
The reference input requires lossDate, incidentType and documentRef. The request envelope supplies an acting identity, a retry key and the expected source revision. The example actor names are local fixtures, not an authentication scheme. A customer implementation must resolve the actual identity and current authority on the server for every protected operation.
Specify source context and failure behavior.
Keep insurer, policy, historical period and party identifiers distinct. Require each declared link to resolve uniquely within its scope. Record the extraction or read boundary and retain source evidence so a reviewer can determine which policy context supported the request. Agree effective-date and time-zone semantics with the domain owner; the example's date comparisons do not establish universal insurance rules.
A repeated retry key with the same input should return the original outcome. Reusing it with changed input should be an explicit conflict. A stale expected revision should stop the action rather than silently overwrite newer work. Test a source outage before mutation, an event delivery failure after mutation and safe recovery of the pending event. Assign an owner to each unresolved failure.
Keep request and review authority separate.
The synthetic suite checks revoked access, cross-scope access, missing input, source failure, duplicate and conflicting retries, stale revisions, review authority, event recovery, changed review context and broken relationships. Domain cases add a loss before the reference period, an unrelated document and a historical policy period. The downloaded case list names all 15 controls; the CLI computes their results on your own machine.
Before production, add cases for the installed source API, authentication and revocation path, permission changes during review, concurrency, real document handling, retention and operational recovery. The OpenAPI download describes the local reference server at 127.0.0.1. Jextra does not host its action endpoints on this website.
Turn the contract into an implementation boundary.
Name the source owner, identity owner, API owner, first consumer, reviewer and release authority. Define the retained policy history, accepted error responses, audit evidence, recovery procedure and cutover conditions. Capture which source changes invalidate a prepared request and what the reviewer must see before accepting it.
Run the reference tests separately from a customer acceptance suite. A passing synthetic suite demonstrates the declared reference behavior; it does not certify an insurer, core platform or production control. Use the exported contract and case list as review inputs, then agree the first implementation wave with the actual owners.