openapi: 3.0.3
info:
  title: Surplus Lines Tax API
  description: 'Surplus lines tax for all 50 states, the District of Columbia, Puerto Rico and the U.S.
    Virgin Islands. Every charge returned carries the name its own state uses and a link to the document
    that sets it.


    HOW THE CALCULATION IS DRIVEN

    - A fee is sent on the side that charged it: `carrier_fees` (the insurer required it) or `broker_fees` (the broker charges and keeps it). In 10 of 53 jurisdictions the tax depends on who imposed the fee, so a fee sent without a side cannot be priced there and is refused with FEE_TYPE_REQUIRED rather than guessed. In the other 43, `fees` is accepted.

    - `lob` selects the line of business. States exempt or re-rate particular coverages.

    - `effective_date` resolves the charges in force on that date, past or future, including scheduled
    changes.

    - `jurisdiction` prices Kentucky''s local government premium tax, set by 417 jurisdictions and often
    larger than the state tax. Omit it and the response says the municipal tax was excluded rather than
    returning a figure that is quietly short.

    - The response shows its work: each charge carries `name`, `rate` and `source`; `state_rules` reports
    the state''s rounding rule and any fee cap alongside what the calculation actually did; `notes` gives
    the authority for how a fee was treated; `warnings` appears where a state publishes an exemption a
    single call cannot verify.'
  version: 3.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://n8nsandbox.undtec.com/webhook/slapi/internal/v3
  description: Internal calculation core - same request and response, no key. Not the published address.
