Surplus Taxes and Fees

Herald enables surplus lines (SL) taxes and fees calculation for non-admitted quotes using InsCipher.

This endpoint integrates with InsCipher's surplus lines tax calculator API, a highly trusted third-party tool used to determine surplus lines taxes and fees down to the state, county, and municipal levels. While Herald manages the integration, InsCipher is not a Herald product—platforms must provide their own InsCipher API token and store it with Herald before using this feature. If you would like access to this feature, please email support@heraldapi.com.

‍

Requirements

The quote must be non-admitted (quote.admitted = false).
The admin parameter adm_p29n_broker_fees must be present in the submission request that generated the quote.
- This must be an integer.
- A value of 0 is allowed and indicates no broker fee.
  ‍

Behavior

InsCipher is the source of truth for all surplus lines taxes and fees in Herald's priceDetails object. If carriers return their own surplus taxes and fees in their response, they are not remitted in priceDetails.
Inscipher prices are remitted in priceDetails.brokerSurcharges.
- Each surplus tax/fee surcharge is marked with surplus: true in the breakdown array
The endpoint calculates:
- SL taxes
- SL stamping fees
- Other applicable state-specific SL charges like:
  - Municipal fees
  - FM tax
  - EMPA tax
  - County fees
  - SL Service charge
If the destination state requires additional SL documents, InsCipher returns them in the response. Herald retrieves these documents, stores them, and attaches them to the quote.
- Inscipher documents have their own dedicated type of inscipher_document
  ‍

Request

POST /quotes/:quote_id/calculate_sl_surcharges

No additional body is necessary for this request.

Response

The response from this endpoint is exactly the same as the GET /quotes/:id endpoint. The response will include the surplus charges from the response, as well as any files returned in the InsCipher response.

Note: In the initial response from the endpoint, InsCipher files will be returned with status processing. These files are handled asynchronously exactly as any other quote files. For more information, see our files documentation.

Copied


{
    "quote": {
        "id": "1cd8700b-c7ff-4b05-bffd-a37057fcd3e5",
        "product": {
            "id": "prd_0051_herald_cyber_surplus",
            "name": "Herald Cyber Surplus",
            "product_line": "cyber_surplus",
            "institution": {
                "id": "ins_vbh3_herald",
                "name": "Herald"
            }
        },
        "status": "active",
        "status_details": null,
        "actions": null,
        "portal_link": "https://dev.redirect.heraldapi.com/prd_0051_herald_cyber_surplus/1cd8700b-c7ff-4b05-bffd-a37057fcd3e5/broker_portal",
        "portal_links": [ ... ],
        "insurers": [ ... ],
        "submission_id": "e9cdb2e5-74ea-4ea4-b85e-9a1f8e93150d",
        "prices": {
            "premium_before_taxes_and_fees": 1810,
            "premium_with_taxes_and_fees": 1935,
            "details": [
                {
                    "text": "Broker fees",
                    "type": "fee",
                    "amount": 100
                }
            ]
        },
        "price_details": {
            "premium": {
                "total": 1810,
                "breakdown": null
            },
            "institution_surcharges": {
                "total": null,
                "breakdown": null
            },
            "government_surcharges": {
                "total": 72.4,
                "breakdown": [
                    {
                        "text": "SL Tax",
                        "type": "tax",
                        "amount": 72.4,
                        "surplus": true
                    }
                ]
            },
            "broker_surcharges": {
                "total": null,
                "breakdown": [
                    {
                        "text": "Broker fees",
                        "type": "fee",
                        "amount": 100
                    }
                ]
            }
        },
        "producer": { ... },
        "files": [
            {
                "id": "ac6da5da-8f65-40e6-ac6c-86dddfcf0c83",
                "status": "available",
                "text": "Quote Summary",
                "type": "quote_summary"
            },
            {
                "id": "9ec8e78b-0657-4ab1-ad4b-5a9002ea71a8",
                "status": "processing",
                "text": "Connecticut Export List",
                "type": "inscipher_document"
            },
            {
                "id": "dcf0a370-ec24-4e4a-954a-29eb023cf6e4",
                "status": "processing",
                "text": "Insured Acknowledgement & Diligent Effort",
                "type": "inscipher_document"
            }
        ],
        "coverage_values": [
            ...
        ],
        "risk_values": [
            ...
        ],
        "admin_values": [
            {
                "admin_parameter_id": "adm_p29n_broker_fees",
                "value": 100,
                "parameter_text": {
                    "applicant_facing_text": "Sum of all broker surcharges to the insured",
                    "agent_facing_text": "Sum of all broker surcharges to the insured"
                },
                "input_type": "integer"
            },
           ...
        ],
        "bind_request_available": true,
        "policy": null,
        "quote_number": null,
        "contacts": null,
        "admitted": false,
        "forms": null
    }
}

‍

Error Cases

Herald's calculate_sl_surcharges will throw errors in the following cases detailed below.

Description	Error Code	Error Message
An inscipher token is missing for the platform	400	No InsCipher API token found for platform (platform-id)
The quote is admitted and thus inelligible for inscipher	400	Admitted quote is not elligible for InsCipher surplus taxes and fees calculation
Broker fees are missing for the quote	400	Broker fees are missing from the quote but are required for inscipher calculation

/quote