​

Triage contract

ClaimReady accepts an explicit claim domain and returns a structured assessment for a supported physical-product warranty or return claim. It does not decide or adjudicate the claim.

​

Claim domains

claimDomain is required. The controlled vocabulary is: An unrecognized value such as home_insurance is malformed input and returns 400 invalid_request_payload. ClaimReady never infers a domain from the issue, product, or evidence.

​

Request fields

The request body is strict. It requires claimDomain, claimType, product, and issue; other top-level fields are rejected. A policy or purchase record is not required to submit. If policy details are absent, the result can identify applicable_policy as missing. If purchase or evidence facts are absent, the result can report the corresponding evidence needs. Optional fields do not turn a structurally valid claim into an invalid request merely because the business facts are incomplete. The supplied customer policy is the only policy authority for the triage; ClaimReady does not invent warranty or legal rules. Structured policy fields such as coverage windows and required-evidence declarations can guide deterministic comparisons when the request supplies enough facts. The free-form text, conditions, and exclusions fields preserve customer-authored policy context; they are not an executable rules language. ClaimReady does not infer rules from that prose. When the modeled facts do not establish whether a condition applies, the corresponding match remains unknown and the result may require manual policy review. Evidence URLs are submitted as references. The API retrieves remote evidence through The Wo’s controlled server-side path. The public response indicates whether purchase documents or evidence were supplied and reports evidence types; it does not return raw URLs or evidence bytes. Language changes interpretation context and human-readable descriptions, while canonical result codes and ClaimReady domain boundaries remain unchanged.

​

Response resource

POST returns 201 with a resource and usage. GET returns 200 with the resource and no new Usage metadata. The resource contains id, status, a safe input snapshot, optional result, and timestamps. The safe snapshot can include claimDomain, claimType, product and issue details, selected safe purchase and policy data, document-supplied booleans, evidence-supplied status, evidence types, and optional language. It omits customer identity, API keys, provider details, and raw source URLs. The result contains claimType, apparentEligibility, reviewDisposition, policyMatches, missingEvidence, riskFlags, suggestedNextStep, and confidence. unknown means the supplied facts do not establish whether a policy condition matches. It is distinct from not_satisfied, which means the available facts show that it does not match. A match describes evaluation of supplied facts and policy; neither status authorizes a claim outcome. policy.requiredEvidence uses the controlled values proof_of_purchase, purchase_document, purchase_date, serial_number, product_photo, damage_photo, applicable_policy, and technician_report. These are the requirements declared by the supplied policy. result.missingEvidence reports needs identified for this triage and is a separate result. The generic evidenceTypes values image and document describe supplied source types; they do not by themselves satisfy a specific evidence subtype such as purchase_document. Only physical_product supports warranty and return. Within that domain, the policy and evidence guide a structured review; they do not grant ClaimReady authority to approve, deny, refund, or make legal or insurance determinations.

​

Idempotency

POST requires an Idempotency-Key of 1–255 characters. Repeating the same key with the same material request replays the original result. Reusing the key with a materially different request returns 409 idempotency_conflict; the claim domain is part of the material request. See Usage and quotas.

​

Retrieval

GET /v1/product-claims/{id} retrieves a customer-owned triage. A resource owned by another customer is indistinguishable from a missing resource and returns 404 claim_triage_not_found. There is no list or search operation.