Single Transaction Import
Import single transactions & documents into InsCipher
Introduction
The Single Transaction Import API allows the programmatic import of single transactional policies and documents into InsCipher's online portal.
URL
POST /api/v1/single/transaction
Field Requirements
Click to open the dialog below. Fields shaded in red are strictly required for a successful transaction.
Request Fields
| Field | Description | Type | Example Value (Default) |
|---|---|---|---|
| batch_id | Unique batch identifier (UUID format). If one is not provided, it will be autogenerated. | string | 8df5f4d7-3aaf-4937-9e6e-bad6b929f98a |
| total_items | Total transactions in batch (must be > 0) | integer | 1 |
| current_item | Current transaction index (must be > 0) | integer | 1 |
| transaction (object) | |||
| id | Unique tracking ID for imported transactions | varchar(255) | 201702028950 |
| policy_number | Policy identifier with state-specific length limits | varchar(50) | CA20170228-05 |
| policy_effective_date | Policy start date (uses transaction date if empty) | date/datetime | 2017-02-01 |
| policy_expiration_date | Policy end date (defaults to 12 months from effective date) | date/datetime | 2018-02-01 |
| transaction_effective_date | Endorsement/transaction execution date | date | 2017-02-01 |
| expiring_policy_number | Previous policy ID (required for renewals) | varchar(50) | CA20170228-04 |
| invoice_date | State-specific invoicing date (GA=Revenue Date, HI=Issued Date) | date | 2017-02-01 |
| invoice_number | Internal tracking ID from agent interface | varchar | INVN-10001 |
| transaction_type | Transaction category (PN, PR, APE, RPE, AE, FC, ZPE, BD, RW, EE, OS, PC) | varchar(50) | PN |
| policy_type | Policy classification (standard/master/cert/reporting_form) | string | standard |
| account_written_as | Brokerage account type (B=Brokerage, DC=Direct Commission) | varchar(50) | B |
| rpg | Risk Purchasing Group indicator (1=Yes, 0=No) | tinyint(1) | 1 |
| layered_risk | Layered risk coverage flag | tinyint(1) | 1 |
| broker_of_record | Broker change indicator | tinyint(1) | 1 |
| risk_retention_group | Risk retention status | tinyint(1) | 1 |
| purchasing_group_name | Required when RPG=1 | varchar(255) | Cal Association |
| risk_description | State-specific risk codes (NY/OH/PA have special requirements) | varchar(255) | General Accidental Coverage |
| ecp | Exempt Commercial Purchaser status | tinyint(1) | 0 |
| exempt | Tax exemption status (Utah-required) | tinyint(1) | 0 |
| multi_state | Multi-state liability indicator | tinyint(1) | 0 |
| policy_limit | Aggregate liability amount (required in 12+ states) | integer(12) | 0 |
| property_limit | Property coverage limit | integer(12) | 0 |
| line_of_business_list (array of objects) | |||
| item | LOB code (GEN-1001, etc) | string | "GEN-1001" |
| coverage | Premium allocation for this LOB | float | 3108.5 |
| insurance_company_list (array of objects) | |||
| item | NAIC code | string | "24856" |
| coverage | Percentage allocation | integer | 100 |
| syndicate_list (array of objects) | |||
| item | Syndicate code | string | "AA-1120131" |
| coverage | Percentage allocation | integer | 60 |
| transaction_line_of_business | Coverage code(s) using pipe separator | integer(11)/string | GEN-1001 |
| transaction_line_of_business_coverage | Premium breakdown percentages | string | N/A |
| non_admitted_insurer_code | Carrier NAIC codes (Lloyd's: AA-1122000) | varchar(255) | AA-1122000 |
| non_admitted_insurer_code_coverage | Percentage allocations | string | N/A |
| premium | Base policy amount | decimal(12,2) | 3108.50 |
| agency_fee | Brokerage service fee | decimal(12,2) | 200.00 |
| inspection_fee | Underwriting audit fee | decimal(12,2) | 0.00 |
| collection_fee | Payment processing fee | decimal(12,2) | 1.11 |
| sl_tax | Surplus lines tax | decimal(12,2) | 117.00 |
| stamping_fee | State filing fee | decimal(12,2) | 7.80 |
| sl_service_charge | OR/MS-specific service charge | decimal(12,2) | 0.00 |
| municipal_fee | KY-specific municipal fee | decimal(12,2) | 0.00 |
| fm_tax | IL Fire Marshal Tax | decimal(12,2) | 0.00 |
| empa_tax | FL EMPA tax | decimal(12,2) | 0.00 |
| total | Auto-sum of premium + fees | decimal(12,2) | 4224.80 |
| commission_received | NH commission status flag | tinyint(1) | 0 |
| mailing_insured_name | Policy document name | varchar(100) | Westfield Galleria at Roseville |
| mailing_address | Primary mailing address | varchar(255) | 1151 Galleria Blvd |
| mailing_address2 | Secondary mailing address | varchar(255) | N/A |
| mailing_city | Mailing city | varchar(100) | Roseville |
| mailing_zip_code | Mailing ZIP code | varchar(20) | 95678 |
| mailing_state_code | 2-letter state code | varchar(20) | CA |
| insured_entity | Entity type (individual/commercial/governmental) | varchar(100) | individual |
| insured_email | Contact email | varchar(100) | producer@demo.none |
| insured_phone | Contact phone | varchar(100) | 212-456-7890 |
| insured_county | Mailing county | varchar(100) | Washington |
| physical_same_as_mailing | Address equivalence flag | tinyint(1) | 1 |
| physical_address | Primary physical address | varchar(255) | 1151 Galleria Blvd |
| physical_address2 | Secondary physical address | varchar(255) | N/A |
| physical_city | Physical city | varchar(100) | Roseville |
| physical_zip_code | Physical ZIP code | varchar(20) | 95678 |
| physical_state_code | 2-letter state code | varchar(20) | CA |
| agent_id | Agency/agent identifier | integer | 1 |
| agent_notes | Internal policy notes | varchar | test notes |
| transaction_documents (array of objects) | |||
| code | Document type code from tax rules API | varchar(255) | D1DISC |
| url | Temporary authenticated document URL | varchar(255) | https://example.com/doc.png |
| id | Document tracking ID | varchar(255) | 1000001 |
| type | Document source type (url/base64) | varchar(255) | url |
| cookie_url | Optional authentication cookie URL | varchar(255) | null |
| document_payload | Base64 encoded content (required for type=base64) | string | KQdiXprAD=dNwYJKODNh=PJBKNP0Ym |
| document_filename | File name for base64 payloads | varchar(255) | policy.pdf |
| sop_name | Service of Process name (AL-required) | varchar(100) | SOP Name |
| declining_carriers (array of objects) | |||
| naic | Declining carrier NAIC code (pipe-separated for multiple) | varchar(255) | 54267 |
| date_declined | Declination date(s) in yyyy-mm-dd format | date | 2017-02-02 |
| declining_reason | State-specific reasons (CA: Capacity, Underwriting, etc.) | varchar(255) | other |
| underwriting_consideration | NY-specific factors (Recent transactions, Advertising, Media) | varchar(255) | Considered |
| representative_name | Contact name(s) for declined carriers | varchar(255) | John Doe |
| representative_title | NY-specific roles (Company Employee/Agent/Other) | varchar(255) | Agent |
| representative_email | Contact emails (pipe-separated) | varchar(255) | demo@demo.com |
| representative_phone_number | Contact phone numbers | varchar(255) | 465 |
| representative_website | Official carrier websites | varchar(255) | demo.com |
| dc_naic | Declining carrier NAIC codes | varchar(255) | 54267|37816|49865 |
| dc_date_declined | Declination dates | date | 2017-02-02|2017-02-03 |
| dc_declining_reason | State-specific rejection reasons | varchar(255) | wrong|bad|incorrect |
| dc_underwriting_consideration | NY-specific underwriting factors | varchar(255) | Demo|Test|Considered |
| retail_producer_name | Retail agent name (WA/OR/AK) | varchar(255) | Producer Name |
| wind_storm_exclusion | TX/FL storm exclusion flag | tinyint(1) | 1 |
| lloyds_cover_holder_number | Lloyd's Binding Authority ID | varchar(255) | N/A |
| migrated | Internal tracking flag | tinyint(1) | 0 |
| associated_producer | Licensed producer ID | varchar(255) | 1234567 |
| stamping_fee_invoice_id | Stamping Fee Invoice ID (InsCipher Connect only) | varchar(255) | INVST-20001 |
| sl_tax_invoice_id | SL Tax Invoice ID field on the Tracking tab in the filing details page of a Filing Agent/Filing Agency Admin User. Only applies to InsCipher Connect clients. | varchar(255) | INVSL-30001 |
| business_group_id | Business Group ID. This is for assigning divisions, regions, or other business groups to a transaction for tracking purposes. Only applies to InsCipher Connect clients. | varchar(255) | Division 1 |
| customer_code | Customer Code. Used for associating specific customer classifications from your management system to a transaction for tracking purposes. | varchar(255) | OPT CUST CODE12 |
| transaction_status | Transaction status (not applicable in UT/ID) | integer | null |
| license_number | License ID. | varchar(255) | null |
| filing_admin | Filing Admin Name. | varchar(255) | null |
| date_filed | Date Filed. If the transaction is imported with a 'Date Filed', it will automatically be imported in a 'Filed' status. | date | 2024-01-01 |
| umr_number | UMR identifier | varchar(255) | - |
| sla_transaction_number | Format: XXXXX-XX-XXXXX (first 5 alphanum) | varchar(255) | IL20170000000 |
| unique_id | Unique identifier | varchar(255) | - |
| stamping_fee_date_paid | Stamping fee payment date | date | 2024-01-01 |
| sl_tax_paid_date | Surplus lines tax payment date | date | 2024-01-01 |
| other_taxes_paid_date | Other taxes payment date | date | 2024-01-01 |
Response Fields
| Field | Description | Type | Example Value (Default) |
|---|---|---|---|
| batch_id | Unique batch identifier | string | 912a654e961bb083981145c344ca40c6 |
| transactions (array of objects) | |||
| id | Unique transaction identifier | string | 201909240000000001 |
| policy_number | Policy identifier | string | CA20170228-05 |
| status | Processing status code | string | 0 |
| status_message | Additional status information | string | - |
Request / Response Examples
{
"batch_id": "8df5f4d7-3aaf-4937-9e6e-bad6b929f98a",
"total_items": 1,
"current_item": 1,
"transaction": {
"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",
"policy_type": "standard",
"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,
"line_of_business_list": [
{
"item": "GEN-1001",
"coverage": 3108.5
}
],
"insurance_company_list": [
{
"item": "24856",
"coverage": 100
}
],
"syndicate_list": [
{
"item": "AA-1126033",
"coverage": 100
}
],
"premium": 3108.5,
"agency_fee": 200,
"inspection_fee": 0,
"collection_fee": 1.11,
"sl_tax": 117,
"stamping_fee": 7.8,
"sl_service_charge": 0,
"municipal_fee": 0,
"fm_tax": 0,
"empa_tax": 0,
"total": 4224.8,
"commission_received": 0,
"mailing_insured_name": "Westfield Galleria at Roseville",
"mailing_address": "1151 Galleria Blvd",
"mailing_address2": "",
"mailing_city": "Roseville",
"mailing_zip_code": "95678",
"mailing_state_code": "CA",
"insured_entity": "individual",
"insured_email": "producer@demo.none",
"insured_phone": "212-456-7890",
"insured_county": "Washington",
"physical_same_as_mailing": 1,
"physical_address": "1151 Galleria Blvd",
"physical_address2": "",
"physical_city": "Roseville",
"physical_zip_code": "95678",
"physical_state_code": "CA",
"agent_id": 1,
"agent_notes": "test notes",
"transaction_documents": [
{
"code": "D1DISC",
"url": "https://www.google.com/logos/doodles/2017/abdual-sattar-edhis-89th-birthday-5757526734798848-res.png",
"id": "1000001",
"type": "url",
"cookie_url": null,
"document_payload": "KQdiXprAD=dNwYJKODNh=PJBKNP0Ym",
"document_filename": "policy.pdf"
}
],
"sop_name": "SOP Name",
"sop_address": "Demo street 1",
"sop_address_2": "2nd floor",
"sop_city": "Winthrop",
"sop_state": "WA",
"sop_zip": "98862",
"declining_carriers": [
{
"naic": "54267",
"date_declined": "2017-02-02",
"declining_reason": "other",
"underwriting_consideration": "Considered",
"representative_name": "John Doe",
"representative_title": "Agent",
"representative_email": "demo@demo.com",
"representative_phone_number": "465",
"representative_website": "demo.com"
}
],
"dc_who_received_the_declinations": "Other Person Office",
"dc_other_person_in_office": "Some Other Person",
"dc_who_performed_diligent_search": 1,
"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",
"retail_producer_license": "",
"retail_agency_license": "",
"retail_phone_number": "",
"retail_email_address": "",
"wind_storm_exclusion": 1,
"wind_storm_eligible_for_pool": 1,
"wind_storm_deduction": 0,
"wind_storm_primary_amount": 0,
"wind_storm_other_coverages_deductible": 0,
"lloyds_cover_holder_number": "",
"lloyds_cover_holder_name": "",
"migrated": 0,
"associated_producer": "1234567",
"stamping_fee_invoice_id": "INVST-20001",
"sl_tax_invoice_id": "INVSL-30001",
"business_group_id": "Division 1",
"customer_code": "OPT CUST CODE12",
"transaction_status": null,
"license_number": null,
"filing_admin": null,
"date_filed": "2024-01-01",
"umr_number": "",
"sla_transaction_number": "IL20170000000",
"unique_id": "",
"stamping_fee_date_paid": "2024-01-01",
"sl_tax_paid_date": "2024-01-01",
"other_taxes_paid_date": "2024-01-01"
}
}{
"batch_id": "912a654e961bb083981145c344ca40c6",
"transactions": [
{
"id": "201909240000000001",
"policy_number": "CA20170228-05",
"status": "0",
"status_message": ""
}
]
}{
"message": "Validation error!",
"errors": {
"transaction.transaction_documents[0].cookie_url": "The cookie URL must be a valid URL or null."
},
"metadata": [
"string"
]
}Updated 6 days ago