API Import: REST API to Import Transactions - Filing Service Clients (V4.5)

Documentation related to importing transactions into the InsCipher portal (Updated on 9/16/2022)

Table Of Contents

  1. Introduction
  2. POST Import Request VS GET Import Response
  3. Authentication and URL
  4. JSON Request Sample
  5. Field Descriptions and Requirements
  6. Mapping Fees and Tax Titles
  7. How Do Generic Lines of Business Import Codes Work?
  8. Can I Import Documents In A Separate Step?
  9. Immediate Response Format
  10. Get Import Results API Call - Optional
  11. How Do I View And Correct Batch Import Errors?
  12. Change History

 

Introduction

InsCipher has an API Endpoint available for your agency to programmatically import transactional policy data and documents into InsCipher’s online portal. In most cases, in order to take advantage of this API, you will need your IT team to be able to extract policy data and documents out of your policy management system, map the fields, and then submit the data electronically through our API endpoint in a JSON format. Most of our clients that have set this up, import batches daily into InsCipher. All batches imported, will be logged and tracked in InsCipher with a batch import ID number. This number also gets associated with individual transactions. InsCipher does have the ability to make certain required fields optional, depending on your workflow. If you have questions about this process or want to get set up, please contact support@inscipher.com.

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. 

Note: Documents can be imported separately from transactions via API. To learn more, go here.

 

POST Import Request Vs GET Import Response

The transaction import for V4.0 differs from previous import versions in that it allows for a much greater volume of transactions to be imported into InsCipher at one time. The import 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. Details on getting an import response can be found here.

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. Details on getting an import response can be found here.

Authentication and URL

A user is authenticated using a unique and encrypted API key.

API Key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Note: Your API Key can be reset at any time by the primary Filing Agency Admin logging into the InsCipher Connect portal. After logging in, go to "My Profile" by first clicking the arrow next to the user name in the top right corner. Afterward, click the button to “GET NEW API KEY”.

Import Request Endpoint

 

https://surpluslines.inscipher.com/api/v4/transaction.json?apikey=xxxxx

Add your assigned API key in the URL in place of the XXXXXXXXXXXXXXXXXXXXXXXXXXXXX

 

HTTP Method

POST                                                  

JSON Request Sample

Descriptions of each field are listed below

[{
"id": "201702028950",
"policy_number": "CA20170228-05",
"policy_effective_date": "2017-02-01",
"policy_expiration_date": "2018-02-01",
"transaction_effective_date": "2017-02-01",
"expiring_policy_number": "CA20170228-04",
"invoice_date": "2017-02-01",
"invoice_number" : "INVN-10001",
"transaction_type": "PN",
"account_written_as": "B",
"rpg": 1,
"layered_risk": 1,
"broker_of_record": 1,
"risk_retention_group": 1,
"purchasing_group_name": "Cal Association",
"risk_description": "General Accidental Coverage",
"ecp": 0,
"exempt": 0,
"multi_state": 0,
"policy_limit": 0,
"property_limit": 0.00,
"export_list": 0,
"transaction_line_of_business_list": "GEN-1001|GEN-1002|GEN-1003",
"transaction_line_of_business_coverage": "950.75|2000.25|157.50",
"non_admitted_insurer_code_list": "39381|AA-1120841|12833",
"non_admitted_insurer_code_coverage": "50|30|20",
"syndicate_list": "AA-1120131|AA-1120124",
"syndicate_list_coverage": "60|40",
"premium": 3108.50,
"agency_fee": 200.00,
"inspection_fee": 0.00,
"sl_tax": 117.00,
"stamping_fee": 7.80,
"sl_service_charge": 0.00,
"municipal_fee": 0.00,
"fm_tax": 0.00,
"empa_tax": 0.00,
"total": 4224.80,
"commission_received": 0,
"mailing_insured_name": "Westfield Galleria at Roseville",
"mailing_address": "1151 Galleria Blvd",
"mailing_city": "Roseville",
"mailing_zip_code": "95678",
"mailing_state_code": "CA",
"insured_entity": "individual",
"physical_same_as_mailing": 1,
"agent_notes" : "test notes",
"retail_producer_name": "Producer Name",
"retail_agency_name": "Producer Agency Name",
"retail_address": "Demo street 1",
"retail_address2": "2nd floor",
"retail_city": "Demo City",
"retail_state": "WA",
"retail_zip": "12345",
"sop_name": "SOP Name",
"sop_address": "Demo street 1",
"sop_address_2": "2nd floor",
"sop_city": "Winthrop",
"sop_state": "WA",
"sop_zip": "98862",
"dc_naic": "54267|37816|49865",
"dc_date_declined": "2017-02-02|2017-02-03|2017-02-04",
"dc_declining_reason": "wrong|bad|incorrect",
"dc_underwriting_consideration": "Demo|Test|Considered",
"dc_representative_name": "John|Doe|Johnson",
"dc_representative_title": "Mr|Dr|Ms",
"dc_representative_email": "demo@demo.none|test@demo.none|demo@demo.none",
"dc_representative_phone_number": "54|36|465",
"umr_number": "C123434",
"sla_transaction_number": "12345-21-05155",
"wind_storm_exclusion": 0,
"eligible_for_windstorm": 0,
"wind_storm_deduction": 0.00,
"windstorm_primary_amount": 0.00,
"other_coverages_deductible": 0,00,
"lloyds_cover_holder_number": "",
"lloyds_cover_holder_name": "",

"transaction_documents": [{
"code": "D1DISC",
"url": "https://www.google.com/logos/doodles/2017/abdul-sattar-edhis-89th-birthday-5757526734798848-
res.png",
"id": 1000001
},{
"code": "POLIC",
"url": "https://www.google.com/logos/doodles/2017/abdul-sattar-edhis-89th-birthday-5757526734798848-
res.png",
"id": 100000
}]
}]

 Multiple Documents With The Same Transaction Are Allowed

