{ "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.\n\nHOW THE CALCULATION IS DRIVEN\n- 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.\n- `lob` selects the line of business. States exempt or re-rate particular coverages.\n- `effective_date` resolves the charges in force on that date, past or future, including scheduled changes.\n- `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.\n- 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": "Sandbox - no API key checked, sandbox data" }, { "url": "https://api.surpluslinesapi.com/v1", "description": "Production" } ], "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.\n\n**State-Specific Features:**\n- Alaska: Wet marine coverage uses independent procurement tax rate\n- Iowa: Tax rates phase down 2024-2027\n- Illinois: Optional fire marshal tax (0-1%)\n- Montana: Electronic filing eliminates stamping fee; fire insurance has additional tax\n- Oregon: New/renewal policies include $10 service charge\n- South Dakota: Fire insurance has higher tax rate\n- Virginia: Workers compensation is tax exempt\n- 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": { "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": { "type": "array", "items": { "type": "string" }, "description": "Why the fee was taxed or exempted, with the authority." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Where a state publishes an exemption this call cannot verify. Never silently applied." }, "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" } } } } } }, "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." } } } } } }