openapi: 3.0.3
info:
  title: Travelers Claims API
  description: Travelers provides APIs for business insurance claim reporting, commercial lines quoting, and policy management. These APIs enable agents, brokers, and commercial clients to programmatically manage insurance workflows including submitting claims, obtaining quotes, and managing policies across property, casualty, workers compensation, and commercial auto lines.
  version: v1.0.0
  contact:
    name: Travelers Developer Portal
    url: https://developer.travelers.com/s/
  x-logo:
    url: https://www.travelers.com/logo.png
servers:
- url: https://api.travelers.com/v1
  description: Travelers API Production Server
security:
- OAuth2: []
tags:
- name: Claims
  description: Business insurance claim reporting and management
paths:
  /claims:
    get:
      operationId: listClaims
      summary: List Claims
      description: Returns a list of business insurance claims for the authenticated organization, filterable by status, policy type, and date range.
      tags:
      - Claims
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - open
          - in-review
          - settled
          - closed
        description: Filter by claim status
      - name: policy_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - property
          - casualty
          - workers-compensation
          - commercial-auto
          - general-liability
        description: Filter by insurance policy type
      - name: start_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter claims from this date (YYYY-MM-DD)
      - name: end_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter claims to this date (YYYY-MM-DD)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
        description: Maximum number of claims to return
      responses:
        '200':
          description: Successful response with claim list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: reportClaim
      summary: Report Claim
      description: Submits a new business insurance claim report to Travelers. Supports property, casualty, workers compensation, and commercial auto claims.
      tags:
      - Claims
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimRequest'
      responses:
        '201':
          description: Claim submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /claims/{claim_number}:
    get:
      operationId: getClaim
      summary: Get Claim
      description: Returns details of a specific insurance claim by claim number.
      tags:
      - Claims
      parameters:
      - name: claim_number
        in: path
        required: true
        schema:
          type: string
        description: The claim number assigned by Travelers
      responses:
        '200':
          description: Successful response with claim details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /claims/{claim_number}/documents:
    post:
      operationId: uploadClaimDocument
      summary: Upload Claim Document
      description: Uploads supporting documentation for an existing claim, such as photos, police reports, or medical records.
      tags:
      - Claims
      parameters:
      - name: claim_number
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                document_type:
                  type: string
                  enum:
                  - photo
                  - police-report
                  - medical-record
                  - invoice
                  - other
                description:
                  type: string
      responses:
        '201':
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ClaimResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Claim'
    ClaimListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Claim'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    ClaimRequest:
      type: object
      required:
      - policy_number
      - loss_date
      - description
      - policy_type
      properties:
        policy_number:
          type: string
        policy_type:
          type: string
          enum:
          - property
          - casualty
          - workers-compensation
          - commercial-auto
          - general-liability
        loss_date:
          type: string
          format: date
        description:
          type: string
        loss_location:
          type: object
          properties:
            address:
              type: string
            city:
              type: string
            state:
              type: string
            zip:
              type: string
        claimant:
          $ref: '#/components/schemas/Claimant'
    Adjuster:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: array
          items:
            type: string
    Claim:
      type: object
      properties:
        claim_number:
          type: string
        policy_number:
          type: string
        policy_type:
          type: string
        status:
          type: string
          enum:
          - open
          - in-review
          - settled
          - closed
        loss_date:
          type: string
          format: date
        reported_date:
          type: string
          format: date-time
        description:
          type: string
        claimant:
          $ref: '#/components/schemas/Claimant'
        adjuster:
          $ref: '#/components/schemas/Adjuster'
        total_incurred:
          type: number
          format: float
    Claimant:
      type: object
      properties:
        name:
          type: string
        contact_email:
          type: string
          format: email
        contact_phone:
          type: string
    DocumentResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
            document_type:
              type: string
            filename:
              type: string
            uploaded_at:
              type: string
              format: date-time
  responses:
    BadRequest:
      description: Bad request - invalid input data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Unprocessable entity - validation errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.travelers.com/oauth/token
          scopes:
            claims:read: Read claim data
            claims:write: Submit and update claims
            quotes:read: Read quote data
            quotes:write: Request quotes
            policies:read: Read policy data