openapi: 3.0.3
info:
  title: Surplus Lines Tax API
  description: |
    Accurate surplus lines tax calculations for all 50 U.S. states, the District of Columbia,
    Puerto Rico, and the U.S. Virgin Islands. Calculate state-specific taxes, stamping fees,
    filing fees, and surcharges with proper rounding rules applied automatically.
  version: 1.0.0
  contact:
    name: Surplus Lines Tax API Support
    email: support@undtec.com
    url: https://surpluslinesapi.com
  license:
    name: Commercial
    url: https://surpluslinesapi.com/terms
servers:
  - url: https://api.surpluslinesapi.com/v1
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Tax Calculation
    description: Calculate surplus lines taxes for any U.S. jurisdiction
  - name: Account
    description: Account and usage information (Coming Soon)
paths:
  /calculate:
    post:
      tags:
        - Tax Calculation
      summary: Calculate surplus lines taxes
      description: |
        Calculate surplus lines taxes for a specific state and premium amount.
        This endpoint applies state-specific tax rates, rounding rules, and special
        coverage type handling automatically.

        **State-Specific Features:**
        - Alaska: Wet marine coverage uses independent procurement tax rate
        - Iowa: Tax rates phase down 2024-2027
        - Illinois: Optional fire marshal tax (0-1%)
        - Montana: Electronic filing eliminates stamping fee; fire insurance has additional tax
        - Oregon: New/renewal policies include $10 service charge
        - South Dakota: Fire insurance has higher tax rate
        - Virginia: Workers compensation is tax exempt
        - Puerto Rico: Medical malpractice is tax exempt
      operationId: calculateTax
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CalculateRequest"
            examples:
              basic:
                summary: Basic calculation
                value:
                  state: "Texas"
                  premium: 10000
              wet_marine:
                summary: Alaska wet marine coverage
                value:
                  state: "Alaska"
                  premium: 50000
                  wet_marine: true
              fire_insurance:
                summary: Montana fire insurance with electronic filing
                value:
                  state: "Montana"
                  premium: 25000
                  fire_insurance: true
                  electronic_filing: true
              illinois_fire_marshal:
                summary: Illinois with fire marshal tax
                value:
                  state: "Illinois"
                  premium: 100000
                  fire_marshal_rate: 0.005
      responses:
        "200":
          description: Successful calculation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CalculateResponse"
              example:
                success: true
                state: "Texas"
                premium: 10000
                taxes:
                  sl_tax: 485.00
                  tax_rate: 0.0485
                  stamping_fee: 18.00
                  stamping_fee_rate: 0.0018
                  filing_fee: 0
                  filing_fee_rate: 0
                total_tax: 503.00
                total_due: 10503.00
                billing:
                  charged: 0.05
                  was_free_query: false
                  remaining_balance: 9.95
                  free_queries_remaining: 0
        "400":
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missing_state:
                  summary: Missing state parameter
                  value:
                    success: false
                    error:
                      code: "MISSING_STATE"
                      message: "State parameter is required"
                invalid_state:
                  summary: Invalid state name
                  value:
                    success: false
                    error:
                      code: "INVALID_STATE"
                      message: "Specified state not recognized"
                invalid_premium:
                  summary: Invalid premium amount
                  value:
                    success: false
                    error:
                      code: "INVALID_PREMIUM"
                      message: "Premium must be a positive number"
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missing_key:
                  summary: Missing API key
                  value:
                    success: false
                    error:
                      code: "MISSING_API_KEY"
                      message: "No API key provided for protected endpoint"
                invalid_key:
                  summary: Invalid API key
                  value:
                    success: false
                    error:
                      code: "INVALID_API_KEY"
                      message: "API key is invalid or expired"
        "429":
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                error:
                  code: "RATE_LIMIT_EXCEEDED"
                  message: "Too many requests, try again later"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                error:
                  code: "INTERNAL_ERROR"
                  message: "Internal server error"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: "API key obtained from app.surpluslinesapi.com dashboard"
  schemas:
    CalculateRequest:
      type: object
      required:
        - state
        - premium
      properties:
        state:
          type: string
          description: |
            Full state name (case-insensitive). Valid values include all 50 U.S. states,
            District of Columbia, Puerto Rico, and Virgin Islands.
          example: "Texas"
          enum:
            - Alabama
            - Alaska
            - Arizona
            - Arkansas
            - California
            - Colorado
            - Connecticut
            - Delaware
            - District of Columbia
            - Florida
            - Georgia
            - Hawaii
            - Idaho
            - Illinois
            - Indiana
            - Iowa
            - Kansas
            - Kentucky
            - Louisiana
            - Maine
            - Maryland
            - Massachusetts
            - Michigan
            - Minnesota
            - Mississippi
            - Missouri
            - Montana
            - Nebraska
            - Nevada
            - New Hampshire
            - New Jersey
            - New Mexico
            - New York
            - North Carolina
            - North Dakota
            - Ohio
            - Oklahoma
            - Oregon
            - Pennsylvania
            - Puerto Rico
            - Rhode Island
            - South Carolina
            - South Dakota
            - Tennessee
            - Texas
            - Utah
            - Vermont
            - Virgin Islands
            - Virginia
            - Washington
            - West Virginia
            - Wisconsin
            - Wyoming
        premium:
          type: number
          format: double
          minimum: 0.01
          description: Premium amount in USD (must be positive)
          example: 10000
        wet_marine:
          type: boolean
          default: false
          description: |
            Set true for wet marine coverage. Affects Alaska calculation
            (3.7% independent procurement tax instead of 2.7% surplus lines tax).
        fire_insurance:
          type: boolean
          default: false
          description: |
            Set true for fire insurance coverage. Affects:
            - South Dakota: 3.0% tax rate instead of 2.5%
            - Montana: Additional 2.5% tax
        electronic_filing:
          type: boolean
          default: false
          description: |
            Set true for electronic filing. Affects Montana stamping fee
            (eliminates the stamping fee).
        fire_marshal_rate:
          type: number
          format: double
          minimum: 0
          maximum: 0.01
          description: |
            Fire marshal tax rate as decimal (0-0.01 representing 0-1%).
            Illinois only.
          example: 0.005
        medical_malpractice:
          type: boolean
          default: false
          description: |
            Set true for medical malpractice coverage.
            Puerto Rico: Medical malpractice is tax exempt.
        workers_comp:
          type: boolean
          default: false
          description: |
            Set true for workers compensation coverage.
            Virginia: Workers compensation is tax exempt.
        year:
          type: integer
          minimum: 2024
          maximum: 2030
          description: |
            Tax year for calculation. Affects Iowa rates which phase down 2024-2027:
            - 2024: 0.975%
            - 2025: 0.95%
            - 2026: 0.925%
            - 2027+: 0.9%
          example: 2025
        new_business:
          type: boolean
          default: true
          description: |
            New/renewal policy flag. Affects Oregon which has a $10 flat
            service charge for new and renewal policies.
    CalculateResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the calculation was successful
          example: true
        state:
          type: string
          description: The state used for calculation (normalized)
          example: "Texas"
        premium:
          type: number
          format: double
          description: The premium amount used
          example: 10000
        taxes:
          type: object
          description: Detailed tax breakdown
          properties:
            sl_tax:
              type: number
              format: double
              description: Surplus lines tax amount
              example: 485.00
            tax_rate:
              type: number
              format: double
              description: Surplus lines tax rate as decimal
              example: 0.0485
            stamping_fee:
              type: number
              format: double
              description: Stamping fee amount
              example: 18.00
            stamping_fee_rate:
              type: number
              format: double
              description: Stamping fee rate as decimal
              example: 0.0018
            filing_fee:
              type: number
              format: double
              description: Filing fee amount (flat fee)
              example: 0
            filing_fee_rate:
              type: number
              format: double
              description: Filing fee rate as decimal (if percentage-based)
              example: 0
            fire_marshal_tax:
              type: number
              format: double
              description: Fire marshal tax (Illinois only)
              example: 0
            service_charge:
              type: number
              format: double
              description: Service charge (Oregon $10 for new/renewal)
              example: 0
        total_tax:
          type: number
          format: double
          description: Sum of all taxes and fees
          example: 503.00
        total_due:
          type: number
          format: double
          description: Premium plus total tax
          example: 10503.00
        billing:
          type: object
          description: Billing information for this API call
          properties:
            charged:
              type: number
              format: double
              description: Amount charged for this query
              example: 0.05
            was_free_query:
              type: boolean
              description: Whether this was a free query
              example: false
            remaining_balance:
              type: number
              format: double
              description: Remaining account balance
              example: 9.95
            free_queries_remaining:
              type: integer
              description: Number of free queries remaining
              example: 0
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: "INVALID_STATE"
              enum:
                - MISSING_API_KEY
                - INVALID_API_KEY
                - MISSING_STATE
                - INVALID_STATE
                - INVALID_PREMIUM
                - RATE_LIMIT_EXCEEDED
                - INTERNAL_ERROR
            message:
              type: string
              description: Human-readable error message
              example: "Specified state not recognized"