{ "info": { "name": "Surplus Lines Tax API (SANDBOX)", "description": "Surplus Lines Tax API. The \"Calculate - fee sides, coverage, any date\" folder exercises the calculation core directly; the remaining folders call the billed endpoint.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "version": "1.0.0" }, "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key", "type": "string" }, { "key": "value", "value": "{{api_key}}", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "variable": [ { "key": "base_url", "value": "https://n8nsandbox.undtec.com/webhook/slapi/internal/v3", "type": "string" }, { "key": "api_key", "value": "YOUR_API_KEY_HERE", "type": "string" } ], "item": [ { "name": "Calculate - fee sides, coverage, any date", "description": "The calculation core. No API key required on this host. These five requests are the inputs that change the answer: who charged the fee, which coverage, and when.", "item": [ { "name": "Insurer required the fee - taxed", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"California\",\n \"premium\": 1000,\n \"carrier_fees\": 250,\n \"lob\": \"SLT-PROP\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://n8nsandbox.undtec.com/webhook/slapi/internal/v3/calculate", "protocol": "https", "host": [ "n8nsandbox", "undtec", "com" ], "path": [ "webhook", "slapi", "internal", "v3", "calculate" ] }, "description": "Expect total_tax 39.75 - the fee is inside the base (3% + 0.18% on 1,250)." }, "response": [] }, { "name": "Broker charges the fee - not taxed in California", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"California\",\n \"premium\": 1000,\n \"broker_fees\": 250,\n \"lob\": \"SLT-PROP\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://n8nsandbox.undtec.com/webhook/slapi/internal/v3/calculate", "protocol": "https", "host": [ "n8nsandbox", "undtec", "com" ], "path": [ "webhook", "slapi", "internal", "v3", "calculate" ] }, "description": "Expect total_tax 31.80. Same money, one field different. fees_exempt shows 250 and notes cites the Department bulletin that puts a negotiated broker fee outside taxable premium." }, "response": [] }, { "name": "Unsplit fee - refused, not guessed", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"California\",\n \"premium\": 1000,\n \"fees\": 250\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://n8nsandbox.undtec.com/webhook/slapi/internal/v3/calculate", "protocol": "https", "host": [ "n8nsandbox", "undtec", "com" ], "path": [ "webhook", "slapi", "internal", "v3", "calculate" ] }, "description": "Expect FEE_TYPE_REQUIRED. California taxes the two sides differently, so a single total cannot be priced. In the 43 jurisdictions that treat them alike, `fees` is accepted." }, "response": [] }, { "name": "As of a past date", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"California\",\n \"premium\": 1000,\n \"carrier_fees\": 250,\n \"effective_date\": \"2022-06-01\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://n8nsandbox.undtec.com/webhook/slapi/internal/v3/calculate", "protocol": "https", "host": [ "n8nsandbox", "undtec", "com" ], "path": [ "webhook", "slapi", "internal", "v3", "calculate" ] }, "description": "Expect the stamping fee at 0.25%, the rate in force before 2023 - total_tax 40.63." }, "response": [] }, { "name": "Kentucky with a jurisdiction", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Kentucky\",\n \"premium\": 1000,\n \"carrier_fees\": 250,\n \"jurisdiction\": \"1017\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://n8nsandbox.undtec.com/webhook/slapi/internal/v3/calculate", "protocol": "https", "host": [ "n8nsandbox", "undtec", "com" ], "path": [ "webhook", "slapi", "internal", "v3", "calculate" ] }, "description": "The local government premium tax is set by 417 Kentucky jurisdictions and often exceeds the state tax. Without `jurisdiction` the response says it was excluded rather than returning a short figure." }, "response": [] } ] }, { "name": "Tax Calculations", "item": [ { "name": "Basic Tax Calculation", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Texas\",\n \"premium\": 10000\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Calculate surplus lines taxes for Texas with a $10,000 premium" }, "response": [ { "name": "Success Response - Texas", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Texas\",\n \"state_code\": \"TX\",\n \"premium\": 10000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": {\n \"rate\": \"4.85%\",\n \"amount\": 485\n },\n \"stamping_fee\": {\n \"rate\": \"0.04%\",\n \"amount\": 4\n },\n \"filing_fee\": null,\n \"service_fee\": null,\n \"surcharge\": null,\n \"regulatory_fee\": null,\n \"fire_marshal_tax\": null\n },\n \"total_tax\": 489,\n \"total_due\": 10489,\n \"notes\": [],\n \"legislative_source\": \"https://statutes.capitol.texas.gov/docs/IN/htm/IN.225.htm\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"error_code\": null,\n \"error_message\": null,\n \"account\": {\n \"balance\": \"9.62\",\n \"free_queries_remaining\": 99,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Calculate California Tax", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"California\",\n \"premium\": 25000\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Calculate surplus lines taxes for California (note: California rounds to whole dollars)" }, "response": [ { "name": "Success Response - California", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"California\",\n \"state_code\": \"CA\",\n \"premium\": 25000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": {\n \"rate\": \"3%\",\n \"amount\": 750\n },\n \"stamping_fee\": {\n \"rate\": \"0.18%\",\n \"amount\": 45\n },\n \"filing_fee\": null\n },\n \"total_tax\": 795,\n \"total_due\": 25795,\n \"notes\": [\"California rounds tax calculations to whole dollars\"],\n \"legislative_source\": \"https://leginfo.legislature.ca.gov/\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"account\": {\n \"balance\": \"9.90\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Calculate Florida Tax", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Florida\",\n \"premium\": 50000\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Calculate surplus lines taxes for Florida" }, "response": [ { "name": "Success Response - Florida", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Florida\",\n \"state_code\": \"FL\",\n \"premium\": 50000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": {\n \"rate\": \"5%\",\n \"amount\": 2500\n },\n \"stamping_fee\": {\n \"rate\": \"0.2%\",\n \"amount\": 100\n },\n \"filing_fee\": null\n },\n \"total_tax\": 2600,\n \"total_due\": 52600,\n \"notes\": [],\n \"legislative_source\": \"http://www.leg.state.fl.us/Statutes/\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"account\": {\n \"balance\": \"9.85\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Calculate New York Tax", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"New York\",\n \"premium\": 100000\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Calculate surplus lines taxes for New York" }, "response": [ { "name": "Success Response - New York", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"New York\",\n \"state_code\": \"NY\",\n \"premium\": 100000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": {\n \"rate\": \"3.6%\",\n \"amount\": 3600\n },\n \"stamping_fee\": {\n \"rate\": \"0.06%\",\n \"amount\": 60\n },\n \"filing_fee\": null\n },\n \"total_tax\": 3660,\n \"total_due\": 103660,\n \"notes\": [],\n \"legislative_source\": \"https://www.nysenate.gov/legislation/laws/INS\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"account\": {\n \"balance\": \"9.80\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] } ] }, { "name": "Special Coverage Types", "item": [ { "name": "Alaska - Wet Marine Coverage", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Alaska\",\n \"premium\": 50000,\n \"wet_marine\": true\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Alaska wet marine coverage uses 3.7% independent procurement tax instead of 2.7% surplus lines tax" }, "response": [ { "name": "Success Response - Alaska Wet Marine", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Alaska\",\n \"state_code\": \"AK\",\n \"premium\": 50000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": {\n \"rate\": \"3.7%\",\n \"amount\": 1850\n },\n \"stamping_fee\": null,\n \"filing_fee\": null\n },\n \"total_tax\": 1850,\n \"total_due\": 51850,\n \"notes\": [\"Wet marine coverage uses independent procurement tax rate (3.7%)\"],\n \"legislative_source\": \"http://www.legis.state.ak.us/basis/statutes.asp\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"account\": {\n \"balance\": \"9.75\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Montana - Fire Insurance + Electronic Filing", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Montana\",\n \"premium\": 25000,\n \"fire_insurance\": true,\n \"electronic_filing\": true\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Montana fire insurance has additional 2.5% tax. Electronic filing eliminates stamping fee." }, "response": [ { "name": "Success Response - Montana Fire + Electronic", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Montana\",\n \"state_code\": \"MT\",\n \"premium\": 25000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": {\n \"rate\": \"2.75%\",\n \"amount\": 687.5\n },\n \"stamping_fee\": null,\n \"fire_marshal_tax\": {\n \"rate\": \"2.5%\",\n \"amount\": 625\n },\n \"filing_fee\": null\n },\n \"total_tax\": 1312.5,\n \"total_due\": 26312.5,\n \"notes\": [\"Fire insurance includes additional 2.5% tax; Electronic filing eliminates stamping fee\"],\n \"legislative_source\": \"https://leg.mt.gov/bills/mca/title_0330/chapters_index.html\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"account\": {\n \"balance\": \"9.70\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "South Dakota - Fire Insurance", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"South Dakota\",\n \"premium\": 30000,\n \"fire_insurance\": true\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "South Dakota fire insurance has 3.0% tax rate instead of standard 2.5%" }, "response": [ { "name": "Success Response - SD Fire Insurance", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"South Dakota\",\n \"state_code\": \"SD\",\n \"premium\": 30000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": {\n \"rate\": \"3%\",\n \"amount\": 900\n },\n \"stamping_fee\": null,\n \"filing_fee\": null\n },\n \"total_tax\": 900,\n \"total_due\": 30900,\n \"notes\": [\"Fire insurance policies use higher tax rate (3% vs standard 2.5%)\"],\n \"legislative_source\": \"https://sdlegislature.gov/Statutes/Codified_Laws/\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"account\": {\n \"balance\": \"9.65\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Illinois - With Fire Marshal Tax", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Illinois\",\n \"premium\": 100000,\n \"fire_marshal_rate\": 0.005\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Illinois allows optional fire marshal tax (0-1%). This example uses 0.5%." }, "response": [ { "name": "Success Response - Illinois Fire Marshal", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Illinois\",\n \"state_code\": \"IL\",\n \"premium\": 100000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": {\n \"rate\": \"3.5%\",\n \"amount\": 3500\n },\n \"stamping_fee\": {\n \"rate\": \"0.15%\",\n \"amount\": 150\n },\n \"fire_marshal_tax\": {\n \"rate\": \"0.5%\",\n \"amount\": 500\n },\n \"filing_fee\": null\n },\n \"total_tax\": 4150,\n \"total_due\": 104150,\n \"notes\": [\"Optional fire marshal tax (0-1%) included\"],\n \"legislative_source\": \"https://www.ilga.gov/legislation/ilcs/ilcs.asp\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"account\": {\n \"balance\": \"9.60\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Virginia - Workers Compensation (Exempt)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Virginia\",\n \"premium\": 75000,\n \"workers_comp\": true\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Virginia workers compensation is tax exempt" }, "response": [ { "name": "Success Response - VA Workers Comp", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Virginia\",\n \"state_code\": \"VA\",\n \"premium\": 75000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": null,\n \"stamping_fee\": null,\n \"filing_fee\": null\n },\n \"total_tax\": 0,\n \"total_due\": 75000,\n \"notes\": [\"Workers compensation policies are tax exempt in Virginia\"],\n \"legislative_source\": \"https://law.lis.virginia.gov/vacode/\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"account\": {\n \"balance\": \"9.55\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Puerto Rico - Medical Malpractice (Exempt)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Puerto Rico\",\n \"premium\": 200000,\n \"medical_malpractice\": true\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Puerto Rico medical malpractice coverage is tax exempt" }, "response": [ { "name": "Success Response - PR Medical Malpractice", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Puerto Rico\",\n \"state_code\": \"PR\",\n \"premium\": 200000,\n \"effective_date\": null,\n \"rates_from\": \"current\",\n \"breakdown\": {\n \"base_tax\": null,\n \"stamping_fee\": null,\n \"filing_fee\": null\n },\n \"total_tax\": 0,\n \"total_due\": 200000,\n \"notes\": [\"Medical malpractice policies are tax exempt in Puerto Rico\"],\n \"legislative_source\": \"https://bvirtualogp.pr.gov/ogp/\",\n \"rate_period\": null,\n \"fallback_reason\": null,\n \"account\": {\n \"balance\": \"9.50\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Iowa - 2025 Tax Year", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Iowa\",\n \"premium\": 40000,\n \"year\": 2025\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Iowa tax rates phase down 2024-2027. 2025 rate is 0.95%." }, "response": [ { "name": "Success Response - Iowa 2025", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Iowa\",\n \"premium\": 40000,\n \"taxes\": {\n \"sl_tax\": 380.00,\n \"tax_rate\": 0.0095,\n \"stamping_fee\": 0,\n \"stamping_fee_rate\": 0,\n \"filing_fee\": 0,\n \"filing_fee_rate\": 0\n },\n \"total_tax\": 380.00,\n \"total_due\": 40380.00,\n \"billing\": {\n \"charged\": 0.05,\n \"was_free_query\": false,\n \"remaining_balance\": 9.45,\n \"free_queries_remaining\": 0\n }\n}" } ] }, { "name": "Oregon - New Business", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Oregon\",\n \"premium\": 15000,\n \"new_business\": true\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Oregon new/renewal policies include a $10 service charge" }, "response": [ { "name": "Success Response - Oregon New Business", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Oregon\",\n \"premium\": 15000,\n \"taxes\": {\n \"sl_tax\": 337.50,\n \"tax_rate\": 0.0225,\n \"stamping_fee\": 0,\n \"stamping_fee_rate\": 0,\n \"service_charge\": 10.00,\n \"filing_fee\": 0,\n \"filing_fee_rate\": 0\n },\n \"total_tax\": 347.50,\n \"total_due\": 15347.50,\n \"billing\": {\n \"charged\": 0.05,\n \"was_free_query\": false,\n \"remaining_balance\": 9.40,\n \"free_queries_remaining\": 0\n }\n}" } ] } ] }, { "name": "Historical Rates", "item": [ { "name": "Get Historical Rate - Texas", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/historical-rates?state=Texas&date=2025-01-01", "host": [ "{{base_url}}" ], "path": [ "historical-rates" ], "query": [ { "key": "state", "value": "Texas" }, { "key": "date", "value": "2025-01-01" } ] }, "description": "Get historical tax rates for Texas on January 1, 2025" }, "response": [ { "name": "Success Response - Texas", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Texas\",\n \"state_code\": \"TX\",\n \"effective_date\": \"2025-01-01\",\n \"rates_from\": \"historical\",\n \"charges\": [\n {\n \"key\": \"sl_tax\",\n \"name\": \"Surplus Lines Premium Tax\",\n \"rate\": \"4.85%\",\n \"basis\": \"percent\",\n \"source\": \"https://comptroller.texas.gov/taxes/insurance/surplus-lines.php\",\n \"effective_from\": \"2020-01-01\"\n },\n {\n \"key\": \"stamping_fee\",\n \"name\": \"Stamping Fee\",\n \"rate\": \"0.04%\",\n \"basis\": \"percent\",\n \"source\": \"https://www.sltx.org/brokers/billing-information/stamping-fees-taxes/\",\n \"effective_from\": \"2024-01-01\"\n }\n ],\n \"payment_frequency\": null,\n \"rounding_rule\": \"Whole dollars for premium, cents for the tax on the return total, not per policy. (Tex. Form 25-104 (printed column headings))\",\n \"legislative_source\": \"https://comptroller.texas.gov/taxes/insurance/surplus-lines.php\",\n \"earliest_verified\": \"2020-01-01\",\n \"account\": {\n \"balance\": \"9.62\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Get Historical Rate - Iowa (Phase-down Period)", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/historical-rates?state=Iowa&date=2025-06-15", "host": [ "{{base_url}}" ], "path": [ "historical-rates" ], "query": [ { "key": "state", "value": "Iowa" }, { "key": "date", "value": "2025-06-15" } ] }, "description": "Get Iowa's rate during the 2025 phase-down period" }, "response": [ { "name": "Success Response - Iowa 2025", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"Iowa\",\n \"state_code\": \"IA\",\n \"effective_date\": \"2025-06-15\",\n \"rates_from\": \"historical\",\n \"charges\": [\n {\n \"key\": \"sl_tax\",\n \"name\": \"Premium Tax\",\n \"rate\": \"0.95%\",\n \"basis\": \"percent\",\n \"source\": \"https://www.legis.iowa.gov/docs/code/432.1.pdf\",\n \"effective_from\": \"2025-01-01\"\n }\n ],\n \"payment_frequency\": null,\n \"rounding_rule\": null,\n \"legislative_source\": \"https://www.legis.iowa.gov/docs/code/432.1.pdf\",\n \"earliest_verified\": \"2020-01-01\",\n \"account\": {\n \"balance\": \"9.62\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Get Historical Rate - California", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/historical-rates?state=California&date=2024-03-15", "host": [ "{{base_url}}" ], "path": [ "historical-rates" ], "query": [ { "key": "state", "value": "California" }, { "key": "date", "value": "2024-03-15" } ] }, "description": "Get California's rate on a specific date in 2024" }, "response": [ { "name": "Success Response - California", "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"state\": \"California\",\n \"state_code\": \"CA\",\n \"effective_date\": \"2024-03-15\",\n \"rates_from\": \"historical\",\n \"charges\": [\n {\n \"key\": \"sl_tax\",\n \"name\": \"Surplus Line Premium Tax\",\n \"rate\": \"3%\",\n \"basis\": \"percent\",\n \"source\": \"https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?lawCode=INS§ionNum=1775.5\",\n \"effective_from\": \"2020-01-01\"\n },\n {\n \"key\": \"stamping_fee\",\n \"name\": \"Stamping Fee\",\n \"rate\": \"0.18%\",\n \"basis\": \"percent\",\n \"source\": \"https://www.slacal.com/resources/broker-taxes-fees\",\n \"effective_from\": \"2023-01-01\"\n }\n ],\n \"payment_frequency\": \"Monthly or annual based on prior year tax liability\",\n \"rounding_rule\": \"Rounded to the nearest dollar on the return total, not per policy. (Cal. Dep't of Insurance Form FS-006, surplus line broker tax return instructions (2025 rev. 11))\",\n \"legislative_source\": \"https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?lawCode=INS§ionNum=1775.5\",\n \"earliest_verified\": \"2020-01-01\",\n \"account\": {\n \"balance\": \"9.62\",\n \"free_queries_remaining\": 0,\n \"was_free_query\": false\n }\n}" } ] }, { "name": "Error - Missing State Parameter", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/historical-rates?date=2025-01-01", "host": [ "{{base_url}}" ], "path": [ "historical-rates" ], "query": [ { "key": "date", "value": "2025-01-01" } ] }, "description": "Example of error when state parameter is missing" }, "response": [ { "name": "Error Response - Missing State", "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"code\": \"MISSING_STATE\",\n \"message\": \"state is required. Send a two-letter code or a full name.\",\n \"statusCode\": 400\n}" } ] }, { "name": "Error - Missing Date Parameter", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/historical-rates?state=Texas", "host": [ "{{base_url}}" ], "path": [ "historical-rates" ], "query": [ { "key": "state", "value": "Texas" } ] }, "description": "Example of error when date parameter is missing" }, "response": [ { "name": "Error Response - Missing Date", "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": true,\n \"code\": \"MISSING_DATE\",\n \"message\": \"date is required, as YYYY-MM-DD.\",\n \"statusCode\": 400\n}" } ] } ] }, { "name": "Error Examples", "item": [ { "name": "Missing State Parameter", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"premium\": 10000\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Example of 400 Bad Request error when state is missing" }, "response": [ { "name": "Error Response - Missing State", "status": "Bad Request", "code": 400, "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"MISSING_STATE\",\n \"message\": \"State parameter is required\"\n }\n}" } ] }, { "name": "Invalid State Name", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Texass\",\n \"premium\": 10000\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Example of 400 Bad Request error with invalid state name" }, "response": [ { "name": "Error Response - Invalid State", "status": "Bad Request", "code": 400, "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"INVALID_STATE\",\n \"message\": \"Specified state not recognized\"\n }\n}" } ] }, { "name": "Invalid Premium (Negative)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Texas\",\n \"premium\": -500\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Example of 400 Bad Request error with negative premium" }, "response": [ { "name": "Error Response - Invalid Premium", "status": "Bad Request", "code": 400, "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"INVALID_PREMIUM\",\n \"message\": \"Premium must be a positive number\"\n }\n}" } ] }, { "name": "Missing API Key", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"state\": \"Texas\",\n \"premium\": 10000\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Example of 401 Unauthorized error when API key is missing" }, "response": [ { "name": "Error Response - Missing API Key", "status": "Unauthorized", "code": 401, "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"MISSING_API_KEY\",\n \"message\": \"No API key provided for protected endpoint\"\n }\n}" } ] }, { "name": "Invalid API Key", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-API-Key", "value": "invalid-key-12345" } ], "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"state\": \"Texas\",\n \"premium\": 10000\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Example of 401 Unauthorized error with invalid API key" }, "response": [ { "name": "Error Response - Invalid API Key", "status": "Unauthorized", "code": 401, "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"INVALID_API_KEY\",\n \"message\": \"API key is invalid or expired\"\n }\n}" } ] }, { "name": "Rate Limit Exceeded", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"state\": \"Texas\",\n \"premium\": 10000\n}" }, "url": { "raw": "{{base_url}}/calculate", "host": [ "{{base_url}}" ], "path": [ "calculate" ] }, "description": "Example of 429 Too Many Requests error" }, "response": [ { "name": "Error Response - Rate Limit", "status": "Too Many Requests", "code": 429, "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"RATE_LIMIT_EXCEEDED\",\n \"message\": \"Too many requests, try again later\"\n }\n}" } ] } ] } ] }