API Documentation

Welcome to the Surplus Lines API documentation. This API provides accurate surplus lines tax calculations for all 50 U.S. states plus the District of Columbia.

Base URL

https://n8n.undtec.com/webhook/slapi

Authentication

All API requests (except public endpoints) require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can also use 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.

Quick Start

Here's a quick example to calculate surplus lines tax for Texas:

cURL

curl -X POST https://n8n.undtec.com/webhook/slapi/v1/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Texas",
    "premium": 10000
  }'

Response:

{
  "success": true,
  "request_id": "abc123-def456",
  "data": {
    "state": "Texas",
    "premium": 10000,
    "state_tax": 485.00,
    "state_tax_rate": 4.85,
    "stamping_fee": 18.00,
    "stamping_fee_rate": 0.18,
    "other_fees": 0,
    "flat_fees": 0,
    "total_tax": 503.00,
    "effective_rate": "5.03%",
    "breakdown": {
      "state_tax": { "rate": 4.85, "amount": 485.00 },
      "stamping_fee": { "rate": 0.18, "amount": 18.00 }
    }
  },
  "usage": {
    "was_free_query": true,
    "cost": 0,
    "remaining_free_queries": 199,
    "current_balance": "0.00"
  }
}

Rate Limits

The API has the following rate limits:

Tier	Requests per minute	Requests per day
Free Tier	60	1,000
Paid	300	50,000

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.

Request Body

Parameter	Type	Required	Description
`state`	string	Yes	Full state name (e.g., "Texas", "California")
`premium`	number	Yes	Premium amount in USD (must be positive)
`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)
`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)

Example Request

curl -X POST https://n8n.undtec.com/webhook/slapi/v1/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Florida",
    "premium": 25000,
    "fire_insurance": true
  }'

Response

{
  "success": true,
  "request_id": "uuid-here",
  "data": {
    "state": "Florida",
    "premium": 25000,
    "state_tax": 1250.00,
    "state_tax_rate": 5.0,
    "stamping_fee": 43.75,
    "stamping_fee_rate": 0.175,
    "other_fees": 0,
    "flat_fees": 0,
    "total_tax": 1293.75,
    "effective_rate": "5.175%",
    "breakdown": {
      "state_tax": { "rate": 5.0, "amount": 1250.00 },
      "stamping_fee": { "rate": 0.175, "amount": 43.75 }
    },
    "special_notes": "Fire Marshal varies",
    "payment_frequency": "Quarterly"
  },
  "usage": {
    "was_free_query": false,
    "cost": 0.38,
    "remaining_free_queries": 0,
    "current_balance": "49.62"
  }
}

GET /v1/rates

Retrieve current tax rates for all states or a specific state. This endpoint is public and does not deduct from your balance.

Query Parameters

Parameter	Type	Required	Description
`state`	string	No	Filter by state name (partial match supported)

Example Request

# Get all rates
curl https://n8n.undtec.com/webhook/slapi/v1/rates

# Get specific state
curl "https://n8n.undtec.com/webhook/slapi/v1/rates?state=Texas"

Response

{
  "success": true,
  "count": 51,
  "data": [
    {
      "state": "Alabama",
      "tax_rate": "6%",
      "stamping_fee": "",
      "filing_fee": "",
      "fire_marshal_tax": "",
      "special_notes": "",
      "payment_frequency": "Annually",
      "legislative_source": "https://law.justia.com/..."
    },
    // ... more states
  ]
}

GET /v1/states

Get a list of all supported states and territories. This endpoint is public.

Example Request

curl https://n8n.undtec.com/webhook/slapi/v1/states

Response

{
  "success": true,
  "count": 51,
  "data": [
    "Alabama",
    "Alaska",
    "Arizona",
    // ... all states
    "Wyoming"
  ]
}

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "request_id": "unique-request-id",
  "data": { ... },
  "usage": {
    "was_free_query": boolean,
    "cost": number,
    "remaining_free_queries": number,
    "current_balance": string
  }
}

Error Response

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

Error Codes

Code	HTTP Status	Description
`MISSING_API_KEY`	401	No API key provided
`INVALID_API_KEY`	401	API key is invalid or expired
`ACCOUNT_SUSPENDED`	403	Account has been suspended
`INSUFFICIENT_BALANCE`	402	Not enough balance for the request
`MISSING_STATE`	400	State parameter is required
`INVALID_PREMIUM`	400	Premium must be a positive number
`STATE_NOT_FOUND`	404	Specified state not found
`RATE_LIMIT_EXCEEDED`	429	Too many requests

State-Specific Rules

Some states have special rules that affect tax calculations:

Alaska

Wet marine coverage has a different tax rate (3.7% instead of 2.7%). 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%

Montana

Electronic filing eliminates the stamping fee. Fire insurance has an additional 2.5% tax.

South Dakota

Fire insurance has a higher tax rate (3.0% instead of 2.5%).

Virginia

Workers compensation insurance is tax exempt.

Puerto Rico

Medical malpractice coverage is tax exempt.

Best Practices

Caching

Tax rates don't change frequently. Consider caching /v1/rates responses 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.

State Names

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

Testing

Use your 200 free queries to test your integration thoroughly before going to production.