API Documentation

Welcome to the Surplus Lines Tax API documentation. This API provides accurate surplus lines tax calculations for all 50 U.S. states, the District of Columbia, Puerto Rico, and the U.S. Virgin Islands.

Base URL

https://api.surpluslinesapi.com/v1

The API is designed to provide:

  • Real-time tax rate information for all jurisdictions
  • Accurate tax calculations with state-specific rounding rules
  • Support for special coverage types (wet marine, fire insurance, etc.)
  • Detailed fee breakdowns including stamping fees, filing fees, and surcharges

Authentication

All API endpoints require authentication. Include your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Keep Your API Key Secure

Never expose your API key in client-side code or public repositories. Always make API calls from your server.

Obtaining an API Key

To get an API key:

  1. Create an account at app.surpluslinesapi.com
  2. Navigate to the API Keys section in your dashboard
  3. Generate a new API key

New accounts include 100 free API calls to get started.

Quick Start

Here's a quick example to calculate surplus lines taxes for a premium:

cURL 
curl -X POST "https://api.surpluslinesapi.com/v1/calculate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "Texas", "premium": 10000}'

Response:

{
  "success": true,
  "state": "Texas",
  "state_code": "TX",
  "premium": 10000,
  "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": [],
  "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
  }
}

State Abbreviations Supported

You can use either the full state name or the 2-letter abbreviation: "state": "TX" works the same as "state": "Texas".

POST /v1/calculate

Calculate surplus lines taxes for a specific state and premium amount. This endpoint performs calculations using the same logic as the web calculator.

Request Body

Parameter Type Required Description
state string Yes State name or 2-letter abbreviation (case-insensitive). Examples: "Texas" or "TX", "California" or "CA".
Alabama (AL), Alaska (AK), Arizona (AZ), Arkansas (AR), California (CA), Colorado (CO), Connecticut (CT), Delaware (DE), District of Columbia (DC), Florida (FL), Georgia (GA), Hawaii (HI), Idaho (ID), Illinois (IL), Indiana (IN), Iowa (IA), Kansas (KS), Kentucky (KY), Louisiana (LA), Maine (ME), Maryland (MD), Massachusetts (MA), Michigan (MI), Minnesota (MN), Mississippi (MS), Missouri (MO), Montana (MT), Nebraska (NE), Nevada (NV), New Hampshire (NH), New Jersey (NJ), New Mexico (NM), New York (NY), North Carolina (NC), North Dakota (ND), Ohio (OH), Oklahoma (OK), Oregon (OR), Pennsylvania (PA), Puerto Rico (PR), Rhode Island (RI), South Carolina (SC), South Dakota (SD), Tennessee (TN), Texas (TX), Utah (UT), Vermont (VT), Virgin Islands (VI), Virginia (VA), Washington (WA), West Virginia (WV), Wisconsin (WI), Wyoming (WY)
premium number Yes Premium amount in USD (must be positive)
effective_date string No Optional: Date for historical calculation in YYYY-MM-DD format (e.g., "2024-06-15"). Leave empty for current rates. Automatically falls back to current rates if historical data is unavailable.
wet_marine boolean No Set true for wet marine coverage (affects Alaska)
fire_insurance boolean No Set true for fire insurance (affects SD, MT)
electronic_filing boolean No Set true for electronic filing (affects MT stamping fee)
fire_marshal_rate number No Fire marshal tax rate 0-1% (Illinois only)
medical_malpractice boolean No Set true for medical malpractice (exempt in PR)
workers_comp boolean No Set true for workers comp (exempt in VA)
year integer No Tax year (affects Iowa rates 2024-2027)
new_business boolean No New/renewal policy flag (affects Oregon $10 fee)

Example Request

curl -X POST "https://api.surpluslinesapi.com/v1/calculate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Texas",
    "premium": 10000
  }'

Response

{
  "success": true,
  "state": "Texas",
  "state_code": "TX",
  "premium": 10000,
  "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": [],
  "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": 0,
    "was_free_query": false
  }
}

Example Request - Historical Calculation

curl -X POST "https://api.surpluslinesapi.com/v1/calculate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Texas",
    "premium": 10000,
    "effective_date": "2024-06-15"
  }'

Response - Historical

{
  "success": true,
  "state": "Texas",
  "state_code": "TX",
  "premium": 10000,
  "effective_date": "2024-06-15",
  "rates_from": "historical",
  "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,
    "slas_clearinghouse_fee": null,
    "flat_fee": null
  },
  "total_tax": 489,
  "total_due": 10489,
  "notes": [
    "Historical rates applied for effective date: 2024-06-15",
    "Rate period: 2024-01-01T00:00:00.000Z to current",
    "Data source: initial_migration"
  ],
  "legislative_source": "https://statutes.capitol.texas.gov/docs/IN/htm/IN.225.htm",
  "rate_period": {
    "effective_from": "2024-01-01T00:00:00.000Z",
    "effective_to": null,
    "data_source": "initial_migration"
  },
  "fallback_reason": null,
  "error_code": null,
  "error_message": null,
  "account": {
    "balance": "0.00",
    "free_queries_remaining": 618,
    "was_free_query": true
  }
}

