Batch Transaction Import

Introduction

The Batch Transaction Import API allows the programmatic import of multiple transactional policy data and documents into InsCipher's online portal. In order to take full advantage of this functionality, your IT team will need to first be able to extract policy data and documents out of your existing policy management system, map these fields to those defined in this documentation, and submit the data on a recurring basis (most InsCipher clients do this on a daily cadence) via this endpoint.

All batches imported into InsCipher are logged and tracked via a batch_id, used to link all transactions together, which is returned in the response. There are a few strict field requirements, but generally, there is some flexibility with regard to what data is required upon initial import. If you have questions on this process or want to get set up, please contact [email protected].

👍

TIP:

There are different methods or approaches to importing transactions using this REST API. If you need a quick solution to test out an import and do not currently have one, consider utilizing Postman or make a test call on our Transaction Import schema page. If you are new to our schemas section, we recommend you start with an overview of how to interact with them here.

📘

Notes:

• Field Requirements:
  We recommend that you add ALL fields marked as Required = ✓ in the field tables below. If there are values that do not exist in your agency system, you may need to hard code these as null and manually add the data after import.
• Document Import:
  While this endpoint allows for the import of documents - they can also be imported separately from transactions via API using your internal invoice number or InsCipher Transaction ID. To learn more, go here.

🚧

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:

• Transaction Types
• Policy Limit Requirements
• Generic Lines of Business List
• State Specific to Generic LOB Mapping
• Description of Risk Import Codes
• Non-Admitted Insurer Codes
• Multiple Insurance States / Syndicate List
• Declining Carrier Import Requirements
• Document Requirements - Filing Services

Workflow Overview

The Policy Transaction import API is designed to be completed in two steps:

Step 1: POST JSON batch file to the Import Endpoint

Run the POST request to import specific transactional details formatted with specific header names to start the import process. This detail can also include a link to documents related to the transactions. See the section below for sample JSON request and field descriptions.

Step 2: Send a GET request to get a detailed Import Response

Run a request to GET the details on whether or not a specific transaction was imported successfully or if there were any import errors.

Read more about Batch Import Status request

Request & Response

POST https://surpluslines.inscipher.com/api/v4/transaction

Before structuring your request for policy import, it is important that you identify what type of InsCipher client you are importing data on behalf of. This will matter, as field requirements between Filing Services and Connect clients differ. Additionally, there are a few requirements around data migration that you should be aware of - and that are noted in the sections below. Click the Get Started tab for the respective client type to understand requirements around:

• Field Types and Descriptions, including required and optional fields.
• JSON request format
• JSON response format
• Error handling and warnings

Filing Services® clients

Connect® clients

Broker Fees vs Carrier Fees

InsCipher separates fees into two buckets as these fees are taxed and reported differently depending on the state.

1. Broker Fees - These are an agency, policy, broker, filing, or other revenue-generating or reimbursement fees charged by or retained by the broker that is not mandated by the carrier.

2. Carrier Fees - These are inspection, audit, underwriting, or other fees charged or mandated by the carrier that is retained by the carrier.

❗️

Please note

It is important that when doing an import into InsCipher, your various fees get mapped to one of these two types so that our system can accurately determine the correct SL Tax calculations.

State Taxes and Fee Titles

InsCipher, by default, has certain state taxes and fees defaulted to these names:

a. sl_tax - Surplus Lines Tax
b. stamping_fee - Stamping Fee c. sl_service_charge - Surplus Lines Service Charge d. fm_tax - Fire Marshall Tax e. empa_tax - EMPA Tax f. municipal_fee - Municipal Tax

In some instances, we have chosen to rename tax titles for certain states instead of creating several custom fee fields. Here is a list of tax/fee titles that may vary from the default.

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.

❗️

Generic codes

It is your responsibility to review the mapping and to determine if there are additional generic codes that need to be mapped or altered.

🚧

Note

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.

Can I Import Documents In A Separate Step?

Yes, after transactions have been imported successfully, documents can be added in a separate step. To do this, please follow the instructions outlined here.

API automatically returns a list of all policy numbers together with import status.

GET Import Status Response

After the policy data has been imported, you can then use the GET request below to get specific results.

GET Import Status (All Clients)