openapi: 3.0.3
info:
  title: Travelers 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
  - name: Quoting
    description: Commercial insurance quoting and policy pricing
  - name: Policies
    description: Policy information 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'
  /quotes:
    post:
      operationId: requestQuote
      summary: Request Commercial Insurance Quote
      description: >-
        Requests a commercial insurance quote for Business Owner Policies
        or Workers Compensation coverage. Returns indications or fully
        bindable quotes for eligible customers.
      tags:
        - Quoting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '200':
          description: Quote generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /quotes/{quote_id}:
    get:
      operationId: getQuote
      summary: Get Quote
      description: Returns a previously generated insurance quote by ID.
      tags:
        - Quoting
      parameters:
        - name: quote_id
          in: path
          required: true
          schema:
            type: string
          description: Quote identifier
      responses:
        '200':
          description: Successful response with quote details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /policies:
    get:
      operationId: listPolicies
      summary: List Policies
      description: >-
        Returns a list of commercial insurance policies for the authenticated
        organization.
      tags:
        - Policies
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [active, expired, cancelled, pending]
          description: Filter by policy status
        - name: policy_type
          in: query
          required: false
          schema:
            type: string
          description: Filter by policy type
      responses:
        '200':
          description: Successful response with policy list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /policies/{policy_number}:
    get:
      operationId: getPolicy
      summary: Get Policy
      description: Returns details of a specific insurance policy.
      tags:
        - Policies
      parameters:
        - name: policy_number
          in: path
          required: true
          schema:
            type: string
          description: The policy number
      responses:
        '200':
          description: Successful response with policy details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid input data
      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'
  schemas:
    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
    Adjuster:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
    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'
    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
    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
    BusinessInfo:
      type: object
      properties:
        name:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        industry_code:
          type: string
        annual_revenue:
          type: number
          format: float
        employee_count:
          type: integer
    QuoteRequest:
      type: object
      required:
        - product_type
        - business_info
      properties:
        product_type:
          type: string
          enum: [business-owners-policy, workers-compensation]
        business_info:
          $ref: '#/components/schemas/BusinessInfo'
        effective_date:
          type: string
          format: date
        coverage_options:
          type: object
          additionalProperties: true
    Quote:
      type: object
      properties:
        quote_id:
          type: string
        product_type:
          type: string
        status:
          type: string
          enum: [indication, bindable, declined]
        premium:
          type: number
          format: float
        effective_date:
          type: string
          format: date
        expiration_date:
          type: string
          format: date
        coverages:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              limit:
                type: number
              deductible:
                type: number
        created_at:
          type: string
          format: date-time
    QuoteResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Quote'
    Policy:
      type: object
      properties:
        policy_number:
          type: string
        product_type:
          type: string
        status:
          type: string
          enum: [active, expired, cancelled, pending]
        insured_name:
          type: string
        effective_date:
          type: string
          format: date
        expiration_date:
          type: string
          format: date
        premium:
          type: number
          format: float
        coverages:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              limit:
                type: number
              deductible:
                type: number
    PolicyResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Policy'
    PolicyListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Policy'
        total:
          type: integer