Access™: Surplus Lines Tax Calculator API (V4.0)

Get instant surplus lines tax calculations and state-specific documents using JSON request (Updated 4-14-2022)

Table of Contents

  1. Introduction
  2. Authentication and URL
  3. JSON Request Sample
  4. Field Descriptions and Requirements (REQUEST)
  5. JSON Response Sample
  6. Field Descriptions (RESPONSE)
  7. Tax Titles
  8. Errors
  9. Documents Return Notes
  10. How Do Generic Lines of Business Import Codes Work?
  11. Change History Log

Introduction

This API allows your management system to quickly query and receive State Surplus Lines taxes and State Fee calculations for your Surplus Lines policies. 

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. 

Authentication and URL


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

URL Endpoint:

https://surpluslines.inscipher.com/api/tax-calculator/calculate-general-taxes.json?apikey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXX

HTTP Method:

POST

JSON Request Sample

 

Descriptions of each field are listed below

 

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 "100" or 100 percent.

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)

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&#39;s premium, all fees, and taxes individually broken out.</p>"
            },
            {
                "note_type": 1,
                "note": "<p><span style=\"background-color:#f5fafc; color:#526273; font-family:&quot;Open Sans&quot;,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:&quot;Calibri&quot;,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:&quot;Calibri&quot;,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&nbsp;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": null,
    "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.

 

END OF SECTION

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.

     

    END OF SECTION

    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

    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

    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.

     

    END OF SECTION

    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_to

    The start date this document went into effect

    date_active_from

    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_setting

    HEADER

    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

    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 will either come as a state requirement or as a template, which can be downloaded. Currently, this return does not include the date the document was updated. Future updates, likely in Q1 2022, will have this functionality. 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. 

    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.

     

    Change History Log

    DATE DESCRIPTION OF CHANGE
    4/14/2022 Updated to V4.0: Added multiple new fields including the ability to submit multiple lines of business, auto-rounding on premium and fees if applicable, auto max fee calculation if applicable, state stamp wording text, new fields related to documents such as the date last updated or who signs the document. 
    2/1/2022 Added links to new field mapping packet.
    12/6/2021 Added new Transaction Types to the mapping section
    9/8/2021 Added API guide to Hubspot article. Simplified areas and added additional context and descriptions to other areas.