openapi: 3.0.1
info:
  title: Tint API
  description: >-
    Tint API v2 - the embedded protection / insurance-as-a-service infrastructure
    that powers Tint's Hermes platform. The REST API provides programmatic access
    to insurance products (programs) and plans, rated quotes, the full policy
    lifecycle (create, issue, endorse, report usage, cancel, void), claims handling
    (FNOL through settlement), Decision Engine decisions, Score Module scores, and
    questionnaires. Every request is authenticated with a Bearer API token; the
    same token determines whether the request is routed to the sandbox or
    production environment. Endpoint paths below are modeled from Tint's public
    documentation at https://docs.tint.ai; request/response schemas are configured
    per program via Tint's validation schema and are therefore not fully enumerated
    here.
  termsOfService: https://www.tint.ai
  contact:
    name: Tint
    url: https://www.tint.ai
  version: '2'
servers:
  - url: https://api.tint.ai/v2
    description: Tint API v2 (sandbox vs production selected by API token)
security:
  - bearerAuth: []
tags:
  - name: Programs
    description: Insurance products (programs) and plans.
  - name: Quotes
    description: Rated plan quotes for a policy.
  - name: Policies
    description: Policy lifecycle and endorsements.
  - name: Claims
    description: Claims handling from FNOL through settlement.
  - name: Decisions
    description: Decision Engine decisions and Score Module scores.
  - name: Questionnaires
    description: Questionnaire definitions attached to policies.