"transaction_documents":
[{
  "code": "POLIC",
  "url": "https://yourdomain.com/api/state-stamp-wording-025462234.pdf",
  "id": 12233
},{
  "code": "SL1",
  "url": "https://yourdomain.com/api/ssw.pdf",
  "id": 455667
},{
  "code": "SL2",
  "url": "https://yourdomain.com/api/dill-eff-025462234.pdf",
  "id": 455666
}]

 

Field Descriptions

Field Title (header must be exact on JSON)

Description

Field type

Optional

Required

id

A unique ID used for tracking imported transactions

This number will be used to identify possible duplicate transactions. Identified duplicate transactions will be excluded from being imported.

varchar (255)

 

policy_number

Policy number. Non-unique field.

varchar (50)

 

policy_effective_date

Policy effective date

date (yyyy-mm-dd)

 

policy_expiration_date

Policy expiration date

date (yyyy-mm-dd)

 

transaction_effective_date

Transaction effective date

For endorsements, this is the endorsement date. For New/Renewal policies, this is equal to the policy effective date. If omitted, today's date is used as transaction eff. date

date (yyyy-mm-dd)

 

expiring_policy_number

Expiring Policy Number

Only Required for Renewal type policies.

varchar (50)

 

Depends

invoice_date

This is the date that the policy was invoiced in most states. In GA, this is the Revenue Recognition Date, in HI, this is the Date Issued.

If omitted, the filing effective date will be used.

date (yyyy-mm-dd)

 

Depends

invoice_number

This is the invoice number (or unique transaction ID) generated by your Agency Management System (AMS). 

This number allows users to trace imports to existing transactions within the management system as is a value we recommend importing.

This number will be used to identify possible duplicate transactions. Identified duplicate transactions will be excluded from being imported.

varchar

 

transaction_type

Updated transaction types can be found here.

varchar (50)

 

account_written_as

Use one of these two options:

Brokerage = B

Direct Client = DC

Use "B" if you sell through a retail agent. Use "DC" if the policy is sold directly to the insured. If omitted, the default Agency Admin setting will be used

varchar (50)

 

rpg

Risk Purchasing Group?

Yes = 1
No = 0

tinyint(1)

 

layered_risk

Layered Risk

Yes = 1

No = 0

tinyint(1)

 

broker_of_record

Broker of Record Change

Yes = 1

No = 0

tinyint(1)

 

risk_retention_group

Risk Retention Group

Yes = 1

No = 0

tinyint(1)

 

purchasing_group_name

Required if RPG (rpg field) is set to Yes (or 1).

