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

# Create a claim triage

> Requires an active ClaimReady entitlement and an Idempotency-Key. Supported requests return a completed triage with one claim_triage Usage unit. Recognized unsupported domains return 422.



## OpenAPI

````yaml /openapi/claim-ready-v1.yaml post /v1/product-claims/triage
openapi: 3.1.0
info:
  title: The Wo ClaimReady API
  version: 1.0.0
  description: >-
    Public v1 contract for ClaimReady physical-product warranty and return
    triage. Results support human review and do not decide claims.
servers:
  - url: https://api.thewo.io
    description: Production
security:
  - ApiKey: []
tags:
  - name: ClaimReady
    description: Claim triage and customer-owned result retrieval.
paths:
  /v1/product-claims/triage:
    post:
      tags:
        - ClaimReady
      summary: Create a claim triage
      description: >-
        Requires an active ClaimReady entitlement and an Idempotency-Key.
        Supported requests return a completed triage with one claim_triage Usage
        unit. Recognized unsupported domains return 422.
      operationId: triageProductClaim
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriageRequest'
            example:
              claimDomain: physical_product
              claimType: warranty
              product:
                name: Example blender
                model: B-100
              issue:
                description: The motor stops during normal use.
              purchase:
                purchasedAt: '2026-02-10'
                seller: Example Shop
              language: en
      responses:
        '201':
          description: Completed triage created or replayed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: 1–255 characters. Reuse for retries of the same material request.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    TriageRequest:
      type: object
      additionalProperties: false
      required:
        - claimDomain
        - claimType
        - product
        - issue
      properties:
        claimDomain:
          $ref: '#/components/schemas/ClaimDomain'
        claimType:
          $ref: '#/components/schemas/ClaimType'
        product:
          $ref: '#/components/schemas/ProductInput'
        purchase:
          $ref: '#/components/schemas/PurchaseInput'
        issue:
          type: object
          additionalProperties: false
          required:
            - description
          properties:
            description:
              type: string
        evidence:
          $ref: '#/components/schemas/EvidenceInput'
        policy:
          $ref: '#/components/schemas/PolicyInput'
        language:
          type: string
          enum:
            - en
            - es
            - pt
    TriageResponse:
      allOf:
        - $ref: '#/components/schemas/TriageResource'
        - type: object
          required:
            - usage
          properties:
            usage:
              type: object
              required:
                - operation
                - units
              properties:
                operation:
                  type: string
                  const: claim_triage
                units:
                  type: integer
                  const: 1
    ClaimDomain:
      type: string
      enum:
        - physical_product
        - insurance
        - personal_injury
        - medical_claim
        - vehicle_accident_liability
        - financial_dispute
        - legal_damages
        - bodily_harm
    ClaimType:
      type: string
      enum:
        - warranty
        - return
    ProductInput:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
        model:
          type: string
        serialNumber:
          type: string
        category:
          type: string
        manufacturer:
          type: string
        externalProductId:
          type: string
    PurchaseInput:
      type: object
      additionalProperties: false
      properties:
        purchasedAt:
          type: string
          format: date
        seller:
          type: string
        externalOrderId:
          type: string
        amount:
          type: object
          additionalProperties: false
          required:
            - minorUnits
            - currency
          properties:
            minorUnits:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            currency:
              type: string
              pattern: ^\s*[A-Za-z]{3}\s*$
        documentUrl:
          type: string
          format: uri
          pattern: ^https?://
          description: >-
            Absolute HTTP or HTTPS URL retrievable subject to The Wo
            remote-resource safety controls.
    EvidenceInput:
      type: object
      additionalProperties: false
      properties:
        images:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceReference'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceReference'
    PolicyInput:
      type: object
      additionalProperties: false
      required:
        - policyType
      description: >-
        Customer-supplied policy context for this triage. ClaimReady does not
        invent warranty or legal rules. Structured policy fields can guide
        deterministic comparisons when enough request facts are available;
        free-form text, conditions, and exclusions are preserved as context and
        are not an executable rules language.
      properties:
        externalPolicyId:
          type: string
        version:
          type: string
        policyType:
          type: string
          enum:
            - warranty
            - return
          description: Must match the request claimType.
        text:
          type: string
          description: >-
            Customer-authored policy text retained as context; ClaimReady does
            not infer executable rules from this prose.
        documentUrl:
          type: string
          format: uri
          pattern: ^https?://
          description: >-
            Absolute HTTP or HTTPS URL retrievable subject to The Wo
            remote-resource safety controls.
        warrantyWindowDays:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        returnWindowDays:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        conditions:
          type: array
          description: >-
            Customer-authored policy conditions retained as context; they are
            not an executable rules language.
          items:
            type: string
        exclusions:
          type: array
          description: >-
            Customer-authored policy exclusions retained as context; they are
            not an executable rules language.
          items:
            type: string
        requiredEvidence:
          type: array
          items:
            $ref: '#/components/schemas/RequiredEvidenceCode'
    TriageResource:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - input
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        status:
          type: string
          const: completed
        input:
          type: object
          additionalProperties: false
          required:
            - claimDomain
            - claimType
            - product
            - purchaseDocumentSupplied
            - issue
            - evidenceSupplied
            - evidenceTypes
            - policyDocumentSupplied
          properties:
            claimDomain:
              $ref: '#/components/schemas/ClaimDomain'
            claimType:
              $ref: '#/components/schemas/ClaimType'
            product:
              $ref: '#/components/schemas/ProductInput'
            purchase:
              $ref: '#/components/schemas/PurchaseSnapshot'
            purchaseDocumentSupplied:
              type: boolean
            issue:
              type: object
              required:
                - description
              properties:
                description:
                  type: string
            evidenceSupplied:
              type: boolean
            evidenceTypes:
              type: array
              items:
                type: string
                enum:
                  - image
                  - document
            policy:
              $ref: '#/components/schemas/PolicySnapshot'
            policyDocumentSupplied:
              type: boolean
            language:
              type: string
              enum:
                - en
                - es
                - pt
        result:
          $ref: '#/components/schemas/TriageResult'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string
            details:
              type: object
    EvidenceReference:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          pattern: ^https?://
          description: >-
            Absolute HTTP or HTTPS URL retrievable subject to The Wo
            remote-resource safety controls.
    RequiredEvidenceCode:
      type: string
      enum:
        - proof_of_purchase
        - purchase_document
        - purchase_date
        - serial_number
        - product_photo
        - damage_photo
        - applicable_policy
        - technician_report
    PurchaseSnapshot:
      type: object
      additionalProperties: false
      properties:
        purchasedAt:
          type: string
          format: date
        seller:
          type: string
        externalOrderId:
          type: string
        amount:
          type: object
          properties:
            minorUnits:
              type: integer
            currency:
              type: string
              pattern: ^[A-Z]{3}$
    PolicySnapshot:
      type: object
      additionalProperties: false
      required:
        - policyType
      properties:
        externalPolicyId:
          type: string
        version:
          type: string
        policyType:
          type: string
          enum:
            - warranty
            - return
        text:
          type: string
        warrantyWindowDays:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        returnWindowDays:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        conditions:
          type: array
          items:
            type: string
        exclusions:
          type: array
          items:
            type: string
        requiredEvidence:
          type: array
          items:
            $ref: '#/components/schemas/RequiredEvidenceCode'
    TriageResult:
      type: object
      additionalProperties: false
      required:
        - claimType
        - apparentEligibility
        - reviewDisposition
        - policyMatches
        - missingEvidence
        - riskFlags
        - suggestedNextStep
        - confidence
      properties:
        claimType:
          $ref: '#/components/schemas/ClaimType'
        apparentEligibility:
          type: string
          enum:
            - potentially_eligible
            - potentially_ineligible
            - undetermined
        reviewDisposition:
          type: string
          enum:
            - review_ready
            - manual_review_required
            - additional_evidence_required
        policyMatches:
          type: array
          items:
            type: object
            required:
              - code
              - status
              - description
            properties:
              code:
                type: string
                enum:
                  - purchase_inside_warranty_window
                  - proof_of_purchase_available
                  - physical_damage_exclusion
              status:
                type: string
                enum:
                  - satisfied
                  - not_satisfied
                  - unknown
              description:
                type: string
        missingEvidence:
          type: array
          items:
            type: object
            required:
              - code
              - description
            properties:
              code:
                type: string
                enum:
                  - proof_of_purchase
                  - purchase_document
                  - purchase_date
                  - serial_number
                  - product_photo
                  - damage_photo
                  - applicable_policy
                  - technician_report
              description:
                type: string
        riskFlags:
          type: array
          items:
            type: object
            required:
              - code
            properties:
              code:
                type: string
                enum:
                  - evidence_inconsistent
                  - purchase_date_uncertain
                  - product_identity_uncertain
                  - policy_conflict
                  - damage_cause_unclear
                  - reported_timeline_inconsistent
                  - possible_misuse_signal
                  - duplicate_evidence_signal
        suggestedNextStep:
          type: object
          required:
            - code
          properties:
            code:
              type: string
              enum:
                - request_proof_of_purchase
                - request_product_serial_number
                - request_clearer_photographs
                - schedule_technical_inspection
                - manual_policy_review
                - continue_warranty_review
                - continue_return_review
            explanation:
              type: string
        confidence:
          type: number
          minimum: 0
          maximum: 1
  responses:
    BadRequest:
      description: Invalid JSON, payload, or idempotency key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidRequest:
              value:
                error:
                  code: invalid_request_payload
                  message: Request body is invalid.
                  requestId: req_123
            invalidDomain:
              value:
                error:
                  code: invalid_request_payload
                  message: Request body is invalid.
                  requestId: req_123
            invalidIdempotencyKey:
              value:
                error:
                  code: invalid_idempotency_key
                  message: Idempotency-Key is invalid.
                  requestId: req_123
    Unauthorized:
      description: API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Customer access is denied or POST entitlement is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Idempotency key conflicts or is currently processing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: Evidence content exceeds its configured limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: Evidence media type is unsupported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unprocessable:
      description: Recognized domain is unsupported or evidence source is rejected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unsupportedDomain:
              value:
                error:
                  code: unsupported_claim_scenario
                  message: This claim domain is not supported by ClaimReady.
                  requestId: req_123
            evidenceRejected:
              value:
                error:
                  code: evidence_source_rejected
                  message: The claim evidence source is not allowed.
                  requestId: req_123
    TooManyRequests:
      description: Rate limit or operation quota was exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected internal error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadGateway:
      description: Processing failed or returned an invalid result.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unavailable:
      description: >-
        Authentication, entitlement, idempotency, quota, evidence, provider,
        persistence, or Usage dependency is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

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