Transaction Status

Retrieve status updates on a single transaction.

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 - both via URL parameters:

  1. **Transaction ID: **Also known as the filing number - this is the identifier that InsCipher gives a transaction once it is submitted into the system.
  2. Invoice Number: This is the identifier sent in with the initial POST request, and usually derives from the ID of the transaction from the agency management system it had before. This method is most utilized by clients.

URL

GET /api/v1/get-transaction-status.json

The transaction or invoice ID's are then required as query parameters to pull a specific transaction, like so:

GET /api/v1/get-transaction-status.json?transaction_id=7009501

GET /api/v1/get-transaction-status.json?invoice_number=480828

Request / Response Examples

{
	"municipal_name": null,
	"municipal_category": null,
	"sl_tax_paid_date": null,
	"stamping_fee_paid_date": null,
	"other_taxes_paid_date": null,
	"sl_tax_invoice_id": "INVSL-30001",
	"stamping_fee_invoice_id": "INVST-20001",
	"unique_id": null,
	"extra_invoice_number": "TESTINGIDe",
	"filed_under_license_name": null,
	"filed_under_license_number": null,
	"id": 7009501,
	"transaction_type": "PN",
	"transaction_status": 1,
	"policy_number": "ABCfe",
	"policy_effective_date": "2017-02-01",
	"transaction_effective_date": "2017-02-01",
	"premium": 3108.5,
	"agency_fee": 200,
	"inspection_fee": 0,
	"sl_tax": 93.26,
	"stamping_fee": 6.22,
	"sl_service_charge": 0,
	"municipal_fee": null,
	"county_fee": null,
	"fm_tax": 0,
	"empa_tax": 0,
	"mailing_insured_name": "Westfield Galleria at Roseville",
	"date_filed": null,
	"gl_moved_date": null,
	"policy_expiration_date": "2018-02-01",
	"transaction_id_number": null,
	"date_ready_to_file": null,
	"collection_fee": 0,
	"physical_state": "CA",
	"transaction_documents": [
		{
			"name": "Custom 0 (POLICYdoc1)",
			"code": null,
			"download_url": "https:\/\/surpluslines.inscipher.com\/transaction\/document\/7009501\/4329514\/download"
		},
		{
			"name": "Custom 1 (UNMAPD)",
			"code": null,
			"download_url": "https:\/\/surpluslines.inscipher.com\/transaction\/document\/7009501\/4329515\/download"
		},
		{
			"name": "Custom 2 (UNMAPD)",
			"code": null,
			"download_url": "https:\/\/surpluslines.inscipher.com\/transaction\/document\/7009501\/4329516\/download"
		}
	],
	"created_by": "John doe",
	"created_date": "2024-10-24 17:35:31 America\/Denver"
}
The request was unacceptable, often due to missing a required parameter.

Response Field Descriptions

📘

Note:

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

Field name

Field description

id

Filing Number created and assigned by the InsCipher portal (integer)

county_fee

Only for KY - Pertains to Local Government Premium Tax (municipal county fees)

other_taxes_paid_date

Date 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_number

This is a state-specific ID.

municipal_name

Only for KY - Pertains to Local Government Premium Tax (municipal county fees)

municipal_category

Only for KY - Pertains to the tax category defined based on the line of business associated with the transaction.

sl_tax_paid_date

Date filing was marked as SL Tax paid in the InsCipher portal.

"yyyy-mm-dd" UTC Timezone

stamping_fee_paid_date

Date filing was marked as Stamping Fee paid in the InsCipher portal.

"yyyy-mm-dd" UTC Timezone

sl_tax_invoice_id

State invoice ID or period pertaining to the payment made for SL Taxes.

stamping_fee_invoice_id

State invoice ID or period pertaining to the payment made for SL Taxes.

unique_id

Unique ID associated to the transaction, added by the filer or during the submission process.

extra_invoice_number

Original agency management system insured invoice number.

filed_under_license_name

License name associated with filing.

filed_under_license_number

License number associated with filing.

transaction_type

Transaction type.

transaction_status

Transaction Status:

Value Returned Description

1 Saved

2 Submitted

3 Flagged

4 Filed

5 Archived

7 Void

8 Ready to File

9 Unregistered

10 In E-File Queue

policy_number

Policy Number

policy_effective_date

Policy Effective Date

"yyyy-mm-dd" UTC Timezone

transaction_effective_date

Transaction Effective Date (will be the same as policy effective date for new and renewal policies)

"yyyy-mm-dd" UTC Timezone

premium

Premium

agency_fee

Agency, Broker, Policy Fees

inspection_fee

Carrier, Inspection, Underwriting Fees

sl_tax

Surplus Lines Taxes (applies to all states)

stamping_fee

Stamping Fees (applies to the majority of states)

sl_service_charge

Surplus Lines Service Charges (only applies to a couple of states)

municipal_fee

Municipal Fee (only applies KY)

fm_tax

Fire Marshall Tax (only applies to a couple of states)

empa_tax

EMPA Tax (or renamed fee that only applies to a couple of states)

mailing_insured_name

Insured Name

physical_state

Risk State

date_filed

Date Filed (if applicable)

gl_moved_date

General Ledger Moved Date (date entered into accounting system)

"yyyy-mm-dd" UTC Timezone

policy_expiration_date

Policy 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

created_by

Name of who the transaction was originally created by within the agency.

created_date

Date the transaction was created by within the agency.

📘

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 Codes & 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