If not included and RPG = Yes, then the transaction will still import but will show RPG error.

varchar(255 )

 

Depends

risk_description

Description of Risk

For New York, Ohio, and Pennsylvania, we require specific import codes to be used when importing.

For all other states, import this as a text value description of the coverage.

See this table for a list of the state-specific codes. To download the table, hover over the top right corner of the table, click on the three dots, and then export to CSV.

varchar(255 )

 

Depends

ecp

Exempt Commercial Purchaser?
Yes = 1

No = 0

If omitted, 0 (zero) value will be imported. Unless you know what this is, set this value to 0.

tinyint(1)

 

exempt

Is the Insured/Entity considered tax-exempt by the state?

Exempt Yes = 1
Exempt No = 0

Unless you know that the insured/Entity is Tax Exempt, set the value to 0 or leave it blank (the system will default to 0). Currently Required only for the state of Utah.

tinyint(1)

 

multi_state

Does the insured’s liability reside in multiple states?

Multi state Yes = 1
Multi state No = 0

InsCipher does not calculate Multi-state surplus lines tax breakdowns. With NIMA dissolving in 2016, InsCipher reports 100% of the premium to the home state of the insured and bases the tax percentages off that state. If omitted, the default is No (0). There are only a few states where InsCipher has enabled this field. 

tinyint(1)

 

policy_limit

This is the aggregate policy limit/liability amount associated with the policy.

The requirement depends on State and Agency settings. There are about a dozen states that require this information when filing. For this reason, we recommend that you include the policy limit on every submission. If it isn't required by the state then this amount will be ignored. However, for a specific list, go here.

integer(12)

 

Depends

property_limit

Property Policy Limit

The requirement depends on State and Agency settings. We recommend that you include the property policy limit on every submission. If it isn't required by the state then this amount will be ignored.

Currently, this field only applies to PA.

 

integer(12)

 

Depends

export_list

The system now auto-sets this value based on the Line of Business used. Therefore, leave this value as "0".

tinyint(1)

 

transaction_line_of_business_list

 

This is an InsCipher-specific import code. We recommend using the Generic Import codes, which can be found here: Generic Line of Business / Coverage Code List If you want to use state-specific codes, you can. These can be found here.

For policies with a single LOB, enter the single import code. If there are multiple LOBs, then these would be added and separated by the pipe symbol “|”.

The requirement depends on whether the state requires a line of business breakdown. As this varies by state, we recommend importing all transactions with multiple lines of businesses, where applicable. If the state only allows for a single LOB when reporting, our system would select the coverage that is associated with the greatest premium amount $.

string

 

transaction_line_of_business_coverage

The premium breakout (rounded to the nearest cent) without the dollar sign in the string. 

Broken-out premiums should be separated by a pipe symbol “|” and should be in the same order as the transaction_line_of_buisness_list.

Whether there is a single line of business or multiple, the premium total should always equal the total added in the premium field above.

string

 

non_admitted_insurer_code_list

This is the NAIC code associated with the insurer. Refer to the Insurance Company import list which can be downloaded here.

For policies with multiple insurance companies, provide the NAIC insurer code list. Multiple values are separated by the pipe symbol “|”.

For Lloyd's policies, use “AA-1122000”. Also, review syndicate_list and syndicate_list_coverage.

This requirement depends on the state requires an insurance company breakdown. As this varies by state, we recommend importing all transactions with multiple insurance companies, where applicable.

Example: 26883|35351

Must also provide details in non_admitted_insurer_code_coverage
Sample fields with Multi-Companies:

“non_admitted_insurer_code_list": "26883|35351",
"non_admitted_insurer_code_coverage”: ”60|40”

 

string

 

non_admitted_insurer_code_coverage

Applicable percentage breakdown. For single insurance companies, list "100" here. For multiple insurance companies, list the breakout. This value would be the percentage breakdown in 100 based values (without the “%” sign). List these in the same order as the non_admitted_insurer_code_list. Multiple values are separated by the pipe symbol “|”.

The requirement depends on if the state requires an insurance company breakdown. As this varies by state, we recommend importing all transactions with multiple insurance companies, where applicable. If a state doesn't allow for multiple to be reported, then our system would select the carrier with the greatest percentage and report the amount with that carrier.

