Tax Calculations

Get instant surplus lines tax calculations and state-specific documents using JSON request.

Pull real-time surplus lines tax rates

Instant, current and accurate Surplus Lines tax rate retrieval.

Reporting Form generation

Streamline form generation and data transformation.

Compliance and Error Reduction

Mitigate compliance risks and ensure precise tax reporting.

Seamless Data Integration

Straightforward quote-to-bind data integration for efficient policy workflow.

Introduction

The Tax Calculator API enables real-time calculation of surplus lines tax rates and fees across all 50 states (plus DC, Puerto Rico, Guam, and the Virgin Islands) as well as admitted rates in the state of Kentucky through a single POST endpoint.

Submit policy details via JSON to /api/v2/tax-calculator/calculate-general-taxes and receive comprehensive tax calculations, including state-specific requirements, stamping fees, and municipal taxes. The API supports both single and multiple lines of business calculations, making it ideal for integrating accurate surplus lines tax compliance into your insurance management system.

Necessary datasheets to reference

InsCipher utilizes certain data tables outside of the documentation for every request to provide the most up to date requirements for your integration.

Depending on your configuration, you may need to reference the following tables, which will be mentioned further down in the documentation.

Feel free to open these in a new window or bookmark for future use:

Generic Lines of Business List

Document Requirements: Tax Calc API

Unique State Tax Titles

State Stamp Wording

Transaction Types List

Identify Line of Business model

Single Line of Business Tax Calculation

When your policy covers just one type of risk, use the single line of business method. This requires:

  • One line of business code (e.g., "GEN-1001")
  • Total premium amount for that line
  • All required location and policy information

Multiple Lines of Business Tax Calculation

For policies covering multiple types of risks, use the multiple lines method. Key differences:

  • Uses pipe-separated (|) values for multiple lines
  • Requires matching premium amounts for each line
  • Total premium must equal sum of all coverage amounts

Request / Response information

Before integrating with InsCipher's Tax Calculator API, click into the section specific to your Lines of Business method below and review the required fields carefully as they vary based on this calculation type and state-specific requirements, with some fields being mandatory (✓) while others depend on factors like location or transaction type.

For both non-admitted and admitted rates for the state of Kentucky, utilize the following URL (HTTP POST): https://surpluslines.inscipher.com/api/v2/tax-calculator/calculate-general-taxes

In the sections below, you'll find specific information related to required and supplemental data necessary to retrieve accurate tax rate information from InsCipher, along with JSON request and response examples.

Non-admitted / Surplus Lines rates for all U.S. states

