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.

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

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 -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",
  "premium": 10000,
  "taxes": {
    "sl_tax": 485.00,
    "tax_rate": 0.0485,
    "stamping_fee": 18.00,
    "stamping_fee_rate": 0.0018
  },
  "total_tax": 503.00,
  "total_due": 10503.00
}

Rate Limits

The API has the following rate limits:

Rate limit headers are included in every response:

• X-RateLimit-Limit - Maximum requests allowed
• X-RateLimit-Remaining - Requests remaining
• X-RateLimit-Reset - Time when the limit resets (Unix timestamp)

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

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",
  "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
  }
}

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

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 rate limit errors (429 status).

State Names

Use full state names (e.g., "Texas" not "TX"). The API performs case-insensitive matching.

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:

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()}`);

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}")