Example: 60|40

string

 

 

syndicate_list

Syndicate list breakdown for Lloyd's ONLY policies, for mult-carrier policies that have Lloyd's and non-Lloyd's carriers, please refer to the note below.

Multiple syndicate codes should be separated by the pipe symbol “|”.

The requirement depends on agency settings and if the state requires a syndicate list breakdown when filing. To simplify the import process, we recommend that you import all Lloyd's policies with a syndicate list breakdown (if possible). If the state does not require it, the breakdown will be ignored.

Example:

"non_admitted_insurer_code": "AA-1122000", "syndicate_list": "AA-1120131|AA-1120124", "syndicate_list_coverage": "60|40"

Syndicate lists are required for multiple states. A full list can be found here:

NOTE: Should you have Lloyd's and Non-Lloyd's carriers, then import transactions with multiple insurance company breakouts where the syndicates would be included in this breakout rather than as a separate syndicate field.

string

 

Depends

syndicate_list_coverage

Syndicate list breakdown percentages listed as a whole number without the percentage sign "%".

Multiple values are separated by pipe the symbol “|”. Keep the percentages in the same order as the list above.

The total amount for the array must equal up to 100.

string

 

Depends

agency_fee

Policy / Broker / Agency Fee or other revenue-generating fee charged and retained by the brokerage to cover admin costs.

If omitted 0 (zero) amount will be imported

decimal(12, 2)

 

inspection_fee

Inspection / Audit / Underwriting Fee or fee retained or required to be charged by the carrier.

If omitted 0 (zero) amount will be imported

decimal(12, 2)

 

sl_tax

Surplus Lines Tax (name may vary slightly by state).

The requirement depends on the Agency account setting if tax import is optional.

If left null, 0 (zero) amount will be imported.

decimal(12, 2)

 

stamping_fee

Stamping Fee (name may vary slightly as FSLO fee in Florida).

The requirement depends on the Agency account setting if tax import is optional.

If applicable in the state and the amount is left null, then 0 (zero) amount will be imported.

decimal(12, 2)

 

sl_service_charge

Currently active only in the states of OR and MS.

If applicable in the state and the amount is left null, then 0 (zero) amount will be imported.

decimal(12, 2)

 

municipal_fee

Currently active only in KY.

If applicable in the state and the amount is left null, then 0 (zero) amount will be imported.

decimal(12, 2)

 

fm_tax

Fire Marshal Tax based on Line of Business. Active in IL, OR, MT, and SD and is based on premium amount.

The requirement depends on the Agency account setting if tax import is optional.

If applicable in the state and the amount is left null, then 0 (zero) amount will be imported.

decimal(12, 2)

 

empa_tax

EMPA tax is active in the state of FL and is based on Line of Business. This value is also used (field is renamed on the UI) as the CT Healthy Home Assessment for property type coverages in CT.

If applicable in the state and the amount is left null, then 0 (zero) amount will be imported.

decimal(12, 2)

 

total

We recommend leaving this as null

total amount = premium + all taxes + all policy fees.

If omitted, the system will sum up and import the total automatically.

decimal(12, 2)

 

commission_received

Is commission received? Currently only applies to NH.

Yes = 1
No = 0

If the commission is received, policy fees cannot be charged. If omitted, a 0 (zero) value will be imported.

tinyint(1)

 

mailing_insured_name

Full insured name as it appears in policy documents

varchar(100 )

 

mailing_address

Insured mailing address

varchar(255 )

 

mailing_address2

Insured mailing address line 2 (if applicable)

varchar(255 )

 

mailing_city

Insured mailing city

varchar(100 )

 

mailing_zip_code

Insured mailing zip code

varchar(20)

 

mailing_state_code

Insured mailing state. 2 letter state code abbreviation.

Example: "CA" = California or "FL" = Florida

varchar(20)

 

insured_entity

Insured entity types are used for states that may consider certain entity types tax exempt. If omitted, "commercial" will be used.

Insured Entity Types are listed below:

Import Code
individual
commercial
governmental
federal
tribal
hospital_alliance
state_approved_tax_exempt

Currently only applies to SC, NC, TN & FL. If known, this can be imported for every state and InsCipher will ignore the value in the states where it isn't applicable. 