Single Line of Business
Field NameDescriptionField TypeRequired
physical_stateAbbreviation of the physical state or tax state of the policy. Format should be in 2 digits following the USPS code post-1963.String (2)
line_of_businessGeneric Line of business import code, in the format 'GEN-1014', etc. State-specific lines of business codes are also available. If you want to see how the generic lines of business codes map to state-specific lines of business codes, refer to this matrixstring
transaction_typeTransaction type code for state-specific tax rules. For a list of accepted transaction types, refer to this matrix under 'Import Codes'.String (3)
premiumFor single lines of business tax calculations: Total premium excluding any policy or carrier fees.decimal (12,2)
agency_feeTotal fees charged by brokerage that are not considered an underwriting or carrier fee. Ex: Broker Fee, policy, filing, processing fees. If passing along Surplus Lines Filing Fee, that charge would be included here.decimal (12,2)
inspection_fee Total of all fees from the carrier or part of the carrier underwriting process (inspection, audit, underwriting fees, protection code lookup costs, etc.).decimal (12,2)
policy_effective_date Policy effective date format. This helps determine tax rules from year to year and follows the tax calculator logic of the return of tax rules by date active from and date active to. If omitted, current date is used to calculate tax and fee return amounts.date (yyyy-mm-dd)
rpgRisk Purchasing Group flag (0=No, 1=Yes). Default to 0 if not applicable.tinyint (1)
account_written_asDo you write directly to the insured or through a retail agent (as a Broker)? Business writing type (DC=Direct Client, B=Brokerage). Default to B if unknown.String (2)
tax_exemptsTax Exempt? 0 - No, 1 - Yes. Applicable only for certain workflows. Typically this will allways be 0.tinyint (1)
ecpExempt Commercial Purchaser (ECP)? 0 - No, 1 - Yes. If you don't know, then make this value "0".tinyint (1)
export_listline of business on the export list? 0 - No 1 - Yes. Applicable only if you know the line of business is on a state export list. This is applicable for documents.tinyint (1)
commission_received0 - No 1-Yes Applicable only for New Hampshire's fee restrictions.tinyint (1)
mailing_entity_typeOnly applies to SC, NC, TN & FL. This field is called 'insured_entity' in transaction import. Code = Name. individual = Individual. commercial = Commercial. governmental = Governmental. federal = Federal Credit Union. tribal = Tribal Lands. hospital_alliance = Hospital Alliance. state_approved_tax_exempt = State Approved Tax Exempt Entity. Notification for future states will occur as they apply.varchar (25)
mailing_insured_emailThe email of the mailing insured.varchar (100)
mailing_insured_phoneThe phone number of the mailing insured.varchar (25)
mailing_countyThe county of the mailing insured.varchar (100)
layered_risktinyint (1)
risk_retention_grouptinyint (1)
broker_of_record_changetinyint (1)
Multiple Lines of Business
Field NameDescriptionField TypeRequired
physical_stateAbbreviation of the physical state or tax state of the policy. Format should be in 2 digits following the USPS code post-1963.String (2)
transaction_typeTransaction type code for state-specific tax rules. For a list of accepted transaction types, refer to this matrix under 'Import Codes'.String (3)
premiumFor single lines of business tax calculations: Total premium excluding any policy or carrier fees.decimal (12,2)
agency_feeTotal fees charged by brokerage that are not considered an underwriting or carrier fee. Ex: Broker Fee, policy, filing, processing fees. If passing along Surplus Lines Filing Fee, that charge would be included here.decimal (12,2)
inspection_fee Total of all fees from the carrier or part of the carrier underwriting process (inspection, audit, underwriting fees, protection code lookup costs, etc.).decimal (12,2)
policy_effective_date Policy effective date format. This helps determine tax rules from year to year and follows the tax calculator logic of the return of tax rules by date active from and date active to. If omitted, current date is used to calculate tax and fee return amounts.date (yyyy-mm-dd)
transaction_line_of_business_listDepends if state requires line of business breakdown. Recommend importing all transactions with multiple LOB's. If Multiple Lines of Business applies, then use the line of business list breakdown. Multiple values are separated by a pipe symbol "|".String (3)
transaction_line_of_business_coverageDepends on if multiple insurance companies are allowed in particular state. Only applicable if there are multiple lines of business. The line of business list breakdown is by premium values. List them in the same order as transaction_line_of_business_list. Multiple values are separated by pipe symbol "|". decimal (12,2)
rpgRisk Purchasing Group flag (0=No, 1=Yes). Default to 0 if not applicable.tinyint (1)
account_written_asDo you write directly to the insured or through a retail agent (as a Broker)? Business writing type (DC=Direct Client, B=Brokerage). Default to B if unknown.String (2)
tax_exemptsTax Exempt? 0 - No, 1 - Yes. Applicable only for certain workflows. Typically this will allways be 0.tinyint (1)
ecpExempt Commercial Purchaser (ECP)? 0 - No, 1 - Yes. If you don't know, then make this value "0".tinyint (1)
export_listline of business on the export list? 0 - No 1 - Yes. Applicable only if you know the line of business is on a state export list. This is applicable for documents.tinyint (1)
commission_received0 - No 1-Yes Applicable only for New Hampshire's fee restrictions.tinyint (1)
mailing_entity_typeOnly applies to SC, NC, TN & FL. This field is called 'insured_entity' in transaction import. Code = Name. individual = Individual. commercial = Commercial. governmental = Governmental. federal = Federal Credit Union. tribal = Tribal Lands. hospital_alliance = Hospital Alliance. state_approved_tax_exempt = State Approved Tax Exempt Entity. Notification for future states will occur as they apply.varchar (25)
mailing_insured_emailThe email of the mailing insured.varchar (100)
mailing_insured_phoneThe phone number of the mailing insured.varchar (25)
mailing_countyThe county of the mailing insured.varchar (100)
layered_risktinyint (1)
risk_retention_grouptinyint (1)
broker_of_record_changetinyint (1)