- url: https://api.surpluslinesapi.com/v1
  description: The API. Requires an API key.
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:
              insurer_fee:
                summary: Fee the insurer required - taxed in California
                value:
                  state: California
                  premium: 1000
                  carrier_fees: 250
                  lob: SLT-PROP
              broker_fee:
                summary: Broker's own fee - not taxed in California
                value:
                  state: California
                  premium: 1000
                  broker_fees: 250
                  lob: SLT-PROP
              historical:
                summary: As of a past date - California's stamping fee is 0.25% before 2023
                value:
                  state: California
                  premium: 1000
                  lob: SLT-PROP
                  carrier_fees: 250
                  effective_date: '2022-06-01'
              kentucky_local:
                summary: Kentucky with a jurisdiction, for the local government premium tax
                value:
                  state: Kentucky
                  premium: 1000
                  lob: SLT-PROP
                  carrier_fees: 250
                  jurisdiction: '1017'
      responses:
        '200':
          description: Successful calculation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateResponse'
              example:
                success: true
                state: Texas
                state_code: TX
                premium: 10000
                lob: SLT-PROP
                effective_date: null
                rates_from: current
                breakdown:
                  base_tax:
                    rate: 4.85%
                    amount: 485
                  stamping_fee:
                    rate: 0.04%
                    amount: 4
                  filing_fee: null
                  service_fee: null
                  surcharge: null
                  regulatory_fee: null
                  fire_marshal_tax: null
                total_tax: 489
                total_due: 10489
                notes: []
                stamp:
                - instrument: stamp
                  ordinal: 1
                  wording: This insurance has been placed with an insurer that is not licensed by the state of Michigan.
                    In case of insolvency, payment of claims may not be guaranteed.
                  how_it_must_appear: '"printed, typed, or stamped in RED INK upon its FACE, in not less than 10-point
                    type" - on each policy, cover note, or other instrument evidencing the insurance that is delivered
                    to the insured or their representative.'
                  style:
                    pt: 10
                    ink: red
                  citation: MCL 500.1922 ("Notice on face of instrument evidencing surplus lines insurance"), Michigan
                    Legislature, retrieved 2026-08-14.
                  provenance: state_first_party
                  provenance_note: null
                  verified_at: '2026-08-14'
                legislative_source: https://statutes.capitol.texas.gov/docs/IN/htm/IN.225.htm
                rate_period: null
                fallback_reason: null
                error_code: null
                error_message: null
                account:
                  balance: '9.62'
                  free_queries_remaining: 99
                  was_free_query: false
        '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
  /historical-rates:
    get:
      summary: The charges in force for a state on a date
      description: Returns the rates themselves rather than a tax figure. For a dated CALCULATION, send
        `effective_date` to /calculate instead.
      parameters:
      - name: state
        in: query
        required: true
        schema:
          type: string
        example: Texas
      - name: date
        in: query
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-01'
      responses:
        '200':
          description: The charges in force
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
              examples:
                texas:
                  summary: Texas on 2025-01-01
                  value:
                    success: true
                    state: Texas
                    state_code: TX
                    effective_date: '2025-01-01'
                    rates_from: historical
                    charges:
                    - key: sl_tax
                      name: Surplus Lines Premium Tax
                      rate: 4.85%
                      basis: percent
                      source: https://comptroller.texas.gov/taxes/insurance/surplus-lines.php
                      effective_from: '2020-01-01'
                    - key: stamping_fee
                      name: Stamping Fee
                      rate: 0.04%
                      basis: percent
                      source: https://www.sltx.org/brokers/billing-information/stamping-fees-taxes/
                      effective_from: '2024-01-01'
                    payment_frequency: null
                    rounding_rule: Whole dollars for premium, cents for the tax on the return total, not
                      per policy. (Tex. Form 25-104 (printed column headings))
                    legislative_source: https://comptroller.texas.gov/taxes/insurance/surplus-lines.php
                    earliest_verified: '2020-01-01'
                    account:
                      balance: '9.62'
                      free_queries_remaining: 0
                      was_free_query: false
                iowa:
                  summary: Iowa mid step-down
                  value:
                    success: true
                    state: Iowa
                    state_code: IA
                    effective_date: '2025-06-15'
                    rates_from: historical
                    charges:
                    - key: sl_tax
                      name: Premium Tax
                      rate: 0.95%
                      basis: percent
                      source: https://www.legis.iowa.gov/docs/code/432.1.pdf
                      effective_from: '2025-01-01'
                    payment_frequency: null
                    rounding_rule: null
                    legislative_source: https://www.legis.iowa.gov/docs/code/432.1.pdf
                    earliest_verified: '2020-01-01'
                    account:
                      balance: '9.62'
                      free_queries_remaining: 0
                      was_free_query: false
        '400':
          description: Missing or invalid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_state:
                  value:
                    error: true
                    code: MISSING_STATE
                    message: state is required. Send a two-letter code or a full name.
                    statusCode: 400
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: Two-letter code or full name. "CA" and "California" both work.
          example: California
        premium:
          type: number
          description: Premium only. Send a fee in a fee field so the state rule can apply to it.
          example: 10000
        carrier_fees:
          type: number
          description: A fee the insurer required as a condition of the policy (policy, inspection, underwriting
            fee).
          example: 250
        broker_fees:
          type: number
          description: A fee the broker charges the insured for its own services and keeps.
          example: 250
        carrier_fee_conditions_met:
          type: boolean
          description: 'Caller declaration: the state''s conditional exemption for this side is satisfied.
            Strictly opt-in - only an explicit true changes anything, and the response records it as the
            caller''s assertion.'
        broker_fee_conditions_met:
          type: boolean
          description: As above, for the broker side.
        lob:
          type: string
          description: Line of business. Five are currently reachable.
          enum:
          - SLT-PROP
          - SLT-APD
          - SLT-CARGO
          - SLT-GL
          - SLT-PROFL
          example: SLT-PROP
        effective_date:
          type: string
          format: date
          description: YYYY-MM-DD. Resolves the charges in force on that date. Defaults to today.
          example: '2022-06-01'
        jurisdiction:
          type: string
          description: 'Kentucky only: 4-digit jurisdiction code or city name, for the local government
            premium tax. `city` is accepted as an alias.'
          example: '1017'
      additionalProperties: false
    CalculateResponse:
      type: object
      properties:
        stamp:
          type: array
          description: 'Every notice the state prescribes for the policy. Empty for the four jurisdictions that
            prescribe none: the District of Columbia and Indiana prescribe no notice, Oklahoma prescribes the
            format and the fact but no words, and Virginia prescribes a form its Commission has not published.
            Eight states prescribe more than one instrument, and in Arizona and North Carolina the second says
            the opposite about the insurer, so all of them are returned in order.'
          items:
            type: object
            properties:
              instrument:
                type: string
                description: which document the wording belongs on
              ordinal:
                type: integer
              wording:
                type: string
                description: the state's own words, unaltered
              how_it_must_appear:
                type: string
                nullable: true
                description: the appearance rule in the state's own words
              style:
                type: object
                nullable: true
                description: 'the same rule as data: pt, bold, ink, caps, contrasting_colour_required, and forms[]
                  where the state permits more than one appearance (Idaho allows red at 10-point bold OR black
                  at 12-point bold, and neither is the default)'
              citation:
                type: string
              provenance:
                type: string
                enum:
                - state_first_party
                - commercial_reproduction
                description: where the text was read. A commercial_reproduction always carries provenance_note
              provenance_note:
                type: string
                nullable: true
              verified_at:
                type: string
                format: date
        success:
          type: boolean
        state:
          type: string
        lob:
          type: string
        effective_date:
          type: string
          nullable: true
        fees_as_sent:
          type: number
        carrier_fees:
          type: number
        broker_fees:
          type: number
        wholesaler_fees:
          type: number
        calculation:
          type: object
          properties:
            premium:
              type: number
            breakdown:
              type: object
              description: One entry per charge slot; unused slots are null. The 0.175% clearinghouse
                charge is `transaction_fee`, because nine states use it and they file through two different
                operators - the operator is named in the charge title, per state.
              additionalProperties:
                type: object
                properties:
                  rate:
                    type: string
                    example: 3%
                  amount:
                    type: number
                    example: 307.5
                  name:
                    type: string
                    description: The name this state's own document uses.
                    example: Surplus Line Premium Tax
                  source:
                    type: string
                    format: uri
                    description: The document that sets this charge.
            total_tax:
              type: number
              example: 39.75
            total_due:
              type: number
              description: premium + fees + total_tax
              example: 1289.75
            fees_taxable:
              type: number
              description: How much of the fee ended up inside the taxable base.
            fees_exempt:
              type: number
              description: How much was left out, and why is in `notes`.
        state_rules:
          type: object
          description: The state's own rules, and what this calculation did with them.
          properties:
            rounding:
              type: object
              properties:
                applied:
                  type: string
                  example: cent
                  description: What this response did.
                rule:
                  type: object
                  description: What the state requires - including whether it applies per policy or on
                    the return total. California rounds to the dollar ON THE RETURN, so a policy's tax
                    is still returned to the cent.
            fee_cap:
              type: object
              description: Any cap the state places on a broker fee, with its citation. Reported, not
                enforced against the transaction.
        notes:
        warnings:
          type: array
          items:
            type: string
          description: Where a state publishes an exemption this call cannot verify. Never silently applied.
    ErrorResponse:
      type: object
      properties:
        error:
          type: boolean
        code:
          type: string
          enum:
          - FEE_TYPE_REQUIRED
          - NO_RATES_FOR_DATE
          - UNKNOWN_STATE
        message:
          type: string
        statusCode:
          type: integer
      description: FEE_TYPE_REQUIRED - an unsplit `fees` total in a state that taxes the sides differently.
        NO_RATES_FOR_DATE - nothing on file in force on the requested date; the calculation is refused
        rather than returning 0.
    RatesResponse:
      type: object
      properties:
        success:
          type: boolean
        state:
          type: string
        state_code:
          type: string
        effective_date:
          type: string
          format: date
          description: The date the charges were resolved for.
        rates_from:
          type: string
          description: current or historical.
        charges:
          type: array
          description: Every charge in force on that date.
          items:
            type: object
            properties:
              key:
                type: string
                example: stamping_fee
              name:
                type: string
                description: The name that state's own document uses.
                example: Stamping Fee
              rate:
                type: string
                example: 0.04%
              basis:
                type: string
                enum:
                - percent
                - flat
              source:
                type: string
                format: uri
              effective_from:
                type: string
                format: date
        payment_frequency:
          type: string
          nullable: true
          description: How often the state is filed. Null where the state publishes no cadence.
        rounding_rule:
          type: string
          nullable: true
        legislative_source:
          type: string
          format: uri
        earliest_verified:
          type: string
          format: date
          description: A charge whose effective_from equals this has been in force AT LEAST since then,
            rather than having changed then.