varchar(100 )

 

Depends

physical_same_as_mailing

If the Physical State is the same as the Mailing State, then set this value = 1

If the Physical State is NOT the same as the Mailing State, set this value = 0.

IMPORTANT: If you make the physical state the same as the mailing state then you will need to make sure that both addresses are added with valid "States" codes or you will receive an import error.

tinyint(1)

 

physical_address

Physical address

Required if Physical State is NOT the same as Mailing State.

varchar(255 )

 

Depends

physical_address2

Physical address line 2

varchar(255 )

 

Depends

physical_city

Physical City

Required if Physical State is NOT the same as Mailing State.

varchar(100 )

 

Depends

physical_zip_code

Physical zip code

Required if Physical State is NOT the same as Mailing State.

varchar(20)

 

Depends

physical_state_code

Physical state. 2 letter state code

Required if Physical State is NOT the same as Mailing State.

varchar(20)

 

Depends

retail_producer_name

Retail Producer Name

Required in WA, OR, and AK only if the business is written through a Retail Agent/Producer.

varchar(255)

 

Depends

retail_agency_name

Retail Agency Name

Required in WA, OR, and AK only if the business is written through a Retail Agent/Producer.

varchar(255)

 

Depends

retail_address

Retail Producer’s Address Line 1

Required in WA, OR, and AK only if the business is written through a Retail Agent/Producer.

varchar(255 )

 

Depends

retail_address2

Retail Producer’s Address Line 2

Required in WA, OR, and AK only if the business is written through a Retail Agent/Producer.

varchar(255 )

 

Depends

retail_city

Retail Producer City Location

Required in WA, OR, and AK only if the business is written through a Retail Agent/Producer.

varchar(100 )

 

Depends

retail_state

Retail Producer State Location

Required in WA, OR, and AK only if the business is written through a Retail Agent/Producer.

varchar(20)

 

Depends

retail_zip

Retail Producer Zip Code Location

Required in WA, OR, and AK only if the business is written through a Retail Agent/Producer.

varchar(20)

 

Depends

sop_name

Service Of Process Name

Currently, only applies to AL.

Service of Process (aka service of suit) is a clause used in the event of a failure to pay amounts claimed under the policy, insurers agree to submit to any court of competent jurisdiction in the US to accept summonses and complaints. If asked for in the portal, including the Service of Process information that is included in the policy documents.

varchar(100 )

 

Depends

sop_address

Service Of Process Address

Currently, only applies to AL.

varchar(255)

 

Depends

sop_address_2

Service Of Process Address 2(if applicable)

Currently, only applies to AL.

varchar(255)

 

Depends

sop_city

Service Of Process City

Currently, only applies to AL.

varchar(100)

 

Depends

sop_state

Service Of Process State. 2 letter state code

Currently, only applies to AL.

varchar(20)

 

Depends

sop_zip

Service Of Process Zip Code

Currently, only applies to AL.

varchar(20)

 

Depends

dc_naic

Declining Carrier NAIC Code

Declining Carrier is an admitted insurance carrier that has declined the request for coverage.

Multiple values are separated by pipe symbol “|”.

Currently, only applicable in SC, TN.

Here is a mapping sheet that describes all of the declining carrier fields. 

varchar(255)

 

Depends

dc_date_declined

Declining Carrier Date Declined

Not Active currently - as additional states are added, this field may become relevant. We do have a plan to add additional declining state requirements to speed up the filing process and eventually automate diligent effort forms. For now, you can exclude this field in your request or if you do add it, it will be ignored on the import. 

For future logic, if added, multiple values are separated by pipe symbol “|” and is required if there are multiple NAIC codes. If you want to view the states that eventually will begin requiring this field, please see this mapping sheet and use the filter to show those fields that are inactive.

date (yyyy-mm-dd)

NOT ACTIVE

 

dc_declining_reason

Declining Carrier Declining Reason

Not Active currently - as additional states are added, this field may become relevant. We do have a plan to add additional declining state requirements to speed up the filing process and eventually automate diligent effort forms. For now, you can exclude this field in your request or if you do add it, it will be ignored on the import. 