Response Fields

Field Type Description
success boolean Whether the request was successful
state string The full state name
state_code string The 2-letter state abbreviation (e.g., "TX", "CA")
premium number The premium amount
effective_date string|null The effective date used for calculation (null if current rates used)
rates_from string Source of rates used: "current" or "historical"
breakdown object Detailed breakdown of all tax components. Each component has rate and amount fields.
breakdown.base_tax object|null Surplus lines tax component with rate (percentage string) and amount (number)
breakdown.stamping_fee object|null Stamping fee component with rate and amount
breakdown.filing_fee object|null Filing fee component with rate and amount
breakdown.service_fee object|null Service fee component with rate and amount
breakdown.surcharge object|null Surcharge component with rate and amount
breakdown.regulatory_fee object|null Regulatory fee component with rate and amount
breakdown.fire_marshal_tax object|null Fire marshal tax component with rate and amount (Illinois only)
breakdown.slas_clearinghouse_fee object|null SLAS clearinghouse fee component with rate and amount
breakdown.flat_fee object|null Flat fee component with rate and amount (e.g., Oregon $10 fee)
total_tax number Total tax amount (sum of all breakdown components)
total_due number Total amount due (premium + total_tax)
notes array Array of notes about the calculation (e.g., exemptions applied)
legislative_source string|null URL to the legal source for the state's tax rate
rate_period object|null Rate period information (only present when effective_date is provided). Contains effective_from, effective_to, and data_source fields.
fallback_reason string|null Explanation if historical rates were unavailable and current rates were used as fallback
error_code string|null Error code if the request failed
error_message string|null Error message if the request failed
account object Account billing information
account.balance string Current account balance in USD after this query (cost per query: $0.38)
account.free_queries_remaining number Number of free queries remaining
account.was_free_query boolean Whether this query used a free query credit

GET /v1/historical-rates

Retrieve historical surplus lines tax rates for any state at a specific date. Look up what tax rates were in effect on any given date to verify past calculations or audit historical policies.

Query Parameters

Parameter Type Required Description
state string Yes State name or 2-letter abbreviation (case-insensitive). Examples: "Texas" or "TX", "Iowa" or "IA"
date string No Date to look up rates for in YYYY-MM-DD format. Example: "2025-01-15". Defaults to today's date if not provided.

Example Request

curl "https://api.surpluslinesapi.com/v1/historical-rates?state=Texas&date=2024-01-02" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "state": "Texas",
  "state_code": "TX",
  "query_date": "2024-01-02",
  "rates_from": "historical",
  "rate": {
    "tax_rate": "4.85%",
    "stamping_fee": "0.04%",
    "filing_fee": "",
    "service_fee": "",
    "surcharge": "",
    "regulatory_fee": "",
    "fire_marshal_tax": "",
    "slas_clearinghouse_fee": "",
    "flat_fee": "",
    "rounding_rule": "Not Specified. We use Standard Rounding 50% Up 49.9% Down.",
    "effective_from": "2024-01-01T00:00:00.000Z",
    "effective_to": null,
    "legislative_source": "https://statutes.capitol.texas.gov/docs/IN/htm/IN.225.htm",
    "confidence": "high",
    "data_source": "initial_migration",
    "field_sources": {
      "flat_fee": "initial_migration",
      "tax_rate": "initial_migration",
      "surcharge": "initial_migration",
      "filing_fee": "initial_migration",
      "service_fee": "initial_migration",
      "stamping_fee": "initial_migration",
      "rounding_rule": "initial_migration",
      "special_notes": "initial_migration",
      "regulatory_fee": "initial_migration",
      "fire_marshal_tax": "initial_migration",
      "slas_clearinghouse_fee": "initial_migration"
    }
  },
  "special_notes": null,
  "account": {
    "balance": "0.00",
    "free_queries_remaining": 616,
    "was_free_query": true
  }
}

Example: Iowa Rate Lookup

curl "https://api.surpluslinesapi.com/v1/historical-rates?state=Iowa&date=2025-06-15" \
  -H "X-API-Key: YOUR_API_KEY"