paths:
  /insurance-products:
    get:
      operationId: listInsuranceProducts
      tags:
        - Programs
      summary: List insurance products (programs) configured for the account.
      responses:
        '200':
          description: List of insurance products.
  /insurance-products/{productSlug}/plans:
    get:
      operationId: listPlans
      tags:
        - Programs
      summary: List the plans available within an insurance product.
      parameters:
        - name: productSlug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of plans for the insurance product.
  /policy:
    post:
      operationId: createPolicy
      tags:
        - Policies
      summary: Create a policy.
      responses:
        '201':
          description: Policy created.
  /policy/{id}:
    get:
      operationId: getPolicy
      tags:
        - Policies
      summary: Retrieve a policy.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Policy.
    put:
      operationId: updatePolicy
      tags:
        - Policies
      summary: Update a policy.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated policy.
  /policy/{id}/issue:
    post:
      operationId: issuePolicy
      tags:
        - Policies
      summary: Issue a policy.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Issued policy.
  /policy/{id}/report-usage:
    post:
      operationId: reportPolicyUsage
      tags:
        - Policies
      summary: Report usage for a usage-based policy.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Usage reported.
  /policy/{id}/payment:
    post:
      operationId: recordPolicyPayment
      tags:
        - Policies
      summary: Record a payment against a policy.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Payment recorded.
  /policy/{id}/cancel:
    post:
      operationId: cancelPolicy
      tags:
        - Policies
      summary: Cancel a policy.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Policy cancelled.
  /policy/{id}/void:
    post:
      operationId: voidPolicy
      tags:
        - Policies
      summary: Void a policy.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Policy voided.
  /policy/{policyId}/quotes:
    get:
      operationId: getPolicyQuotes
      tags:
        - Quotes
      summary: Get rated plan quotes for a policy. Coverages are returned inline.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Plan quotes including inline coverage details.
  /policy/{policyId}/decisions/{decisionType}:
    get:
      operationId: getPolicyDecision
      tags:
        - Decisions
      summary: Calculate and retrieve a Decision Engine decision for a policy.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: decisionType
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Calculated decision.
  /policy/{policyId}/scores:
    get:
      operationId: computePolicyScores
      tags:
        - Decisions
      summary: Compute Score Module scores for a policy.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Computed scores.
  /policy/{policyId}/score/{scoreId}:
    get:
      operationId: getPolicyScore
      tags:
        - Decisions
      summary: Retrieve one calculated score for a policy.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: scoreId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Calculated score.
  /policy/{policyId}/endorsement:
    post:
      operationId: createEndorsement
      tags:
        - Policies
      summary: Create an endorsement (mid-term change) on a policy.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Endorsement created.
  /policy/{policyId}/endorsements:
    get:
      operationId: listEndorsements
      tags:
        - Policies
      summary: List endorsements on a policy.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of endorsements.
  /policy/{policyId}/endorsement/{id}:
    get:
      operationId: getEndorsement
      tags:
        - Policies
      summary: Retrieve an endorsement.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Endorsement.
    put:
      operationId: updateEndorsement
      tags:
        - Policies
      summary: Update an endorsement.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated endorsement.
  /policy/{policyId}/endorsement/{id}/approve:
    post:
      operationId: approveEndorsement
      tags:
        - Policies
      summary: Approve an endorsement.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Endorsement approved.
  /policy/{policyId}/endorsement/{id}/cancel:
    post:
      operationId: cancelEndorsement
      tags:
        - Policies
      summary: Cancel an endorsement.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Endorsement cancelled.
  /policy/{policyId}/endorsement/{id}/quotes:
    get:
      operationId: getEndorsementQuotes
      tags:
        - Quotes
      summary: Get quotes for an endorsement.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Endorsement quotes.
  /policy/{policyId}/endorsement/{id}/decisions/{decisionType}:
    get:
      operationId: getEndorsementDecision
      tags:
        - Decisions
      summary: Get a decision for an endorsement.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: decisionType
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Endorsement decision.
  /policy/{policyId}/questionnaire/{slug}:
    get:
      operationId: getPolicyQuestionnaire
      tags:
        - Questionnaires
      summary: Retrieve a questionnaire definition attached to a policy.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Questionnaire definition.
  /policy/{policyId}/claim:
    post:
      operationId: createClaim
      tags:
        - Claims
      summary: Create a claim (first notice of loss) on a policy.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Claim created.
  /policy/{policyId}/claims:
    get:
      operationId: listPolicyClaims
      tags:
        - Claims
      summary: List claims on a policy.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of claims.
  /policy/{policyId}/claim/{claimId}:
    put:
      operationId: updatePolicyClaim
      tags:
        - Claims
      summary: Update a claim under a policy.
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
        - name: claimId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated claim.
  /claims:
    get:
      operationId: listClaims
      tags:
        - Claims
      summary: List claims across the account.
      responses:
        '200':
          description: List of claims.
  /claim/{id}:
    get:
      operationId: getClaim
      tags:
        - Claims
      summary: Retrieve a claim.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Claim.
    put:
      operationId: updateClaim
      tags:
        - Claims
      summary: Update a claim.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated claim.
  /claim/{id}/receive:
    post:
      operationId: receiveClaim
      tags:
        - Claims
      summary: Mark a claim as received.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Claim received.
  /claim/{id}/incomplete:
    post:
      operationId: markClaimIncomplete
      tags:
        - Claims
      summary: Mark a claim as incomplete.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Claim marked incomplete.
  /claim/{id}/review:
    post:
      operationId: reviewClaim
      tags:
        - Claims
      summary: Move a claim into review.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Claim under review.
  /claim/{id}/approve:
    post:
      operationId: approveClaim
      tags:
        - Claims
      summary: Approve a claim.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Claim approved.
  /claim/{id}/settle:
    post:
      operationId: settleClaim
      tags:
        - Claims
      summary: Settle a claim.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Claim settled.
  /claim/{id}/deny:
    post:
      operationId: denyClaim
      tags:
        - Claims
      summary: Deny a claim.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Claim denied.
  /claim/{id}/withdraw:
    post:
      operationId: withdrawClaim
      tags:
        - Claims
      summary: Withdraw a claim.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Claim withdrawn.
  /claim/{claimId}/notes:
    get:
      operationId: listClaimNotes
      tags:
        - Claims
      summary: List notes on a claim.
      parameters:
        - name: claimId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of claim notes.
  /claim/{claimId}/note:
    post:
      operationId: createClaimNote
      tags:
        - Claims
      summary: Add a note to a claim.
      parameters:
        - name: claimId
          in: path
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Note created.
  /claim/{claimId}/note/{noteId}:
    put:
      operationId: updateClaimNote
      tags:
        - Claims
      summary: Update a claim note.
      parameters:
        - name: claimId
          in: path
          required: true
          schema:
            type: string
        - name: noteId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated note.
  /claim/{claimId}/payment:
    post:
      operationId: createClaimPayment
      tags:
        - Claims
      summary: Record a payment against a claim.
      parameters:
        - name: claimId
          in: path
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Claim payment recorded.
  /claim/{claimId}/upload-url:
    get:
      operationId: getClaimUploadUrl
      tags:
        - Claims
      summary: Get a pre-signed URL to upload a claim document.
      parameters:
        - name: claimId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Upload URL.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token passed as "Authorization: Bearer ${API_TOKEN}". The token
        determines whether the request is routed to the sandbox or production
        environment.