For future logic, if added, multiple values are separated by pipe symbol “|” and is required if there are multiple NAIC codes. The value imported would be the reason why the admitted carrier declined to write the business. This value imported is a state-specific reason and should be one of the options provided. If you want to view the states that eventually will begin requiring this field, please see this mapping sheet and use the filter to show those fields that are inactive.

 varchar(255)

NOT ACTIVE

 

dc_underwriting_consideration

Declining Carrier Underwriting Consideration.

Not Active currently - Eventually, will only be applicable to NY. For now, you can exclude this field in your request or if you do add it, it will be ignored on the import. 

For future logic, if added, multiple values are separated by pipe symbol “|” and are required if there are multiple NAIC codes. The value imported would be the underwriting consideration used when binding the policy. This value imported is a state-specific reason and should be one of the options provided. If you want to view the states that eventually will begin requiring this field, please see this mapping sheet and use the filter to show those fields that are inactive.

varchar(255)

NOT ACTIVE

 

dc_representative_name

Declining Carrier Representative Name

Not Active currently - Eventually, will only be applicable to NY. For now, you can exclude this field in your request or if you do add it, it will be ignored on the import. 

For future logic, if added, multiple values are separated by pipe symbol “|” and are required if there are multiple NAIC codes. The value imported will be the representative name. IIf you want to view the states that eventually will begin requiring this field, please see this mapping sheet and use the filter to show those fields that are inactive.

varchar(255)

NOT ACTIVE

 

dc_representative_title

Declining Carrier Representative Title

Not Active currently - Eventually, will only be applicable to NY. For now, you can exclude this field in your request or if you do add it, it will be ignored on the import. 

For future logic, if added, multiple values are separated by pipe symbol “|” and are required if there are multiple NAIC codes. The value imported would be the representative name. If you want to view the states that eventually will begin requiring this field, please see this mapping sheet and use the filter to show those fields that are inactive.

varchar(255)

NOT ACTIVE 

 

dc_representative_email

Declining Carrier representative Email

Not Active currently - Eventually, will only be applicable to NY. For now, you can exclude this field in your request or if you do add it, it will be ignored on the import. 

For future logic, if added, multiple values are separated by pipe symbol “|” and are required if there are multiple NAIC codes. The value imported would be the representative name. If you want to view the states that eventually will begin requiring this field, please see this mapping sheet and use the filter to show those fields that are inactive.

varchar(255)

NOT ACTIVE 

 

dc_representative_phone_number

Declining Carrier representative Phone Number

Not Active currently - Eventually, will only be applicable to NY. For now, you can exclude this field in your request or if you do add it, it will be ignored on the import. 

For future logic, if added, multiple values are separated by pipe symbol “|” and are required if there are multiple NAIC codes. The value imported would be the representative name. If you want to view the states that eventually will begin requiring this field, please see this mapping sheet and use the filter to show those fields that are inactive.

varchar(255)

NOT ACTIVE

 

agent_notes

Agent Notes

Populates the Agent Notes section on the Filing Details page of a Filing Agent/Filing Agency Admin user.

Include only if you want to add other information about the policy not captured in any of the other fields.

varchar (255)

 

umr_number

Lloyd's transaction number

Required in NJ and MS if Lloyd's is a carrier on the policy.

varchar(20)

 

Depends

sla_transaction_number

NJ Transaction Number (Format XXXXX-XX-XXXXX)

Required in NJ

Numeric (12) 

XXXXX-XX-XXXXX

 

Depends

wind_storm_exclusion

Windstorm Exclusion Flag

Flag on whether or not windstorm exclusion applies. Only applied to certain property coverages and only applies in TX and FL.

TRUE = 1
FALSE = 0

tinyint(1)

 

Depends

eligable_for_windstorm

Eligible For Windstorm Pool?

Only applied to certain property coverages and only applies in FL. 

TRUE = 1
FALSE = 0

Boolean

 

Depends 

wind_storm_deductible

Windstorm/Hurricane Deductible

Amount of windstorm/hurricane deductible related to certain property coverages. Only applies in FL. 

If not applicable, leave blank.

decimal(12, 2)

 

Depends

windstorm_primary_amount

Windstorm Primary Amount (Coverage A)

Amount related to certain property coverages. Only applies in FL. 

If not applicable, leave blank.

decimal(12, 2)

 

Depends

other_coverages_deductible

