Transaction Status

Retrieve status updates on a single transaction submitted into the InsCipher platform.

Introduction

This API allows you to programmatically get status updates on a single filing submitted into the InsCipher platform. This can be utilized by both InsCipher Filing Service™ and Connect™ clients. Bulk status updates are not available using this request.

There are two approaches to get status updates. This can be done using the Filing # (from InsCipher) or it can be done using the Invoice Number from your management system that was included on the transaction when it was first imported. Either approach works, but most clients use the Invoice Number method.

📘

TIP:

There are different methods or approaches to retrieving filing status updates using this API GET request. If you need a quick solution to test out an import and do not currently have one, consider utilizing Postman.

🚧

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:


Request Method - GET

Authentication / API Key:

The 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:

  • If going by Invoice #:

https://surpluslines.inscipher.com/api/v1/get-transaction-status.json?apikey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&invoice_number=987654321

  • If going by Filing #:

https://surpluslines.inscipher.com/api/v1/get-transaction-status.json?apikey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&transaction_id=1234567

  • HTTP Method: GET

JSON Response Sample

{
"id":195195,
"county_fee": null,
"other_taxes_paid_date": null,
"transaction_id_number": null,
"municipal_name": null,
"municipal_category": null,
"sl_tax_paid_date":null,
"stamping_fee_paid_date":null,
"sl_tax_invoice_id":null,
"stamping_fee_invoice_id":null,
"unique_id":null,
"extra_invoice_number":"IN812551",
"filed_under_license_name":null,
"filed_under_license_number":null,
"transaction_type":"PN",
"transaction_status":2,
"policy_number":"PN58585",
"policy_effective_date":"2019-06-12",
"transaction_effective_date":"2019-06-12",
"premium":10,
"agency_fee":20,
"inspection_fee":0,
"sl_tax":0,
"stamping_fee":0,
"sl_service_charge":0,
"municipal_fee":0,
"fm_tax":0,
"empa_tax":0,
"mailing_insured_name":'Insured name',
"physical_state":"CA",
"date_filed":null,
"gl_moved_date":"2019-06-13",
"policy_expiration_date":"2020-06-12",
"transaction_documents": [
    {
        "name": "Test custom document",
        "code": null,
        "download_url": "http://localhost:8080/transaction/document/156230/64789/download"
    },
    {
        "name": "Policy",
        "code": "POLIC",
        "download_url": "http://localhost:8080/transaction/document/156230/64791/download"
    },
    {
        "name": "SL-1",
        "code": "SL1",
        "download_url": "http://localhost:8080/transaction/document/156230/64792/download"
    }
]
}

Response Field Descriptions

📘

Note:

The responses below are pulled from what values are on the filing details page of the applicable queried transaction.

Field nameField description
idFiling Number created and assigned by the InsCipher portal (integer)
county_feeOnly for KY - Pertains to Local Government Premium Tax (municipal county fees)
other_taxes_paid_dateDate filing was marked paid for all other taxes. Other taxes are defined as all taxes except for SL tax and Stamping Fee (i.e. empa, municipal fee, etc.)

"yyyy-mm-dd" UTC Timezone
transaction_id_numberThis is a state-specific ID.
municipal_nameOnly for KY - Pertains to Local Government Premium Tax (municipal county fees)
municipal_categoryOnly for KY - Pertains to the tax category defined based on the line of business associated with the transaction.
sl_tax_paid_dateDate filing was marked as SL Tax paid in the InsCipher portal.

"yyyy-mm-dd" UTC Timezone
stamping_fee_paid_dateDate filing was marked as Stamping Fee paid in the InsCipher portal.

"yyyy-mm-dd" UTC Timezone
sl_tax_invoice_idState invoice ID or period pertaining to the payment made for SL Taxes.
stamping_fee_invoice_idState invoice ID or period pertaining to the payment made for SL Taxes.
unique_idUnique ID associated to the transaction, added by the filer or during the submission process.
extra_invoice_numberOriginal agency management system insured invoice number.
filed_under_license_nameLicense name associated with filing.
filed_under_license_numberLicense number associated with filing.
transaction_typeTransaction type.
transaction_statusTransaction Status:

Value Returned Description

1 Saved

2 Submitted

3 Flagged

4 Filed

5 Archived

7 Void

8 Ready to File
policy_numberPolicy Number
policy_effective_datePolicy Effective Date

"yyyy-mm-dd" UTC Timezone
transaction_effective_dateTransaction Effective Date (will be the same as policy effective date for new and renewal policies)

"yyyy-mm-dd" UTC Timezone
premiumPremium
agency_feeAgency, Broker, Policy Fees
inspection_feeCarrier, Inspection, Underwriting Fees
sl_taxSurplus Lines Taxes (applies to all states)
stamping_feeStamping Fees (applies to the majority of states)
sl_service_chargeSurplus Lines Service Charges (only applies to a couple of states)
municipal_feeMunicipal Fee (only applies KY)
fm_taxFire Marshall Tax (only applies to a couple of states)
empa_taxEMPA Tax (or renamed fee that only applies to a couple of states)
mailing_insured_nameInsured Name
physical_stateRisk State
date_filedDate Filed (if applicable)
gl_moved_dateGeneral Ledger Moved Date (date entered into accounting system)

"yyyy-mm-dd" UTC Timezone
policy_expiration_datePolicy Expiration Date
transaction_documents :Transaction Documents attached to the filing
........{ name, code, download_url }Collection of transaction documents' data :

name : Transaction document name

code : Transaction document code

download_url : Transaction document download URL

📘

Note:

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.

Response & 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:

Error ResponseDescription
200 - OKA successful request
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedInvalid or missing API key
402 - Request FailedThe parameters were valid but the request failed
404 - Not FoundThe requested resource doesn't exist
429 - Too Many RequestsToo many requests hit the API too quickly
500 - Internal Server ErrorAn error occurred while processing a request