Surplus Lines Calculator API

RESTful API Specification v1.0

Note: This is the API specification document. The actual API implementation is coming soon. To be notified when the API is available, please contact us and select "Sign up for API" as your inquiry type.

Overview

The Surplus Lines Calculator API will provide programmatic access to calculate surplus lines taxes and fees for insurance policies across all U.S. states and territories. The API will handle various state-specific rules, rounding requirements, and special cases.

Base URL

https://api.surpluslines.com/v1

Request/Response Format

All requests and responses use JSON format. Include the following headers:

{
  "Content-Type": "application/json",
  "Accept": "application/json"
}

Authentication

The API will use API key authentication. Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY
Note: API keys will be issued per organization once the API is available. Keep your API key secure and do not share it publicly.

Endpoints

GET /api/states

Retrieve a list of all supported states and territories with their tax information.

Response

200 OK

{
  "states": [
    {
      "code": "AL",
      "name": "Alabama",
      "taxRate": "6%",
      "hasSpecialOptions": false,
      "roundingRule": "Standard Rounding 50% Up 49.9% Down"
    },
    {
      "code": "AK",
      "name": "Alaska",
      "taxRate": "2.7%",
      "hasSpecialOptions": true,
      "specialOptions": ["wetMarine"],
      "roundingRule": "Standard Rounding 50% Up 49.9% Down"
    }
    // ... more states
  ]
}

GET /api/states/{stateCode}

Retrieve detailed tax information for a specific state.

Parameters

Parameter Type Required Description
stateCode string Required Two-letter state code (e.g., "CA", "NY")

Response

200 OK

{
  "state": "California",
  "stateCode": "CA",
  "taxRate": "3%",
  "fees": {
    "stampingFee": "0.18%",
    "filingFee": null,
    "serviceFee": null,
    "surcharge": null,
    "regulatoryFee": null,
    "fireMarshalTax": null,
    "slassClearinghouseFee": null,
    "flatFee": null
  },
  "specialNotes": null,
  "paymentFrequency": "Monthly or annual based on prior year tax liability",
  "roundingRule": "Record All Amounts in Whole Dollars",
  "legislativeSource": "https://www.insurance.ca.gov/...",
  "specialOptions": []
}

POST /api/calculate

Calculate surplus lines taxes and fees for a given premium amount and state.

Request Body

Parameter Type Required Description
state string Required Full state name or two-letter code
premium number Required Premium amount (must be > 0)
options object Optional State-specific options (see below)

State-Specific Options

State Option Type Description
Alaska isWetMarine boolean Apply wet marine exemption (3.7% independent procurement tax)
Illinois applyFireMarshal boolean Apply fire marshal tax
Illinois fireMarshalRate number Fire marshal tax rate (0-1%)
Iowa year string Tax year (2024, 2025, 2026, 2027+)
Montana isFire boolean Apply additional 2.5% fire insurance tax
Montana isElectronic boolean Electronic filing (waives stamping fee)
Oregon isNewRenewal boolean New or renewal policy ($10 flat fee applies)
Puerto Rico isMedicalMalpractice boolean Medical malpractice coverage (tax exempt)
South Dakota isFire boolean Fire insurance (3% rate instead of 2.5%)
Virginia isWorkersComp boolean Workers' compensation insurance (tax exempt)

Example Request

{
  "state": "Montana",
  "premium": 10000,
  "options": {
    "isFire": true,
    "isElectronic": true
  }
}

Response

200 OK

{
  "success": true,
  "calculation": {
    "state": "Montana",
    "premium": 10000,
    "items": [
      {
        "name": "Base Tax",
        "rate": "2.75%",
        "amount": 275.00,
        "unroundedAmount": 275.00
      },
      {
        "name": "Additional Fire Insurance Tax",
        "rate": "2.5%",
        "amount": 250.00,
        "unroundedAmount": 250.00
      }
    ],
    "taxesAndFeesSubtotal": 525.00,
    "total": 10525.00,
    "roundingRule": "Standard Rounding 50% Up 49.9% Down",
    "specialNotes": "Stamping fee waived for electronic filing."
  }
}

Error Response

400 Bad Request

{
  "success": false,
  "error": {
    "code": "INVALID_PREMIUM",
    "message": "Premium amount must be greater than 0"
  }
}

POST /api/report-problem

Report an issue with tax calculations or rates.

Request Body

Parameter Type Required Description
state string Required State where issue occurred
calculationDetails object Required Details of the calculation performed
problemDescription string Required Description of the issue
contactInfo object Required Contact information (name, email, company)

Response

201 Created

{
  "success": true,
  "message": "Problem report submitted successfully",
  "reportId": "RPT-2025-001234"
}

Error Handling

The API uses standard HTTP status codes and returns detailed error messages.

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {} // Optional additional details
  }
}

Common Error Codes

HTTP Status Error Code Description
400 INVALID_STATE Invalid or unsupported state code
400 INVALID_PREMIUM Premium amount is invalid or <= 0
400 INVALID_OPTIONS Invalid options for the specified state
401 UNAUTHORIZED Missing or invalid API key
404 STATE_NOT_FOUND State not found in database
429 RATE_LIMIT_EXCEEDED Too many requests
500 INTERNAL_ERROR Internal server error

Data Models

State Object

{
  "state": "string",           // Full state name
  "stateCode": "string",       // Two-letter state code
  "taxRate": "string",         // Base tax rate (e.g., "3%")
  "fees": {
    "stampingFee": "string|null",
    "filingFee": "string|null",
    "serviceFee": "string|null",
    "surcharge": "string|null",
    "regulatoryFee": "string|null",
    "fireMarshalTax": "string|null",
    "slassClearinghouseFee": "string|null",
    "flatFee": "string|null"
  },
  "specialNotes": "string|null",
  "paymentFrequency": "string|null",
  "roundingRule": "string",
  "legislativeSource": "string",
  "specialOptions": ["string"]  // Available special options for this state
}

Calculation Item Object

{
  "name": "string",              // Fee/tax name
  "rate": "string",              // Rate applied (e.g., "3%", "$10")
  "amount": "number",            // Rounded amount
  "unroundedAmount": "number"    // Original calculated amount before rounding
}

Calculation Response Object

{
  "state": "string",
  "premium": "number",
  "items": [CalculationItem],
  "taxesAndFeesSubtotal": "number",
  "total": "number",
  "roundingRule": "string",
  "specialNotes": "string|null"
}
Note on Rounding: The API respects state-specific rounding rules. Some states require rounding to whole dollars, others to the nearest cent, and some prohibit rounding. The unroundedAmount field shows the original calculation before rounding rules are applied.

HTTP Status Codes

Status Code Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Missing or invalid API key
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error

Rate Limits

The API enforces rate limits to ensure fair usage:

  • 100 requests per minute for standard accounts
  • 1000 requests per minute for enterprise accounts
  • Rate limit headers are included in all responses

Rate Limit Headers:

  • X-RateLimit-Limit - The maximum number of requests allowed
  • X-RateLimit-Remaining - The number of requests remaining
  • X-RateLimit-Reset - The time when the rate limit resets

Support

For API support and questions:

  • Email: api@surpluslines.com
  • Documentation updates: Check this page for the latest API information
  • Report issues: Use the /api/report-problem endpoint or contact support