All Other Perils Deductible

Amount related to all other deductibles not mentioned in the other fields above. Only applies in FL. 

If not applicable, leave blank.

decimal(12, 2)

 

Depends

lloyds_cover_holder_number

According to LLoyd's, Cover Holder is a company or partnership authorized by a Managing Agent to enter into a contract or contracts of insurance to be underwritten by the members of a syndicate managed by it in accordance with the terms of a Binding Authority. 

For additional details please see here

varchar (255 )

 

lloyds_cover_holder_name

According to LLoyd's, Cover Holder is a company or partnership authorized by a Managing Agent to enter into a contract or contracts of insurance to be underwritten by the members of a syndicate managed by it in accordance with the terms of a Binding Authority. 

For additional details please see here

varchar (255 )

 

transaction_documents

Section for uploading transactional documents (Policies, Diligent Effort forms, etc.) during API submission. If omitted, documents will need to be added separately using the document import API. Or they can be added manually to the filing details page for each policy.

(see below)

 

Depends

   └ code

Document import code examples can be viewed here

varchar

 

 

   └ url

Full document URL that can be accessed by our system and downloaded.

For security reasons, many of our clients use a temporary URL (expiring after 120 mins) with a one-time use token.

varchar (255 )

 

└ id

The unique document ID number. This is optional and used for import tracking purposes only.

integer(11)

 

 

Mapping Fees and Tax Titles

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 agency, policy, broker, filing, or other revenue-generating or reimbursement fees charged by or retained by the broker that are not mandated by the carrier.

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

It is important that when doing an import into InsCipher, that 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:

    1. sl_tax - Surplus Lines Tax
    2. stamping_fee - Stamping Fee
    3. sl_service_charge - Surplus Lines Service Charge
    4. fm_tax - Fire Marshall Tax
    5. empa_tax - EMPA Tax
    6. 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. 

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

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, documents can be imported via API separately. In order to do so, you will need to use the transaction number assigned by InsCipher to a policy transaction previously imported or use the same "invoice_number" value used when importing the transactional detail. For more information, go here.

Immediate Response Format

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

Success Response

{
"batch_id": "818b1a7f66c0f6f53de2248b8eb417d5",
"transactions": [
{
"id": "20190923002",
"policy_number": "CA20170228-09",
"transaction_id": 34748,
"status": 0,
"status_message": "Processing"
}]
}

 

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

Get Import Results Request

HTTP method:

GET 

Get Import results (HTTP method: GET)

https://surpluslines.inscipher.com/api/v4/transaction-import-results.json?apikey=xxxxx&batch_id=yyyyyy

Success Response

 {
"batch_id": "912a654e961bb083981145c344ca40c6",
"status": "processed",
"transactions": [
{
"id": "201909240000000001",
"policy_number": "CA20170228-05",
"transaction_id": 34859,
"status": 0,
"status_message": "Success"
}]
}

Success Response + Warnings

 {
"batch_id": "912a654e961bb083981145c344ca40c6",
"status": "processed",
"transactions": [
{
"id": "201909240000000001",
"policy_number": "CA20170228-05",
"transaction_id": 34859,
"status": 0,
"status_message": "Success",
"warnings": {
"lineOfBusiness": "Line of business is invalid.",
"total": "Transaction total values don't match. Provided - 4224.80. Calculated - 3407.98",
"slTax": "SL tax values don't match. Provided - 117.00. Calculated - 93.26",
"stampingFee": "Stamping fee values don't match. Provided - 7.80. Calculated - 6.22"
}
}]
}

Error Response

 {
"batch_id":"f6272344cc2b5dccdaf24c9120ab77de",
"status": "processed",
"transactions":[
{
"id":"00001",
"policy_number":"ABC 0099",
"status":1001,
"status_message":"Error: missing required document with code 'POLIC'."
}]
}

Response Status (Batch) Codes

Status

Description

accepted

Batch is accepted and scheduled for processing (transactions are not imported yet)

waiting_for_processing

Batch is waiting for processing

in_progress

Batch processing is in progress

partial_processed

Batch is partially processed - part of the import processing failed (this status is very unlikely - force majeure)

processed

Batch is processed

failed

Batch processing failed

Response Status Codes

Code

Name

0