Admitted rates - Kentucky

Overview
Field NameDescriptionField TypeRequired
admittedFor getting Admitted/Premium tax rates, set this value to "1"integer
physical_stateAbbreviation of the physical state or tax state of the policy. In this case, only "KY" is accepted value.string (2)
physical_addressThe physical address of where the majority of the risk resides.varchar (255)
physical_cityThe physical city of where the majority of the risk resides.varchar (100)
physical_zip_codeThe physical zip code of where the majority of the risk resides.varchar (5)
line_of_businessThe type or line of business (aka coverage code). Refer to Line of Business datasheet for the full list of accepted values.string (10)
transaction_typeTransaction type code for state-specific tax rules. Refer to Transaction Types datasheet for the full list of accepted values.string (3)
premiumGross premium on the policy.decimal (12,2)
agency_feeTotal fees charged by brokerage (policy, filing, processing fees).decimal (12,2)
inspection_feeTotal fees charged by carrier (inspection, audit, underwriting fees).decimal (12,2)
commission_received0 - No 1-Yes Applicable only for New Hampshire's fee restrictions.tinyint (1)

Errors

InsCipher uses conventional HTTP response codes to indicate the success or failure of an API request. In general, 2xx codes indicate success, 4xx codes indicate a failure due to invalid information provided or issues with authorization, and 5xx codes indicate server errors.

For example - unauthorized usage of the Tax Calculator API will result in the following error:

{
  "error": {
    "code": "Unauthorized access",
    "status": 401,
    "message": "Insufficient permissions to access this API endpoint"
  }
}

FAQ's

Documents

How are Documents returned via this endpoint?

Documents returned using this method will be returned in one of two ways:

  1. Blank document templates: These will be returned as links where blank state forms can be downloaded
  2. Required documents for submission: This will not be a downloadable file, but rather this is informational in nature letting the user know if this document is required or not for submission with the rest of the policy detail. For a quick summary of document requirements, you can refer to the Document Requirements datasheet.

Generic Lines of Business

How do Generic Lines of Business Import Codes work?

InsCipher maintains a list of active coverage lists by state. To simplify the import process, we do not expect you to determine what these codes are on import. Instead, we have created Generic Import codes for you to use which can be found on the Generic Lines of Business List datasheet.

On the sheet, the generic codes (GEN-XXXX) are listed with the orange headers on the left side of the sheet. To the right, you will see state-specific codes listed with blue headers. If you import using the generic codes, then our system will automatically associate the transaction to the proper state-specific line of business upon import according to the mapping. It is your responsibility to review the mapping and to determine if there are additional generic codes that need to be mapped or altered.

InsCipher will accommodate adding generic codes for you as part of the implementation process. These need to be requested via email and in one single request for all adjustments needed. If changes to this mapping are requested after implementation, clients will be charged an hourly rate to add these codes as it can be a time-consuming process.

Tax Titles

How should I be understanding tax titles?

There are some states where field names are repurposed for state-specific definitions of taxes and/or state fees. For a summary of these tax titles, refer to the Unique State Tax Titles datasheet.