Tax Calculator API®
Get instant surplus lines tax calculations and state-specific documents using JSON request.
Introduction
Maintaining surplus lines tax compliance has never been easier. With InsCipher's Tax API®, you'll be able to retrieve surplus lines tax calculations and documents for all 50 states (plus the District of Columbia, Puerto Rico, Guam, and the Virgin Islands) and have these rates delivered right back into your AMS, Quote/Bind, or rating system.
🌟 PREMIUM ENDPOINT:
Access to this endpoint is subject to an extra fee. Contact our Sales Team for more information.
Access to this endpoint is subject to an extra fee. Contact our Sales Team for more information.
TIP:
There are different methods or approaches to retrieving tax calculations using InsCipher's Access REST API. If you need a quick solution to test out an import and do not currently have one, consider utilizing Postman.
Note:
- Field Requirements:
We recommend that you add ALL fields marked as Required = ✓ in the field tables below. If there are values that do not exist in your agency system, you may need to hard code these as null and manually add the data after import.
Before Getting Started:
InsCipher utilizes 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:
Kentucky Insurance Tax Calculations
InsCipher can calculate BOTH admitted and non-admitted insurance tax rates for the state of Kentucky. The article below is specific to surplus lines tax rates. For admitted (Premium) tax rates, please refer to this other article:
Request Method
Authentication and URL
A user is authenticated using an API key, which is provided by your InsCipher implementation specialist. The API key is typically around 40 characters.
API Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
HTTP Method: POST
There are two options for passing through your API key:
- Include API key in the header (recommended)
- Include API key in the URL
Method 1: URL Endpoint (API key in Header):
https://surpluslines.inscipher.com/api/tax-calculator/calculate-general-taxes
If you are using the header method (default for new users), ensure that the API key is included in the header.
Example:
Method 2: URL Endpoint (API Key in URL):
Example:
JSON Request Sample
NOTE:
We allow for single or multiple lines of business tax calculations. If you write multiple lines of business consistently, we recommend that you always use the multiple lines of the business JSON request option. This is to make it standardized for you across the board. Then if there is a single coverage, then set the value of the coverage amount to be the total premium amount.
Single Line of Business Tax Calculations
{
"physical_state" : "KY",
"physical_address": "1110 Sparks Rd",
"physical_city" : "Lexington",
"physical_zip_code": "40505",
"line_of_business" : "GEN-1001",
"policy_effective_date" : "2019-04-01",
"transaction_type" : "PN",
"premium" : 1000.55,
"agency_fee" : 100,
"inspection_fee" : 200,
"commission_received": 0,
"rpg" : 0,
"ecp" : 1,
"account_written_as" : "DC"
}
Multiple Line of Business Tax Calculations
{
"physical_state" : "KY",
"physical_address": "1110 Sparks Rd",
"physical_city" : "Lexington",
"physical_zip_code": "40505",
"transaction_line_of_business_list": "GEN-1001|GEN-1002|GEN-1003",
"transaction_line_of_business_coverage": "500.55|200.25|299.75",
"policy_effective_date" : "2019-04-01",
"transaction_type" : "PN",
"agency_fee" : 100,
"inspection_fee" : 200,
"commission_received": 0,
"rpg" : 0,
"ecp" : 1,
"account_written_as" : "DC"
}
Field Descriptions and Requirements (REQUEST)
Tip
Not every field is necessary to get surplus lines taxes returned. However, we strongly recommend providing a complete dataset whenever possible to ensure you are getting back the most accurate and complete data. Surplus lines taxes can and do vary by state, line of business, policy effective dates, rpgs, etc.
| Field Name | Description | Field Type | Required |
|---|---|---|---|
| physical_state | Abbreviation of the physical state or the tax state of the policy. Format should be in 2 digits following the USPS code post-1963. | String (2) | ✓ |
| physical_address | The physical address of where the majority of the risk resides. This is ONLY used to calculate the municipality jurisdiction and the municipal tax (LGPT) for Kentucky. | varchar (255) | Depends |
| physical_city | The physical city of where the majority of the risk resides. This is ONLY used to calculate the municipality jurisdiction and the municipal tax (LGPT) for Kentucky. | varchar (100) | Depends |
| physical_zip_code | The five-digit zip code of where the majority of the risk resides. This is ONLY used to calculate the municipality jurisdiction and the municipal tax (LGPT) for Kentucky. | varchar (5) | Depends |
| line_of_business | For single lines of business tax calculations: Line of business code related to the policy. The reason why this is mandatory is that there are some states that have coverage-specific tax rules. Instead of using the state-specific codes, we suggest using one of the generic codes which we have defined on this list. The generic codes appear with a "GEN-" prefix. More detail on how these work can be found below. | string | Depends |
| premium | For single lines of business tax calculations: Total premium of the policy excluding any policy or carrier fees. | decimal (12,2) | Depends |
| transaction_line_of_business_list | For multiple lines of business tax calculations: Line of business codes related to the policy, separated by a "|" pipe symbol. The reason why this is mandatory is that there are some states that have coverage-specific tax rules. Instead of using the state-specific codes, we suggest using one of the generic codes which we have defined on this list. The generic codes appear with a "GEN-" prefix. More detail on how these work can be found below. | string | Depends |
| transaction_line_of_business_coverage | For multiple lines of business tax calculations: Total premium of each of the included lines of businesses provided in the related field above, separated by a "|" pipe symbol. Do not include any policy or carrier fees in this amount. | varchar | Depends |
| policy_effective_date | Policy effective date of the original policy. For endorsements, use the original policy effective date of the new or renewal policy applicable to the endorsement. This field is not required but is recommended. This is because we have historical tax rules. If left blank, our system will default this to be today's date. | date (YYYY-MM-DD) | |
| transaction_type | There are a few states that have transaction type-specific tax rules. For example, there are a couple of states that do not return stamping fees for flat cancellations or return premium endorsements. Keep this in mind when setting up your tax rules. Here is a list of active filing types that may be taxed differently in the InsCipher Portal (all depending on the state tax rule). | String (3) | ✓ |
| premium | Total premium of the policy excluding any policy or carrier fees. | decimal (12,2) | ✓ |
| agency_fee | Total fees charged or retained by the brokerage includes fees such as policy fees, agency fees, filing fees, processing fees, etc.For the purpose of SL Tax calculations, all reportable fees must be mapped to one of two buckets (agency_fee or inspection_fee) | decimal (12,2) | ✓ |
| inspection_fee | Total fees charged, mandated, or retained by the carrier include fees such as inspection fees, audit fees, carrier fees, underwriting fees, etc. For the purpose of SL Tax calculations, all reportable fees must be mapped to one of two buckets (agency_fee or inspection_fee) | decimal (12,2) | ✓ |
| commission_received | This field is only applicable to NH and relates to determining maximum fee limits in the state as NH does not allow for the collection of both commission and revenue-generating policy fees. Value Meaning 0 No 1 Yes You can choose to include this for every state, but only policies in NH will return an applicable response. If left blank, the system defaults this value to "0" (or No). | tinyint (1) | |
| rpg | Is your policy a part of a Risk Purchasing Group or RPG? The reason why this is required is there are a few states that have RPG-specific tax rates or document requirements. Value Meaning 0 No 1 Yes If you don't write RPG business, then default this value to "0" (or No) | tinyint (1) | ✓ |
| ecp | Is your policy a part of an Exempt Commercial Purchaser or ECP? The reason why this is required is there are a few states that have RPG-specific tax rates or document requirements. Value Meaning 0 No 1 Yes If you don't write ECP business, then default this value to "0" (or No) | tinyint (1) | |
| account_written_as | There are some states that have different document requirements if the business is written direct or through a retail agent. If the business is written directly to the insured, mark it as "DC". If the business is written through a retail agent, mark it as "B". Value Meaning DC Direct Client B Brokerage If unknown, we recommend defaulting to "B" (or Brokerage). | String (2) | ✓ |
JSON Response Sample
For a description of the field names and values, refer to this table.
{
"line_of_business_id": 1,
"fm_tax_percentage": null,
"line_of_business_list": [
{
"generic_code": null,
"code": "GEN-1001",
"fm_tax_title": "",
"empa_tax_title": ""
}
],
"state_properties": {
"state_stamp_wording_text": "“This insurance has been placed with an insurer not licensed to transact business in the Commonwealth of Kentucky but eligible as a surplus lines insurer. The insurer is not a member of the Kentucky Insurance Guaranty Association. Should the insurer become insolvent, the protection and benefits of the Kentucky Insurance Guaranty Association are not available.”",
"state_stamp_wording_instructions": "Wording to be conspicuously stamped on the face page of the policy, initialed by or bearing the name of the surplus lines broker who procured it.\nExample: “This insurance has been placed with an insurer not licensed to transact business in the Commonwealth of Kentucky but eligible as a surplus lines insurer. The insurer is not a member of the Kentucky Insurance Guaranty Association. Should the insurer become insolvent, the protection and benefits of the Kentucky Insurance Guaranty Association are not available.”\nJohn Smith",
"state_stamp_wording_font_size": 12,
"state_stamp_wording_font_bold": 0,
"state_stamp_wording_font_italics": 0,
"state_stamp_wording_font_color": "black",
"state_stamp_wording_type": "wording",
"state_stamp_wording_updated_at": "2022-04-14 06:04:00"
},
"account_written_as": "DC",
"line_of_business": "GEN-1001",
"transaction_type": "PN",
"premium": 1000.55,
"agency_fee": 100,
"inspection_fee": 200,
"sl_tax": 39.02,
"stamping_fee": 23.41,
"sl_service_charge": 0,
"municipal_fee": null,
"fm_tax": 0,
"empa_tax": 0,
"rpg": 0,
"tax_rule": {
"is_sl_tax_active": true,
"sl_tax_amount_type": 1,
"sl_tax_amount": 3,
"is_sl_tax_input_manual": false,
"is_stamping_fee_active": true,
"stamping_fee_amount_type": 1,
"stamping_fee_amount": 1.8,
"is_stamping_fee_input_manual": false,
"exclude_stamping_fee_when_negative_premium": false,
"is_sl_service_charge_active": false,
"sl_service_charge_amount_type": 1,
"sl_service_charge_amount": 0,
"is_sl_service_charge_input_manual": false,
"is_municipal_fee_active": true,
"municipal_fee_amount_type": 2,
"municipal_fee_amount": 0,
"is_municipal_fee_input_manual": false,
"fee_restrictions": false,
"fee_restriction_amount_fixed_active": false,
"fee_restriction_amount_fixed": null,
"fee_restriction_amount_percentage_active": false,
"fee_restriction_amount_percentage": null,
"max_fee": false,
"max_fee_amount_type": 1,
"max_fee_amount": null,
"fee_restriction_apply_to": [
0
],
"fee_restriction_apply_from": [
0
],
"both_fees_allowed": true,
"ask_if_commission_received": false,
"round_up_taxes_to_the_nearest_dollar": false,
"round_up_premium_to_the_nearest_dollar": false,
"sl_tax_title": null,
"sl_service_charge_title": null,
"stamping_fee_title": "Surcharge",
"municipal_fee_title": "Municipal Tax",
"state_notes": [
{
"note_type": 1,
"note": "<p>All premium bearing policy documents (declarations page, endorsements, etc.) must have the transaction's premium, all fees, and taxes individually broken out.</p>"
},
{
"note_type": 1,
"note": "<p><span style=\"background-color:#f5fafc; color:#526273; font-family:"Open Sans",sans-serif\">Signed/Completed disclosure must be attached to policy before issuance.</span></p>"
},
{
"note_type": 1,
"note": "<p><span style=\"font-size:11pt\"><span style=\"font-family:Calibri,sans-serif\"><strong><span style=\"font-family:"Calibri",sans-serif\"><span style=\"color:#c0392b\">Tax Exempt status varies by state. To help determine whether or not a policy qualifies as Tax Exempt, please review the article found </span></span></strong><strong><span style=\"font-family:"Calibri",sans-serif\"><a href=\"https://support.inscipher.com/knowledge/tax-exempt-status-by-state\" style=\"color:blue; text-decoration:underline\"><span style=\"color:#2980b9\">here</span></a><span style=\"color:#c0392b\">.</span></span></strong></span></span></p>"
},
{
"note_type": 1,
"note": "<p><strong>Collection Fees:</strong> Per <a href=\"https://apps.legislature.ky.gov/law/statutes/statute.aspx?id=43399\">K.R.S 91A.08(4)</a> and 806 KAR 2:150 - the broker or carrier may charge and retain a collection fee to cover the administrative costs associated with preparing and filing the LGPT quartlery and annual reports. This fee is not taxable and but is reported on the LGPT reports. Since this is not payable to the jurisdiction, there is no field in the tax calculator for this collection fee. It is your respoinsibility to track and report any collection fee to the state. Please refer to the statutes referenced regarding the fee limitations.</p>"
}
],
"state_documents": [
{
"upload_required": false,
"name": "Disclosure & Acknowledgement",
"code": "DISCL",
"document_note": "To be signed by insured. Signed copy must be attached to policy before issuance - To be Kept on File",
"transaction_types": [
{
"name": "New Policy",
"short_code": "PN"
},
{
"name": "Renewal Policy",
"short_code": "PR"
}
],
"document_download_link": "https://surpluslines.inscipher.com/doc/link/c90daf2b64cb08c55e852280ecc27b40/1538",
"last_edited_at": "2020-09-18",
"date_active_from": null,
"date_active_to": null,
"document_group": "Affidavit - Blank",
"rpg": 2,
"ecp": 2,
"exempt": 2,
"export_list": 2,
"who_signs": "Insured"
},
{
"upload_required": true,
"name": "Policy or Binder/Dec page",
"code": "POLIC",
"document_note": null,
"transaction_types": [
{
"name": "New Policy",
"short_code": "PN"
},
{
"name": "Renewal Policy",
"short_code": "PR"
}
],
"document_download_link": null,
"last_edited_at": "2021-11-05",
"date_active_from": null,
"date_active_to": null,
"document_group": "Policy Docs",
"rpg": 2,
"ecp": 2,
"exempt": 2,
"export_list": 2,
"who_signs": "N/A"
},
{
"upload_required": true,
"name": "Endorsement",
"code": "ENDOR",
"document_note": "Attach full endorsement",
"transaction_types": [
{
"name": "Additional Premium Endorsement",
"short_code": "APE"
},
{
"name": "Return Premium Endorsement",
"short_code": "RPE"
},
{
"name": "Audit Endorsement",
"short_code": "AE"
},
{
"name": "Flat Cancellation",
"short_code": "FC"
},
{
"name": "Pro Rata Cancellation",
"short_code": "PC"
},
{
"name": "Extension Endorsement",
"short_code": "XE"
},
{
"name": "Audit Return Premium Endorsement",
"short_code": "ARE"
},
{
"name": "Reinstatement",
"short_code": "RI"
}
],
"document_download_link": null,
"last_edited_at": "2021-12-02",
"date_active_from": null,
"date_active_to": null,
"document_group": "Policy Docs",
"rpg": 2,
"ecp": 2,
"exempt": 2,
"export_list": 2,
"who_signs": "N/A"
},
{
"upload_required": false,
"name": "Diligent Search Form",
"code": "DSF",
"document_note": "To be completed confirming diligent search.",
"transaction_types": [
{
"name": "New Policy",
"short_code": "PN"
},
{
"name": "Renewal Policy",
"short_code": "PR"
}
],
"document_download_link": null,
"last_edited_at": "2021-12-30",
"date_active_from": null,
"date_active_to": null,
"document_group": "Affidavit - Custom",
"rpg": 2,
"ecp": 0,
"exempt": 2,
"export_list": 2,
"who_signs": "Broker"
},
{
"upload_required": false,
"name": "State Stamp Wording",
"code": "SSW",
"document_note": "Wording to be conspicuously stamped on the face page of the policy, initialed by or bearing the name of the surplus lines broker who procured it.",
"transaction_types": [
{
"name": "New Policy",
"short_code": "PN"
},
{
"name": "Renewal Policy",
"short_code": "PR"
}
],
"document_download_link": "https://surpluslines.inscipher.com/doc/link/797e210f26986298257ac1616deba392/1212755",
"last_edited_at": "2022-02-17",
"date_active_from": null,
"date_active_to": null,
"document_group": "State Stamp - Blank",
"rpg": 2,
"ecp": 2,
"exempt": 2,
"export_list": 2,
"who_signs": "N/A"
}
],
"round_up_fees_to_the_nearest_dollar": false,
"round_taxes_to_the_nearest_dollar": false,
"round_premium_to_the_nearest_dollar": false,
"round_fees_to_the_nearest_dollar": false
},
"commission_received": false,
"tax_exempt": 0,
"export_list": null,
"municipal_tax_settings": [
{
"municipal_tax_setting": {
"municipality_name": "Lexington-Fayette",
"line_category": "inland_marine"
}
}
],
"county_tax_settings": null,
"collection_fee": 0,
"physical_address": "1110 Sparks Rd",
"physical_city": "Lexington",
"physical_zip_code": "40505",
"physical_state": "KY"
}
Field Descriptions (RESPONSE)
Note:
The responses below are currently a bit out of order from the data submitted in the request. However, the values are accurate and can still be mapped to field names in your Quote/Bind system. Your task to start out will be to do the mapping such that data returned updates the quote and provides a seamless/automatic experience for the end-user.
| Field | Description of Values |
|---|---|
| line_of_business_id | The state-specific Line of Business Code returned |
| fm_tax percentage | FM Tax percentage, if applicable |
| line_of_business_list | HEADER (Useful for Multi-Line of Business Tax Calculations) |
| generic_code | Informational Only > Generic Code used to calculate taxes. Note: There are a few states that allow for multi-line of business submissions. For these states, there could be a possibility of tax rates being different, depending on the premium associated with each line of business. Should you have multiple lines of business but the state does not allow for multiple lines of business to be used when filing , our system will be based the tax rates on the line of business with the greatest amount of premium. |
| code | Informational Only > State-specific line of business code used to calculate taxes |
| fm_tax_title | If this is null or blank, then consider the tax title to be the default name of "FM Tax". There are a few instances where a different tax title may be used in a state. For a full state list, please refer to this matrix. |
| empa_tax_title | If this is null or blank, then consider the tax title to be the default name of "EMPA Tax". There are a few instances where a different tax title may be used in a state. For a full state list, please refer to this matrix. |
| state_properties | HEADER (if applicable) |
| state_stamp_wording_text | Actual state stamp wording text |
| state_stamp_wording_instructions | Instructions on how to apply state stamp wording to the policy document(s). Note, that there may be a need to add additional dynamic fields to be included with the text. For example, there are several states, where in addition to the wording, the license name and/or number would need to be added after the text. |
| state_stamp_wording_font_size | Should the text have a specific font size? The return value will be an integer (2) Note: If there is not a state requirement, the default value will be "12", meaning 12 pt. font size. |
| state_stamp_wording_font_bold | Should the text be bold? 0 - No 1 - Yes Note: If there is not a state requirement, the default value will be "0" or No |
| state_stamp_wording_font_italics | Should the text be in italics? 0 - No 1 - Yes Note: If there is not a state requirement, the default value will be "0" or No |
| state_stamp_wording_font_color | Should the text be in a specific color? Options returned are "black", "red", or "blue" Note: If there is not a state requirement, the default value will be "black" |
| state_stamp_wording_type | Currently, this field can be considered N/A. By default, this will show as "wording". |
| state_stamp_wording_updated_at | The last date where there was an update to the state stamp wording text, instructions, or formatting settings made by the InsCipher team. |
| account_written_as | Brokerage = B or Direct to Client = DC This is just returning the value submitted and won't be relevant to the tax calculations. |
| transaction_type | Transaction type code submitted in the Request. This is just returning the value submitted and may not be necessary to utilize if stored in your management system. |
| premium | Policy premium amount. This returned value may be rounded (if applicable). |
| agency_fee | Agency Fee, Policy Fee, Filing Fee, Broker Fee, and/or other revenue generated fee not mandated by the Carrier. This returned value may be rounded or capped to a max fee amount (if applicable). |
| inspection_fee | Inspection Fee, Audit Fee, Underwriting Fee, and/or other fee mandated by the carrier. This returned value may be rounded or capped to a max fee amount (if applicable). |
| sl_tax | Surplus Lines Taxes - calculated and rounded (if applicable) |
| stamping_fee | Stamping Fee amount - Sometimes renamed depending on state calculated and rounded (if applicable) |
| sl_service_charge | Surplus Lines Service Charge – Sometimes renamed depending on state - Applies to just a few states - calculated and rounded (if applicable) |
| municipal_fee | Kentucky’s LGPT - calculated |
| county_fee | Kentucky's County Tax - calculated (if applicable) |
| fm_tax | Fire Marshall Tax – Sometimes renamed depending on state - Applies to just a few states - calculated and rounded (if applicable) |
| empa_tax | EMPA tax - EMPA applies only to FL but there are a few other states where this field has been repurposed for other state-specific taxes calculated and rounded (if applicable) |
| physical_address | Physical Address of the Insured This is just returning the value submitted and may not be necessary to utilize if already stored in your management system. |
| physical_city | Physical City of the Insured This is just returning the value submitted and may not be necessary to utilize if already stored in your management system. |
| physical_state | Physical State two-letter code of the Insured This is just returning the value submitted and may not be necessary to utilize if already stored in your management system. |
| physical_zip_code | Five-digit Zip Code of the Insured This is just returning the value submitted and may not be necessary to utilize if already stored in your management system. |
| rpg | Is the policy part of an RPG? 0 - No 1 - Yes This is just returning the value submitted and may not be necessary to utilize if already stored in your management system. |
| tax_rule | HEADER (INFORMATIONAL ONLY) |
| is_sl_tax_active | Is Surplus Lines Tax active? true false |
| sl_tax_amount_type | Surplus Lines Tax Type Values: 1 - Percentage (%) 2 - Fixed ($) |
| sl_tax_amount | Surplus Lines Tax Amount (as it relates to percentage or fixed amount) |
| is_sl_tax_input_manual | Can Surplus Lines Tax be entered manually? true false |
| is_stamping_fee_active | Is the Stamping Fee active? true false |
| stamping_fee_amount_type | Stamping Fee Type Values: 1 - Percentage (%) 2 - Fixed ($) |
| stamping_fee_amount | Stamping Fee Amount (as it relates to percentage or fixed amount) |
| is_stamping_fee_input_manual | Can Stamping Fee be entered manually? true false |
| is_sl_service_charge_active | Is Service Charge Fee active? true false |
| sl_service_charge_amount_type | Service Charge Fee Type Values: 1 - Percentage (%) 2 - Fixed ($) |
| sl_service_charge_amount | Service Charge Fee Amount (as it relates to percentage or fixed amount) |
| is_sl_service_charge_input_manual | Is Service Charge Fee entered manually? true false |
| is_municipal_fee_active | Is Municipal Fee Active? true false |
| municipal_fee_amount_type | Municipal Fee Type Values: 1 - Percentage (%) 2 - Fixed ($) |
| municipal_fee_amount | Municipal Tax Amount (as it relates to percentage or fixed amount) |
| is_municipal_fee_input_manual | Is Municipal Fee entered manually? true false |
| fee_restrictions | Are there any fee restrictions? true false |
| fee_restriction_amount_fixed_active | Fee restriction amount fixed true false |
| fee_restriction_amount_percentage_active | Fee restriction amount percentage true false |
| fee_restriction_amount_percentage | Percentage amount |
| max_fee | The max fee total $ that can be charged on a policy |
| max_fee_amount_type | 1 - Percentage (%) 2 - Fixed ($) |
| max_fee_amount | Value of the max fee. For example, if "6" and the Max Fee Type = Percentage, then it would be "6%" |
| fee_restriction_applies_to | Fee restrictions applies to start date? 0 - None 1 = Policy Premium (premium) 2 = Agency Fee (agency_fee) 3 = Inspection/Underwriting Fee (inspection_fee) If multiple, then values will come in an array |
| fee_restriction_applies_from | Fee restrictions applies from start date? 0 - None 1 = Policy Premium (premium) 2 = Agency Fee (agency_fee) 3 = Inspection/Underwriting Fee (inspection_fee) If multiple, then values will come in an array |
| both_fees_allowed | Are both Broker Fees and Carrier Fees Allowed? true false |
| ask_if_commission_received | Does the state care about the commission for fee limits? (will only apply to NH) true false This is just returning the value submitted and may not be necessary to utilize if stored in your management system. |
| sl_tax_title | SL Tax Title If Null, this should default to "Surplus LInes Tax" There are a few instances where a different tax title may be used in a state. For a full state list, please refer to this matrix. |
| sl_service_charge_title | SL Service Charge Title If Null, this should default to "SL Service Charge" There are a few instances where a different tax title may be used in a state. For a full state list, please refer to this matrix. |
| stamping_fee_title | Stamping Fee Title If Null, this should default to "Stamping Fee" There are a few instances where a different tax title may be used in a state. For a full state list, please refer to this matrix. |
| municipal_fee_title | Municipal Fee Title - KY ONLY If Null, this should default to "Municipal Tax" There are a few instances where a different tax title may be used in a state. For a full state list, please refer to this matrix. |
| state_notes | Array of state-specific notes added by InsCipher to assist in the quoting and binding of policies As there may be more than one note, this may come as an array. |
| state_documents | HEADER |
| upload_required | Is document upload required to submit the transaction to InsCipher |
| name | Document name |
| code | Document code (used when importing documents into InsCipher via API submission) |
| document_note | Document specific notes that give direction on how it is used |
| transaction_type | Transaction type code. View available transaction or filing types in this matrix. |
| document_download_link | One-time use URL that can be used to download documents. |
| last_edited_at | Last date the document was updated by the InsCipher team. |
| date_active_from | The start date this document went into effect |
| date_active_to | The end date this document became no longer applicable |
| document_group | Group or type of document (Informational Only) |
| rpg | Is the document applicable if the policy is classified as being part of a Risk Purchasing Group (RPG) 0 - No 1 - Yes |
| ecp | Is the document applicable if the policy is classified as being written by an Exempt Commercial Purchaser (ECP)? 0 - No 1 - Yes |
| exempt | Is the document applicable if the policy is considered "Tax Exempt"? 0 - No 1 - Yes |
| export_list | Is the document applicable if on the state's "Export List"? 0 - No 1 - Yes |
| who_signs | If a signature is required, who signs the document? N/A - No signature required |
| round_up_fees_to_the_nearest_dollar | Rounding Rules: Do the FEES round UP to the nearest dollar? true false |
| round_up_taxes_to_the_nearest_dollar | Rounding Rules: Do the TAXES round UP to the nearest dollar? true false |
| round_up_premium_to_the_nearest_dollar | Rounding Rules: Does the PREMIUM round UP to the nearest dollar? true false |
| round_fees_to_the_nearest_dollar | Rounding Rules: Does the FEES round to the nearest dollar? true false |
| tax_exempt | Is the policy considered Tax Exempt? 0 - No 1 - Yes Not applicable. You can ignore this value. |
| export_list | Is the Line of Business on the state's Export List? 0 - No 1 - Yes 2 - Both This is if the line of business selected is on the Export List in the state (should they have one). If "1" (or Yes), this means that a diligent effort form is typically not required in the state. Note: "2" means that the state doesn't have an export list. |
| municipality_name | Municipality name returned based on the physical address, city, zip, and state-provided. Applicable to KY Only |
| line_category | One of the seven Kentucky line categories: Fire and Allied Perils Casualty Liability Only Vehicle Inland Marine Health Life All Other Risk Taxed |
| municipal_tax_settings | KY - ONLY HEADER (currently this is not returning values) - Collection of municipal_tax_setting or null if not applicable. |
| municipal_tax_setting | KY - ONLY HEADER (currently this is not returning values) |
| municipality_name | Municipality name in Kentucky |
| line_category | Line category in Kentucky, which are important during quarterly and annual reporting of LGPT reports. Return Code Line Category Name fire_and_allied_perils Fire and Allied Perils casulaty_liability_only Casualty Liability Only vehicle Vehicle inland_marine Inland Marine health Health life Life all_other_risk_taxes All Other Risk Taxed |
| county_tax_settings | HEADER (currently this is not returning values) |
| county_name | County name in Kentucky. Only applies if a county fee is in addition to municipal fee (rare). |
| line_category | Line category in Kentucky, which are important during quarterly and annual reporting of LGPT reports. Return Code Line Category Name fire_and_allied_perils Fire and Allied Perils casulaty_liability_only Casualty Liability Only vehicle Vehicle inland_marine Inland Marine health Health life Life all_other_risk_taxes All Other Risk Taxed |
| collection_fee | Returns back the collection fee passed through. If left null, this defaults to "0" (zero) |
| physical_address | The address used: Only applicable to KY - Used to calculate the specific municipality and associated taxes If multiple locations exist, use the location where the largest risk resides (or greatest amount of premium exists). |
| physical_city | The city used: Only applicable to KY - Used to calculate the specific municipality and associated taxes If multiple locations exist, use the location where the largest risk resides (or greatest amount of premium exists). |
| physical_zip_code | The zip code used: Only applicable to KY - Used to calculate the specific municipality and associated taxes If multiple locations exist, use the location where the largest risk resides (or greatest amount of premium exists). |
| physical_state | Only applicable to KY - Used to calculate the specific municipality and associated taxes If multiple locations exist, use the location where the largest risk resides (or greatest amount of premium exists). |
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 this matrix.
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, 5xx codes indicate server errors.
Below are the main HTTP error code and identifier used as well as a summary description of the error:
400 - Bad Request Illegal JSON format
/
Authentication Failed - API Key is invalid
Documents Return Notes
"Documents" returned using this method will be returned in one of two ways:
- Blank document templates: These will be returned as links where blank state forms can be downloaded
- 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 this matrix.
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 here. 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.
Important
It is your responsibility to review the mapping and to determine if there are additional generic codes that need to be mapped or altered.
Note
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.
Updated 12 days ago