OK, accepted (Step 1), success (Step 2)

1001

Error: Missing required documents

1002

Error: Transaction type not found

1003

Error: Transaction line of business is missing or invalid

1004

Error: Department not found

1005

Error: Unable to assign tax rule

1006

Error: ECP (Exempt commercial purchaser) not provided

1010

Error: Insurance company not provided

1011

Error: Multi-State value not provided

1012

Error: Customer physical state code is invalid

1013

Error: Description of risk not found by real state and import code

1014

Error: Transaction invoice number already exists in the system

1015

Error: Missing state is required when physical address same as mailing

2001

Error: Missing required fields

3001

Error: Duplicate transaction is submitted

5001

Error: Mailing insured name cannot be empty

5003

Error: Agent cannot file in state

6001

Error: upload document … size is too big, xMB is allowed

6002

Error: document … are not reachable

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Available Warning Messages

 Message

Description

total

Transaction total values don\'t match. Provided - %.2f. Calculated - %.2f

"Transaction total values don't match. Provided - 4224.80. Calculated - 4100.00"

policyLimit

policyLimit value %s are empty or not numerical. "policyLimit value ***** are empty or not numerical"

insuranceCompany

"Insurance company is invalid."
"Insurance company is missing."

slTax

SL tax values don\'t match. Provided - %.2f. Calculated - %.2f "SL tax values don't match. Provided - 117.00. Calculated - 0.00"

stampingFee

Stamping fee values don\'t match. Provided - %.2f. Calculated - %.2f

"Stamping fee values don't match. Provided - 7.80. Calculated - 0.00"

premium

State requires to round %spremium amount to nearest dollar. Imported %.2f, required %.2f

fmTax

FM tax values don\'t match. Provided - %.2f. Calculated - %.2f "FM tax values don't match. Provided - 5.00. Calculated - 0.00"

slServiceCharge

"SL service charge values don't match. Provided - 5.00. Calculated - 0.00"

SL service charge values don\'t match. Provided - %.2f. Calculated - %.2f

empaTax

"Empa tax values don't match. Provided - 7.00. Calculated - 0.00"

Empa tax values don\'t match. Provided - %.2f. Calculated - %.2f

syndicateList

"Total syndicate list coverage has to be 100%. (5 digits

precision are supported)"

Total syndicate list coverage has to be 100%%. (%s digits

precision are supported)

"Syndicate list breakdown is missing."

lineOfBusiness

"Line of business is missing."

"Line of business is invalid."

"Line of business breakdown is missing."

insuranceCompanyItems

"Total insurance company list coverage has to be 100%. (5 digits precision are supported)"

Total insurance company list coverage has to be 100%%. (%s digits precision are supported)

"Insurance Company List breakdown is missing, or incorrect list codes provided."

rpgName

"Purchasing group name not provided (RPG = 'yes')."

ecp

"ECP not provided."

How Do I View And Correct Batch Import Errors?

  1. If there are errors, you can go to the "Filings Import Log" page to identify the transactions that have errors and correct them.
  2. If there are many errors that came through on a batch, you can delete the entire batch by clicking the "Delete" button on the batch:
  3. When pulling up the error code list, you will see the reason for the error followed by the policy number that was trying to be uploaded.
  4. You will then need to go into the batch and correct the error.

Change History

DATE DESCRIPTION OF CHANGE
9/16/2022 New fields added: insured_entity, property_limit, layered_risk, broker_of_record, risk_retention_group, multiple sos and dc fields. Updated formatting on a number of fields and clarified some descriptions. Added new mapping report for Declining Carrier and Policy Limit details.
6/8/2022 Add information related to the new API to import documents feature.
3/14/2022 Added windstorm exclusion and deductible fields.
2/1/2022 Added links to new FS Mapping Packet, UMR number, SLA transaction number, and clarified language related to syndicate list.
12/6/2021 Added new Transaction Types to the mapping section
8/27/2021 Added new fields of UMR Number and NJ Transaction number (v4.2)
8/17/2021 Added section for mapping tax titles and fees (v4.1)
7/28/2021 Update format to Version History
7/20/2021 Changed description of Export List being set to NULL > to being set to "0" and added version history.
7/13/2021 Updated description of GET Status Response
7/3/2021 Released V 4.0