Response (showing Iowa's 2025 rate during the phase-down period):

{
  "success": true,
  "state": "Iowa",
  "state_code": "IA",
  "query_date": "2025-06-15",
  "rates_from": "historical",
  "rate": {
    "tax_rate": "0.95%",
    "stamping_fee": "",
    "filing_fee": "",
    "service_fee": "",
    "surcharge": "",
    "regulatory_fee": "",
    "fire_marshal_tax": "",
    "slas_clearinghouse_fee": "",
    "flat_fee": "",
    "rounding_rule": "standard",
    "effective_from": "2025-01-01T00:00:00.000Z",
    "effective_to": "2025-12-31T00:00:00.000Z",
    "legislative_source": "Iowa Code ยง432A.2",
    "confidence": "high",
    "data_source": "initial_migration",
    "field_sources": {
      "tax_rate": "initial_migration",
      "stamping_fee": "initial_migration",
      "filing_fee": "initial_migration",
      "service_fee": "initial_migration",
      "surcharge": "initial_migration",
      "regulatory_fee": "initial_migration",
      "fire_marshal_tax": "initial_migration",
      "slas_clearinghouse_fee": "initial_migration",
      "flat_fee": "initial_migration",
      "rounding_rule": "initial_migration",
      "special_notes": "initial_migration"
    }
  },
  "special_notes": "Iowa's surplus lines tax is being phased down over multiple years.",
  "account": {
    "balance": "9.90",
    "free_queries_remaining": 0,
    "was_free_query": false
  }
}

Error Response

If required parameters are missing:

{
  "success": false,
  "error": "Missing required parameter: state",
  "example": "/v1/historical-rates?state=Iowa&date=2025-06-15"
}

Use Cases

  • Policy Audits: Verify that correct tax rates were applied to historical policies
  • Backdated Calculations: Calculate taxes for policies with inception dates in the past
  • Compliance Reports: Generate reports showing what rates were in effect at specific dates
  • Dispute Resolution: Confirm historical rates for billing or regulatory inquiries

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Error Codes

Code HTTP Status Description
MISSING_API_KEY 401 No API key provided for protected endpoint
INVALID_API_KEY 401 API key is invalid or expired
MISSING_STATE 400 State parameter is required
INVALID_STATE 400 Specified state not recognized
INVALID_PREMIUM 400 Premium must be a positive number
INSUFFICIENT_BALANCE 402 Account balance is too low. Add funds at app.surpluslinesapi.com
RECHARGE_FAILED 409 Auto-recharge payment failed. Check your payment method in your account settings
RATE_LIMIT_EXCEEDED 429 Too many requests, try again later
INTERNAL_ERROR 500 Internal server error

State-Specific Rules

Some states have special rules that affect tax calculations. The API handles these automatically when you provide the appropriate flags:

Alaska

Wet marine and transportation coverage has a different tax rate (3.7% independent procurement tax instead of 2.7% surplus lines tax). Set wet_marine: true in your request.

Iowa

Tax rates are being phased down from 2024-2027:

  • 2024: 0.975%
  • 2025: 0.95%
  • 2026: 0.925%
  • 2027+: 0.9%

Use the year parameter to specify which rate to apply.

Illinois

Fire marshal tax can be applied (0-1%). Set fire_marshal_rate to the applicable percentage.

Montana

Two special rules:

  • Electronic filing eliminates the stamping fee. Set electronic_filing: true.
  • Fire insurance has an additional 2.5% tax. Set fire_insurance: true.

Oregon

New and renewal policies have a $10 flat service charge. Set new_business: true (default) to include it.

South Dakota

Fire insurance has a higher tax rate (3.0% instead of 2.5%). Set fire_insurance: true.

Virginia

Workers compensation insurance is tax exempt. Set workers_comp: true.

Puerto Rico

Medical malpractice coverage is tax exempt. Set medical_malpractice: true.

Rounding Rules

Each state has specific rounding rules that the API applies automatically:

  • Arizona: No rounding permitted
  • California: Round to whole dollars
  • Illinois: Round to nearest whole dollar
  • New Jersey: No rounding permitted
  • South Carolina: Round to nearest dollar
  • Most states: Standard rounding (50% up, 49.9% down)

Best Practices

Caching

Tax rates don't change frequently. Consider caching calculation results for identical state/premium combinations for up to 24 hours to reduce API calls.

Error Handling

Always check the success field in responses. Implement retry logic with exponential backoff for transient errors.

State Names

You can use either full state names (e.g., "Texas") or 2-letter abbreviations (e.g., "TX"). Both formats are case-insensitive.

Validating Inputs

Validate premium amounts on your end before sending to the API. Ensure they are positive numbers.

Testing

For testing, use small premium amounts to verify your integration. New accounts include 100 free API calls.

SDKs and Libraries

The API is REST-based and can be called from any HTTP client. Here are examples for common languages:

JavaScript (Node.js) 
const response = await fetch('https://api.surpluslinesapi.com/v1/calculate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    state: 'California',
    premium: 25000
  })
});
const result = await response.json();
console.log(`Total: $${result.total_due.toLocaleString()}`);
Python 
import requests

headers = {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
payload = {
    'state': 'Texas',
    'premium': 50000
}
response = requests.post('https://api.surpluslinesapi.com/v1/calculate',
                         json=payload, headers=headers)
result = response.json()
print(f"Total with taxes: ${result['total_due']:,.2f}")

Need help? Contact us at support@undtec.com

© Underwriters Technologies 2025