> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thewo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Triage contract

> ClaimReady request fields, supported claim domains, and result semantics.

# 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:

| Value | Triage behavior |
| - | - |
| `physical_product` | Supported for warranty and return triage. |
| `insurance` | Recognized but unsupported; returns `422 unsupported_claim_scenario`. |
| `personal_injury` | Recognized but unsupported; returns `422 unsupported_claim_scenario`. |
| `medical_claim` | Recognized but unsupported; returns `422 unsupported_claim_scenario`. |
| `vehicle_accident_liability` | Recognized but unsupported; returns `422 unsupported_claim_scenario`. |
| `financial_dispute` | Recognized but unsupported; returns `422 unsupported_claim_scenario`. |
| `legal_damages` | Recognized but unsupported; returns `422 unsupported_claim_scenario`. |
| `bodily_harm` | Recognized but unsupported; returns `422 unsupported_claim_scenario`. |

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.

| Field | Contract |
| - | - |
| `claimType` | Required: `warranty` or `return`. |
| `product` | Required object with `name`; optional `model`, `serialNumber`, `category`, `manufacturer`, and `externalProductId`. |
| `issue` | Required object with `description`. |
| `purchase` | Optional: `purchasedAt`, `seller`, `externalOrderId`, `amount`, and `documentUrl`. `amount` uses non-negative integer `minorUnits` and an explicit three-letter `currency` code. |
| `evidence` | Optional `images` and/or `documents`; each entry has a `url`. |
| `policy` | Optional customer-supplied policy; when present it requires `policyType` matching `claimType`. Optional details include `externalPolicyId`, `version`, `text`, `documentUrl`, warranty/return window days, `conditions`, `exclusions`, and `requiredEvidence`. |
| `language` | Optional: `en`, `es`, or `pt`; omission defaults to `en`. |

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`.

| Field | Values and meaning |
| - | - |
| `apparentEligibility` | `potentially_eligible`, `potentially_ineligible`, or `undetermined`; not approval or denial. |
| `reviewDisposition` | `review_ready`, `manual_review_required`, or `additional_evidence_required`; describes workflow readiness only. |
| `policyMatches` | `purchase_inside_warranty_window`, `proof_of_purchase_available`, or `physical_damage_exclusion`, each with `satisfied`, `not_satisfied`, or `unknown` status. A policy match is not an approval or denial. |
| `missingEvidence` | `proof_of_purchase`, `purchase_document`, `purchase_date`, `serial_number`, `product_photo`, `damage_photo`, `applicable_policy`, or `technician_report`. |
| `riskFlags` | `evidence_inconsistent`, `purchase_date_uncertain`, `product_identity_uncertain`, `policy_conflict`, `damage_cause_unclear`, `reported_timeline_inconsistent`, `possible_misuse_signal`, or `duplicate_evidence_signal`. These are review signals, not fraud findings. |
| `suggestedNextStep` | `request_proof_of_purchase`, `request_product_serial_number`, `request_clearer_photographs`, `schedule_technical_inspection`, `manual_policy_review`, `continue_warranty_review`, or `continue_return_review`. Advisory only. |
| `confidence` | Number from 0 to 1 describing confidence in the triage output, not truth, fraud, or legal probability. |

`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](https://docs.thewo.io/claim-ready/guides/usage-and-quotas.md#idempotency).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.