API: STATUS Update for Filings - Filing Services™ and Connect™ Clients ONLY

API to pull status updates of filings submitted into the InsCipher Broker and Connect portals. For use by Filing Services™ and Connect™ clients only.

Table of Contents

  1. Introduction
  2. URL: Authentication & GET Request (Combined)
  3. JSON Response Sample
  4. Response Field Descriptions
  5. Errors
  6. Change History Log

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. 

URL: Authentication & GET Request (Combined)

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

For a description of the field names and values, refer to this table.

{
"sl_tax_paid_date": "2019-02-19T00:00:00-07:00",
"stamping_fee_paid_date": "2019-02-19T00:00:00-07:00",
"other_taxes_paid_date": null,
"sl_tax_invoice_id": "2019 CA Annual",
"stamping_fee_invoice_id": "3124234",
"unique_id": null,
"extra_invoice_number": "INVN-10001",
"filed_under_license_name": "Test Agency 2",
"filed_under_license_number": "12345",
"id": 206691,
"transaction_type": "PN",
"transaction_status": 8,
"policy_number": "CA20170228-11",
"policy_effective_date": "2018-12-01",
"transaction_effective_date": "2019-12-01",
"premium": 3900,
"agency_fee": 200,
"inspection_fee": 0,
"sl_tax": 117,
"stamping_fee": 7.8,
"sl_service_charge": 0,
"municipal_fee": 0,
"fm_tax": 0,
"empa_tax": 0,
"mailing_insured_name": "Westfield Galleria at Roseville",
"physical_state": "CA",
"date_filed": null,
"gl_moved_date": null,
"policy_expiration_date": "2019-12-01"
}

 

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

sl_tax_paid_date

SL Tax Paid Date (full date and timestamp)

UTC Timezone

stamping_fee_paid_date

Stamping Fee Paid Date (full date and timestamp)

UTC Timezone

other_taxes_paid_date

Other Taxes Paid Date (full date and timestamp)

UTC Timezone

sl_tax_invoice_id

SL Tax Invoice ID (string)

stamping_fee_invoice_id

Stamping Fee Invoice ID (string)

unique_id

Unique ID # (string)

extra_invoice_number

Invoice number added during the initial import (varchar)

filed_under_license_name

License name associated with the filing (varchar)

filed_under_license_number

License number associated with the filing (varchar)

id

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

transaction_type

Transaction type mapping can be found here.

transaction_status

Transaction Status:

Value Returned          Description

1                              Saved

2                              Submitted

3                              Flagged

4                              Filed

5                              Archived

7                              Void 

8                              Ready to File

policy_number

Policy # (String)

policy_effective_date

Policy Effective Date (YYYY-MM-DD)

UTC Timezone

transaction_effective_date

Transaction Effective Date (full date and timestamp)

UTC Timezone

premium

Premium

Decimal, 2

agency_fee

Agency Fee

Decimal, 2

inspection_fee

Inspection Fee

Decimal, 2

sl_tax

SL Tax Amount (or renamed tax)

Decimal, 2

stamping_fee

Stamping Fee Amount (or renamed tax)

Decimal, 2

sl_service_charge

SL Service Charge Amount (or renamed tax)

Decimal, 2

municipal_fee

Municipal Fee Amount

Decimal, 2

fm_tax

FM Tax Amount (or renamed tax)

Decimal, 2

empa_tax

EMPA Tax Amount (or renamed tax)

Decimal, 2

mailing_insured_name

Insured Name (String)

physical_state

Physical State abbreviation (2 characters)

date_filed

Date filed (full date and timestamp)

UTC Timezone

gl_moved_date

GL Moved Date (full date and timestamp)

UTC Timezone

policy_expiration_date

Policy Expiration Date (YYYY-MM-DD)

UTC Timezone

 

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.

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 Response

Description

200 - OK

A successful request

400 - Bad Request

The request was unacceptable, often due to missing a required parameter.

401 - Unauthorized

Invalid or missing API key

402 - Request Failed

The parameters were valid but the request failed

404 - Not Found

The requested resource doesn't exist

429 - Too Many Requests

Too many requests hit the API too quickly

500 - Internal Server Error

An error occurred while processing a request

 

Change History Log

DATE DESCRIPTION OF CHANGE
2/1/2022 Added link to new Filing Type page
12/6/2021 Added new Transaction Types to the mapping section
9/16/2021 Added API guide to Hubspot article. Simplified areas and added additional context and descriptions to other areas.