# InsCipher Developer Portal

> Developer documentation for InsCipher API, integrations, and platform tools.

import { IframeSnippet } from '../components/IframeSnippet'

## Tax Calculator Widget

The InsCipher Tax Calculator Widget gives surplus lines professionals instant access to accurate E\&S tax calculations directly within their existing internal tools. Embedded via iframe, the widget requires no software installation and integrates seamlessly into your agency management system, broker portal, or carrier platform.

The widget supports three methods for entering policy data:

* **Manual entry** — input premium, state, and policy details directly into the form fields.
* **AI document extraction** — upload a surplus lines quote, binder, or policy document and the widget's AI engine automatically extracts key fields — including gross premium, effective dates, and insured details — and pre-fills the form.
* **AI chat entry** — describe the risk or paste policy details into the chat interface, and the widget intelligently maps the information to the appropriate form fields.

Upon submission, the widget returns a complete surplus lines tax breakdown, including:

* State surplus lines taxes
* Stamping office fees (where applicable)
* Municipal taxes (Kentucky only)
* Total taxes and fees due

Along with the tax calculation, the widget surfaces relevant state-specific compliance documents, such as diligent effort forms and stamping office filing instructions, to support your end-to-end placement workflow.

### Embedding the Widget

To embed the widget, add the following snippet to any page on your internal site or portal:

```html
<iframe src="YOUR_WIDGET_URL" width="100%" height="800px" frameborder="0"></iframe>
```

Replace `YOUR_WIDGET_URL` with the URL provided by your InsCipher account manager.

:::warning
The widget URL contains authentication credentials. Do not share it publicly or outside of your organization.
:::

Some platforms require allowlisting the InsCipher domain before the widget will load.

#### SharePoint Example

**Prerequisites** *(optional — only if embedding is blocked)*

Ensure `surpluslines.inscipher.com` is added to the SharePoint **HTML embed allowlist**: SharePoint admin center → **Settings** → **HTML embed allowlist**. If you are not the admin, forward this to your IT team.

**Embed the widget**

1. Open an existing SharePoint page and click **Edit**, or create a new page.
2. Click the **+** icon and search for **Embed** in the web parts list.
3. Select **Embed**.
4. Paste the <IframeSnippet /> into the **"Website address or embed code"** field.
5. Click **Publish**.

:::note
If you see "Embedding content from this website isn't allowed", the InsCipher domain has not yet been added to the allowlist — see Prerequisites above.
:::

*The widget embedded in a SharePoint page:*

<img src="/images/tax_calculator_widget.png" alt="Tax Calculator Widget embedded in SharePoint" style={{width: '80%'}} />

### Using the Widget

#### Calculate Taxes

##### AI-Assisted Mode (Default)

1. On the widget's main screen, upload a policy PDF, or type the policy details directly into the chat.
2. The widget will extract the relevant fields and pre-fill the form automatically.
3. Review all pre-filled values carefully before proceeding.

:::warning
Automated detection is not 100% error-free — always verify the values are accurate and complete.
:::

4. Click **Calculate Taxes**.

##### Manual Mode

1. Click **Enter Details Manually** in the top right corner of the widget.
2. Fill out the fields.
3. Click **Calculate Taxes**.

#### Review and Download Results

After clicking **Calculate Taxes**, the widget displays a **Calculation Result** screen with two tabs:

##### Taxes Tab

Shows a full breakdown of the calculation including state, premium, line of business, transaction type, all applicable taxes and fees, total amount due, state stamp wording, and document notes.

Click **Download PDF** to save the full tax breakdown.

##### State Documents Tab

Shows state-specific documents split into two sections:

* **Required Uploads** — documents that must be attached, with filing, binding, and signature requirements indicated for each.
* **Optional/Reference** — additional documents provided for reference.

Click **Download** next to individual documents or **Download All** to save all at once.

To start over, click **Start New Calculation**. To go back and edit the form, click **Back to Form**.


import { PayloadTroubleshooter } from '../components/PayloadTroubleshooter'

## Payload Troubleshooter — Test Page

<PayloadTroubleshooter />


## Configuration

A webhook configuration tells InsCipher what event to listen for, where to send it, and which states it applies to. Configurations are set up with the InsCipher team — <a href="https://www.inscipher.com/contact">contact InsCipher Sales</a> if you are a new client, or <a href="mailto:support@inscipher.com">InsCipher Support</a> if you are an existing client.

### Configuration fields

| Field                  | Description                                                                                                                                     | Required |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Title                  | A name for the webhook.                                                                                                                         | Yes      |
| Description            | Notes about the webhook, for your own reference.                                                                                                | No       |
| Event                  | The single event this webhook subscribes to. See <a href="/webhooks/event-reference/batch-events">Event Reference</a> for the available events. | Yes      |
| URL                    | The full endpoint URL that receives the `POST` request.                                                                                         | Yes      |
| States                 | The US states this configuration applies to. At least one state is required.                                                                    | Yes      |
| Header Key             | An optional custom header name sent with each request. See [Custom headers](#custom-headers).                                                   | No       |
| Header Value           | The value paired with the header key.                                                                                                           | No       |
| Subscriber emails      | One or more email addresses that receive failure notifications.                                                                                 | No       |
| Report by email        | Whether failed deliveries trigger an email notification. Enabled by default.                                                                    | No       |
| Report by notification | Whether failed deliveries trigger a system notification. Enabled by default.                                                                    | No       |

:::note
A new webhook is **disabled** when first created. It must be enabled before InsCipher will send any events to it.
:::

### One event per configuration

Each configuration subscribes to exactly one event. To receive multiple event types, create a separate configuration for each.

### State-specific configuration

Most events are routed by state: an event is delivered only if the transaction's state is among the states selected on the configuration. This lets you apply one event to a few states and another event to all states, independently.

:::note
Batch events (`webhook.batch.status.processed` and `webhook.batch.status.failed`) are **not** routed by state — a batch can span multiple states, so the state selection does not filter these events. The states field is still required when creating any configuration.
:::

### Custom headers

You can add one custom header (a single key/value pair) to every request from a configuration — useful for an additional authentication token or a routing tag on your side.

The header key must be a single word with no spaces. The allowed characters are letters, digits, and the following symbols:

```
' ` # $ % & * + . ^ _ | ~ ! -
```

Characters outside this set (including spaces, `@`, `/`, `:`, `;`) are rejected.

:::note
Only one custom key/value pair is supported per configuration. The HMAC signature is sent separately in the `X-HMAC-Signature` header — see <a href="/webhooks/security">Request Security & Validation</a>.
:::


## Overview

InsCipher notifies a custom endpoint of yours with a JSON request body whenever a specific platform event occurs.

Webhooks are HTTP callbacks that fire when an event happens inside the InsCipher platform — a status change, a payment date update, and so on. When the event occurs, InsCipher sends a `POST` request containing event data to a URL you configure. This removes the need to poll the API for changes, which is especially useful for automating surplus lines tax filing and compliance workflows.

This section covers how to configure webhooks, how to secure and validate the requests you receive, and the exact payload of every event.

### How delivery works

1. An event occurs in InsCipher (for example, a transaction's status changes to *Filed*).
2. InsCipher builds a JSON payload describing the event.
3. InsCipher sends a `POST` request to the endpoint URL on your matching webhook configuration.
4. Your server processes the request and responds with a `2xx` status code to acknowledge receipt.
5. InsCipher records the response for that webhook so it can be reviewed later.

The direction matters: with webhooks, **InsCipher calls your endpoint** — the opposite of a normal API call where you call InsCipher.

### Event categories

Events are grouped by the InsCipher entity they relate to:

* **Batch** — events about a transaction import (a batch of transactions).
* **Transaction** — events about an individual transaction, including filing status, SLA number, and state stamp wording.
* **Taxes & Fees** — events about surplus lines tax and stamping fee paid dates.

### Available events

You can subscribe a webhook configuration to one event. To receive more than one event type, create more than one configuration.

| Event description                          | Event code                                           |
| ------------------------------------------ | ---------------------------------------------------- |
| Batch Status updated to "Processed"        | `webhook.batch.status.processed`                     |
| Batch Status updated to "Failed"           | `webhook.batch.status.failed`                        |
| Transaction Status updated to "Filed"      | `webhook.transaction.status.filed`                   |
| Transaction SLA Number updated             | `webhook.sla.number.updated`                         |
| Transaction Stamping Fee Paid Date updated | `webhook.transaction.stamping-fee-paid-date.updated` |
| Transaction SL Tax Paid Date updated       | `webhook.transaction.sl-tax-paid-date.updated`       |
| State Stamp Wording updated                | `webhooks.state_stamp_wording.updated`               |

:::note
The State Stamp Wording event code begins with `webhooks.` (plural) and uses underscores, unlike the other six which begin with `webhook.` (singular). Match the exact string when routing events on your side.
:::

### Request format

Every request is a `POST` with a JSON body. The following headers are sent:

| Header             | Always sent                   | Description                                                                                                                        |
| ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`     | Yes                           | Always `application/json`.                                                                                                         |
| `X-HMAC-Signature` | Only if an HMAC secret is set | SHA-256 HMAC of the request body, used to verify authenticity. See <a href="/webhooks/security">Request Security & Validation</a>. |
| Custom header      | Only if configured            | An optional single key/value pair you define in the configuration.                                                                 |

Each event also includes its own JSON payload. See the individual event pages for the full body of every event.

### Responses and failures

Your endpoint must respond with a `2xx` status code within **3 seconds**. Any non-`2xx` response, a connection error, or a timeout is treated as a failed delivery.

InsCipher records the most recent response from your endpoint (status and body) on the webhook configuration, so you can review the last delivery result.

:::note
InsCipher attempts to deliver each event **once**. If the delivery fails, no automatic retry occurs — a failure notification is sent instead.
:::

### Failure notifications

When a delivery fails, InsCipher can notify you in two independent ways, each toggled separately on the configuration:

* **System notification** — a message in the InsCipher notifications tray. Controlled by the *report by notification* setting.
* **Email notification** — an email to the subscriber addresses on the configuration. Controlled by the *report by email* setting, and only sent if at least one subscriber email is set.

Both notifications include the event ID, the response status, and the response body. The email also attaches the undelivered request body as `failed_webhook_request_body.json` for debugging.

A failed delivery during a **test send** (initiated by InsCipher, not by you) is labeled as a test in the notification, and its event ID is `0`.

### Limitations

Webhook requests are processed through a system queue. There are no published rate limits; if you notice delivery delays, report them through a support ticket.

import { WebhooksOverviewPage } from '../../components/WebhooksOverviewPage'

<WebhooksOverviewPage cardsOnly />


## Request Security & Validation

Verify the authenticity of every webhook request with an HMAC signature.

InsCipher strongly recommends verifying incoming webhook requests using an HMAC (Hash-based Message Authentication Code). When an HMAC secret is configured, InsCipher signs each request, letting your endpoint confirm that the request genuinely came from InsCipher and was not altered in transit. This protects your server against forged or tampered webhook notifications.

### Before you start

* This feature is available to Filing Agency Admins and Agency Admins.
* The HMAC secret is generated from the InsCipher portal and shown **only once**. Store it securely. If it is lost, generate a new one.
* Treat the secret like a password. Only technical administrators responsible for generating and storing it should have access.
* You can work with the InsCipher team to send test requests to your endpoint, so you can validate your HMAC implementation in a staging environment before going live.

### How the signature works

When an HMAC secret is set for the receiving account, InsCipher adds an `X-HMAC-Signature` header to every webhook request. The signature is computed as:

```
X-HMAC-Signature = HMAC-SHA256( request_body, your_secret )
```

Where:

* `request_body` is the raw JSON body of the request, exactly as sent.
* `your_secret` is the HMAC secret generated in the portal.

The algorithm is **SHA-256**. If no HMAC secret is set, the `X-HMAC-Signature` header is omitted.

:::note
The signature is computed over the serialized JSON body. Validate against the raw bytes you receive, before any reformatting or re-serialization, so your computed value matches.
:::

### Steps to generate and validate

#### 1. Generate your secret

Generate the secret from the InsCipher portal:

* **Filing Agency Admin:** In the portal settings, go to **Connectivity Settings** → **Get New HMAC Secret**.
* **Agency Admin:** In the portal, go to **Settings → Connectivity Settings → Get New HMAC Secret**.

The secret is copied to your clipboard and shown only once. Paste it into secure storage immediately.

#### 2. Implement your validation function

On your endpoint, compute an HMAC-SHA256 of the raw request body using your stored secret, then compare it to the value in the `X-HMAC-Signature` header. If they match, the request is authentic and unmodified.

Use a constant-time comparison to avoid timing attacks.

```python
import hmac
import hashlib

def is_valid(raw_body: bytes, signature_header: str, secret: str) -> bool:
    computed = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(computed, signature_header)
```

```javascript
const crypto = require("crypto");

function isValid(rawBody, signatureHeader, secret) {
  const computed = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signatureHeader)
  );
}
```

#### 3. Configure your endpoint

Make sure your endpoint accepts `POST` requests and can read the `X-HMAC-Signature` header. Once validation works, continue to <a href="/webhooks/configuration">Configuration</a> to set up your endpoint URL, select an event, and choose the states the webhook applies to.

:::tip
Reject any request whose signature does not match, and any request missing the `X-HMAC-Signature` header when you expect one. Do not process the payload until the signature is verified.
:::


## Batch Events

Events about a transaction import — a batch of transactions imported together. Batch webhooks can only be configured at the Agency Admin level.

Batch events are **not routed by state**: a batch can span multiple states, so the states selected on the configuration do not filter these events.

### Batch Status updated to "Processed"

Fires when a batch finishes processing and moves to the `processed` status.

**Event code:** `webhook.batch.status.processed`

#### When it fires

* A user uploads a CSV through the Batch Importer in the portal.
* A batch is imported via an integration or the Transaction Import API.

#### Payload

The top-level object describes the batch. The `transactions` array contains the full data for each transaction in the batch.

| Field          | Type    | Description                                                                   |
| -------------- | ------- | ----------------------------------------------------------------------------- |
| `event_id`     | integer | ID of the delivery log entry. `0` for test sends.                             |
| `event`        | string  | `webhook.batch.status.processed`.                                             |
| `timestamp`    | string  | When the event was created (`YYYY-MM-DD HH:MM:SS`).                           |
| `sent_at`      | string  | When the request was sent (`YYYY-MM-DD HH:MM:SS`).                            |
| `batch_id`     | string  | The batch identifier.                                                         |
| `status`       | string  | The batch processing status.                                                  |
| `transactions` | array   | The transactions in the batch. See [Transaction object](#transaction-object). |

#### Example

```json
{
  "event_id": 12,
  "event": "webhook.batch.status.processed",
  "timestamp": "2024-09-10 07:51:27",
  "sent_at": "2024-09-10 07:51:27",
  "batch_id": "e455acef2249e49bb04476226750f9fc",
  "status": "processed",
  "transactions": [
    {
      "policy_number": "AAM05001801",
      "unique_id": "abc-123",
      "transaction_id": 167254,
      "transaction_type": "PN",
      "transaction_status": 2,
      "mailing_insured_name": "Acme LLC",
      "physical_state": "CA",
      "invoice_number": "15245",
      "status_message": "Submitted",
      "date_filed": null,
      "warnings": [
        "Required document is missing",
        "Line of business is invalid"
      ]
    }
  ]
}
```

### Batch Status updated to "Failed"

Fires when a batch fails to process due to an internal system error. These failures are rare.

**Event code:** `webhook.batch.status.failed`

#### When it fires

A batch of transactions or documents imported into InsCipher fails to process and needs attention. Subscribing lets you react immediately rather than discovering the failure later.

#### Payload

The structure mirrors the processed event but adds an `errors` field, and the `transactions` array contains the raw imported rows that were not processed (a reduced set of fields).

| Field          | Type    | Description                                                             |
| -------------- | ------- | ----------------------------------------------------------------------- |
| `event_id`     | integer | ID of the delivery log entry. `0` for test sends.                       |
| `event`        | string  | `webhook.batch.status.failed`.                                          |
| `timestamp`    | string  | When the event was created (`YYYY-MM-DD HH:MM:SS`).                     |
| `sent_at`      | string  | When the request was sent (`YYYY-MM-DD HH:MM:SS`).                      |
| `batch_id`     | string  | The batch identifier.                                                   |
| `status`       | string  | The batch processing status.                                            |
| `errors`       | string  | A description of the failure. Currently always `Internal system error`. |
| `transactions` | array   | The unprocessed import rows. See fields below.                          |

Each item in `transactions` for a failed batch contains the raw imported values, any of which may be `null`:

| Field                   | Type           | Description                             |
| ----------------------- | -------------- | --------------------------------------- |
| `id`                    | string \| null | The row's ID, if present in the import. |
| `unique_id`             | string \| null | The row's unique ID, if present.        |
| `policy_number`         | string \| null | Policy number, if present.              |
| `policy_effective_date` | string \| null | Policy effective date, if present.      |
| `invoice_number`        | string \| null | Invoice number, if present.             |
| `agent_id`              | string \| null | Agent ID, if present.                   |

#### Example

```json
{
  "event_id": 170,
  "event": "webhook.batch.status.failed",
  "timestamp": "2025-04-03 09:53:35",
  "sent_at": "2025-04-03 09:53:35",
  "batch_id": "b0b11d49e06e265b66eb3a02a7d3f2e4",
  "status": "failed",
  "errors": "Internal system error",
  "transactions": [
    {
      "id": "12345",
      "unique_id": "as.d.as.d.aasd",
      "policy_number": "XLC1919",
      "policy_effective_date": "2024-12-10",
      "invoice_number": "52882",
      "agent_id": "5"
    }
  ]
}
```

### Transaction object

For a **processed** batch, each item in `transactions` describes a full transaction:

| Field                   | Type           | Description                                                                                                                                             |
| ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `policy_number`         | string         | The policy number.                                                                                                                                      |
| `unique_id`             | string         | The transaction's unique ID.                                                                                                                            |
| `transaction_id`        | integer        | The InsCipher transaction ID.                                                                                                                           |
| `transaction_type`      | string         | The transaction type short code.                                                                                                                        |
| `transaction_status`    | integer        | The transaction's lifecycle status. Common values: `1` Saved, `2` Submitted, `4` Filed, `5` Archived.                                                   |
| `mailing_insured_name`  | string         | The mailing insured name.                                                                                                                               |
| `physical_state`        | string         | The physical state abbreviation.                                                                                                                        |
| `invoice_number`        | string         | The invoice number.                                                                                                                                     |
| `status_message`        | string         | A human-readable status label.                                                                                                                          |
| `date_filed`            | string \| null | The filing date (`YYYY-MM-DD`), or `null` if not filed.                                                                                                 |
| `warnings`              | array          | Present only if the transaction has warnings. A list of warning messages.                                                                               |
| `transaction_documents` | array          | Present only if the transaction has documents. See <a href="/webhooks/event-reference/transaction-events#transaction-documents">Transaction Events</a>. |


## Taxes & Fees Events

Events about surplus lines tax and stamping fee paid dates on a transaction.

### Stamping Fee Paid Date updated

Fires when a transaction's Stamping Fee Paid Date is updated.

**Event code:** `webhook.transaction.stamping-fee-paid-date.updated`

#### Payload

| Field                      | Type           | Description                                                     |
| -------------------------- | -------------- | --------------------------------------------------------------- |
| `event_id`                 | integer        | ID of the delivery log entry. `0` for test sends.               |
| `event`                    | string         | `webhook.transaction.stamping-fee-paid-date.updated`.           |
| `timestamp`                | string         | When the event was created (`YYYY-MM-DD HH:MM:SS`).             |
| `sent_at`                  | string         | When the request was sent (`YYYY-MM-DD HH:MM:SS`).              |
| `policy_number`            | string         | The policy number.                                              |
| `transaction_id`           | integer        | The InsCipher transaction ID.                                   |
| `invoice_number`           | string \| null | The invoice number, if any.                                     |
| `stamping_fee_title`       | string \| null | The stamping fee title for the state, if any.                   |
| `stamping_fee_invoice_id`  | string \| null | The stamping fee invoice ID, if any.                            |
| `stamping_fee_paid_date`   | string \| null | The paid date (`YYYY-MM-DD HH:MM:SS`), or `null` if not set.    |
| `stamping_fee_amount`      | number         | The stamping fee amount.                                        |
| `is_stamping_fee_active`   | boolean        | Whether the stamping fee is active.                             |
| `stamping_fee_amount_type` | string         | How the amount is applied: `fixed`, `percentage`, or `unknown`. |

#### Example

```json
{
  "event_id": 62,
  "event": "webhook.transaction.stamping-fee-paid-date.updated",
  "timestamp": "2024-11-20 14:19:24",
  "sent_at": "2024-11-20 14:19:24",
  "policy_number": "522-29-12",
  "transaction_id": 18949,
  "invoice_number": "Ce39829289-L398",
  "stamping_fee_title": "Surcharge",
  "stamping_fee_invoice_id": null,
  "stamping_fee_paid_date": "2024-11-20 00:00:00",
  "stamping_fee_amount": 1.2,
  "is_stamping_fee_active": true,
  "stamping_fee_amount_type": "percentage"
}
```

### SL Tax Paid Date updated

Fires when a transaction's Surplus Lines Tax Paid Date is updated.

**Event code:** `webhook.transaction.sl-tax-paid-date.updated`

#### Payload

| Field                     | Type           | Description                                                     |
| ------------------------- | -------------- | --------------------------------------------------------------- |
| `event_id`                | integer        | ID of the delivery log entry. `0` for test sends.               |
| `event`                   | string         | `webhook.transaction.sl-tax-paid-date.updated`.                 |
| `timestamp`               | string         | When the event was created (`YYYY-MM-DD HH:MM:SS`).             |
| `sent_at`                 | string         | When the request was sent (`YYYY-MM-DD HH:MM:SS`).              |
| `policy_number`           | string         | The policy number.                                              |
| `transaction_id`          | integer        | The InsCipher transaction ID.                                   |
| `invoice_number`          | string \| null | The invoice number, if any.                                     |
| `sl_tax_title`            | string \| null | The SL tax title for the state.                                 |
| `sl_service_charge_title` | string \| null | The SL service charge title for the state.                      |
| `sl_tax_invoice_id`       | string \| null | The SL tax invoice ID, if any.                                  |
| `sl_tax_paid_date`        | string \| null | The paid date (`YYYY-MM-DD HH:MM:SS`), or `null` if not set.    |
| `sl_tax_amount`           | number         | The SL tax amount.                                              |
| `is_sl_tax_active`        | boolean        | Whether the SL tax is active.                                   |
| `sl_tax_amount_type`      | string         | How the amount is applied: `fixed`, `percentage`, or `unknown`. |

#### Example

```json
{
  "event_id": 63,
  "event": "webhook.transaction.sl-tax-paid-date.updated",
  "timestamp": "2024-11-08 12:11:02",
  "sent_at": "2024-11-08 12:11:02",
  "policy_number": "-822-",
  "transaction_id": 4982215,
  "invoice_number": null,
  "sl_tax_title": null,
  "sl_service_charge_title": null,
  "sl_tax_invoice_id": null,
  "sl_tax_paid_date": "2024-11-02 00:00:00",
  "sl_tax_amount": 1.5,
  "is_sl_tax_active": true,
  "sl_tax_amount_type": "percentage"
}
```


## Transaction Events

Events about an individual transaction: filing status, SLA number, and state stamp wording.

### Transaction Status updated to "Filed"

Fires when a transaction's status changes to *Filed*.

**Event code:** `webhook.transaction.status.filed`

#### When it fires

* **Manual change (Connect clients):** a user changes a transaction's status to *Filed* on the policy details page, or in bulk via a CSV update.
* **State Export (all clients):** transactions are successfully exported to the state of filing. When this happens, a request is sent for both the state export and for the individual transaction, because both conditions are met.

:::note
For **New York**, a transaction is considered filed after being sent to the state, but still requires the insured's signature on the Stamped Declination Page. The document is returned stamped and named `Stamped Dec Page` in the payload.
:::

#### Two payload shapes

This event has two payload shapes depending on what triggered it:

* **Individual transaction** — no `batch_id` or top-level `status`; `transactions` holds the single transaction.
* **State export** — includes `batch_id` and a top-level `status`; `transactions` holds every transaction in the export.

Distinguish them by the presence of `batch_id` / top-level `status`.

#### Common fields

| Field          | Type    | Description                                                        |
| -------------- | ------- | ------------------------------------------------------------------ |
| `event_id`     | integer | ID of the delivery log entry. `0` for test sends.                  |
| `event`        | string  | `webhook.transaction.status.filed`.                                |
| `timestamp`    | string  | When the event was created (`YYYY-MM-DD HH:MM:SS`).                |
| `sent_at`      | string  | When the request was sent (`YYYY-MM-DD HH:MM:SS`).                 |
| `batch_id`     | string  | **State export only.** The export batch identifier.                |
| `status`       | string  | **State export only.** The export processing status.               |
| `transactions` | array   | The transaction(s). See [Transaction object](#transaction-object). |

#### Example — individual transaction

```json
{
  "event_id": 21,
  "event": "webhook.transaction.status.filed",
  "timestamp": "2024-07-29 12:13:59",
  "sent_at": "2024-07-29 12:13:59",
  "transactions": [
    {
      "policy_number": "ID PREMIUM 01",
      "unique_id": "abc-123",
      "transaction_id": 165235,
      "transaction_type": "PN",
      "transaction_status": 4,
      "mailing_insured_name": "Acme LLC",
      "physical_state": "ID",
      "invoice_number": "15245",
      "status_message": "Filed",
      "date_filed": "2024-07-29",
      "warnings": [
        "Retail producer not provided",
        "Line of business is missing"
      ],
      "transaction_documents": [
        {
          "document_id": 65540,
          "document_name": "Policy",
          "document_url": "https://surpluslines.inscipher.com/transaction/document/165235/65540/download",
          "stamped": false
        }
      ]
    }
  ]
}
```

#### Example — state export

```json
{
  "event_id": 31,
  "event": "webhook.transaction.status.filed",
  "timestamp": "2024-07-29 18:33:57",
  "sent_at": "2024-07-29 18:33:57",
  "batch_id": "6f6a0b3a3fb435b504039bcee59dfba9",
  "status": "submission_accepted",
  "transactions": [
    {
      "policy_number": "ent-indv",
      "unique_id": "def-456",
      "transaction_id": 155561,
      "transaction_type": "PN",
      "transaction_status": 4,
      "mailing_insured_name": "Beta Corp",
      "physical_state": "TX",
      "invoice_number": "15250",
      "status_message": "Filed",
      "date_filed": "2024-07-29",
      "transaction_documents": [
        {
          "document_id": 63896,
          "document_name": "Policy",
          "document_url": "https://surpluslines.inscipher.com/transaction/document/155561/63896/download",
          "stamped": false
        }
      ]
    }
  ]
}
```

#### Transaction object

Each item in `transactions` describes a transaction:

| Field                   | Type           | Description                                                                                           |
| ----------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `policy_number`         | string         | The policy number.                                                                                    |
| `unique_id`             | string         | The transaction's unique ID.                                                                          |
| `transaction_id`        | integer        | The InsCipher transaction ID.                                                                         |
| `transaction_type`      | string         | The transaction type short code.                                                                      |
| `transaction_status`    | integer        | The transaction's lifecycle status. Common values: `1` Saved, `2` Submitted, `4` Filed, `5` Archived. |
| `mailing_insured_name`  | string         | The mailing insured name.                                                                             |
| `physical_state`        | string         | The physical state abbreviation.                                                                      |
| `invoice_number`        | string         | The invoice number.                                                                                   |
| `status_message`        | string         | A human-readable status label.                                                                        |
| `date_filed`            | string \| null | The filing date (`YYYY-MM-DD`), or `null` if not filed.                                               |
| `warnings`              | array          | Present only if the transaction has warnings. A list of warning messages.                             |
| `transaction_documents` | array          | Present only if the transaction has documents. See below.                                             |

#### Transaction documents

Each item in `transaction_documents`:

| Field           | Type    | Description                                                                          |
| --------------- | ------- | ------------------------------------------------------------------------------------ |
| `document_id`   | integer | The document ID.                                                                     |
| `document_name` | string  | The document name.                                                                   |
| `document_url`  | string  | An absolute URL to download the document.                                            |
| `stamped`       | boolean | `true` only when the document name is exactly `Stamped Dec Page`; otherwise `false`. |

### SLA Number updated

Fires when a transaction's SLA Transaction Number is updated.

**Event code:** `webhook.sla.number.updated`

#### When it fires

The primary use case is **Illinois**, where a Countersignature Number is assigned to each transaction to confirm the filing was received by SLAI (Surplus Line Association of Illinois). Subscribers use this event to retrieve the Countersignature page from SLAI, which must be provided to the insured with the policy documents.

#### Payload

| Field                    | Type           | Description                                                      |
| ------------------------ | -------------- | ---------------------------------------------------------------- |
| `event_id`               | integer        | ID of the delivery log entry. `0` for test sends.                |
| `event`                  | string         | `webhook.sla.number.updated`.                                    |
| `timestamp`              | string         | When the event was created (`YYYY-MM-DD HH:MM:SS`).              |
| `policy_number`          | string         | The policy number.                                               |
| `transaction_id`         | integer        | The InsCipher transaction ID.                                    |
| `invoice_number`         | string         | The invoice number.                                              |
| `sla_transaction_number` | string         | The SLA transaction (countersignature) number.                   |
| `mailing_insured_name`   | string         | The mailing insured name.                                        |
| `physical_state`         | string         | The physical state abbreviation.                                 |
| `date_filed`             | string \| null | The filing date (`YYYY-MM-DD HH:MM:SS`), or `null` if not filed. |

This event does not include a `sent_at` field.

#### Example

```json
{
  "event_id": 164,
  "event": "webhook.sla.number.updated",
  "timestamp": "2025-03-25 10:16:54",
  "policy_number": "123.123.2345",
  "transaction_id": 168947,
  "invoice_number": "123-456-7980",
  "sla_transaction_number": "Test number",
  "mailing_insured_name": "Samuel G Stamas",
  "physical_state": "CA",
  "date_filed": null
}
```

### State Stamp Wording updated

Fires when state stamp wording or Guaranty Fund Notice notes change for a state.

**Event code:** `webhooks.state_stamp_wording.updated`

:::note
This event code begins with `webhooks.` (plural) and uses underscores, unlike the other events.
:::

#### When it fires

* **State stamp wording updated**: the stamp wording text, formatting (font size, italic, bold, color), or instructions for a state are changed.
* **Guaranty Fund Notice notes updated**: the Guaranty Fund Notice notes for a state are changed.

#### Payload

The payload has a fixed base, followed by six stamp wording properties that are **always present**. A `previous_` counterpart is included only for properties that actually changed in this event.

Fixed base fields:

| Field            | Type    | Description                                                                               |
| ---------------- | ------- | ----------------------------------------------------------------------------------------- |
| `event_id`       | integer | ID of the delivery log entry. `0` for test sends.                                         |
| `event`          | string  | `webhooks.state_stamp_wording.updated`.                                                   |
| `timestamp`      | string  | When the event was created, in ISO 8601 with timezone (e.g. `2025-06-06T09:44:40+00:00`). |
| `state_code`     | string  | The state abbreviation.                                                                   |
| `state`          | string  | The state name.                                                                           |
| `effective_date` | string  | When the stamp wording configuration took effect, in ISO 8601 with timezone.              |

The six stamp wording properties are always sent regardless of whether they changed. For each property that did change, a `previous_` field is also included with the prior value. The six properties are: `state_stamp_wording_text`, `state_stamp_wording_instructions`, `fontSize`, `italic`, `bold`, and `color`.

:::note
Unlike the other events, the State Stamp Wording `timestamp` and `effective_date` use ISO 8601 format with timezone. The other events use `YYYY-MM-DD HH:MM:SS` without timezone.
:::

#### Example

```json
{
  "event_id": 598,
  "event": "webhooks.state_stamp_wording.updated",
  "timestamp": "2025-06-06T09:44:40+00:00",
  "state_code": "AL",
  "state": "Alabama",
  "effective_date": "2025-06-06T00:00:00+00:00",
  "state_stamp_wording_text": "<p>This is my new stamp wording description...</p>",
  "previous_state_stamp_wording_text": "<p>This was my previous stamp wording description...</p>",
  "state_stamp_wording_instructions": "This is my new instruction block...",
  "previous_state_stamp_wording_instructions": "This was my previous instruction block...",
  "fontSize": 23,
  "italic": true,
  "previous_italic": false,
  "bold": false,
  "previous_bold": true,
  "color": "red"
}
```


## Microsoft Azure

## Microsoft Azure SSO Setup

If your organization already uses Microsoft Entra ID (formerly Azure Active Directory), you can integrate it with the InsCipher Connect® portal for a faster, more secure login experience. Once enabled, your users will authenticate through Microsoft instead of a legacy username/password.

:::warning
**Email addresses must match.** The email address associated with each user's Microsoft account must exactly match the email address registered for that user in the InsCipher portal. Mismatched emails will prevent login.
:::

***

### Before You Begin

* You need **Microsoft Entra ID admin access** to complete the setup (the Azure portal account must be able to register applications in your tenant).
* InsCipher uses **OAuth** (not SAML).
* You will need to create a **user group** in Azure and associate your filing team's Microsoft accounts to that group.
* Once SSO is enabled, users will no longer be able to log in with their legacy InsCipher username/password.
* Make sure your users are aware of this change before enabling SSO.

***

### 1. Register an App in Microsoft Entra ID

1. Sign in to the **Azure portal** and search for **Microsoft Entra ID**.
2. In the left menu, under **Manage**, select **App registrations**.
3. Click **+ New registration**.
4. Enter a meaningful **Name** for the app (for example, `InsCipher SSO`).
5. Under **Supported account types**, select **Accounts in this organizational directory only** (recommended for most organizations).
6. Click **Register**. You'll land on the app's **Overview** page.

:::tip
Microsoft updates the Azure portal UI periodically. For the current step-by-step screens, see Microsoft's official guide: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
:::

***

### 2. Add the Callback URL

In your app registration, under **Manage**, select **Authentication** → on the **Redirect URI configuration** tab, select **Add Redirect URI** → choose the **Web** platform, then add the following redirect (callback) URL:

```
https://surpluslines.inscipher.com/sso/connect/check/azure
```

See Microsoft's guide: [Add a redirect URI](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri).

***

### 3. Collect Your Credentials

You will need to securely send the following parameters to the InsCipher implementation team:

| Parameter                   | Where to find it                                                                             |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| **Application (client) ID** | App registration → **Overview** page                                                         |
| **Tenant ID**               | App registration → **Overview** page (listed as *Directory (tenant) ID*)                     |
| **Client Secret**           | App registration → **Certificates & secrets** → **+ New client secret** → copy the **Value** |

**Getting the Application (client) ID and Tenant ID:**
Open your app registration and go to the **Overview** page. Both values are shown in the Essentials section — copy the **Application (client) ID** and the **Directory (tenant) ID**. See Microsoft's guide: [Find your tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant).

**Getting the Client Secret:**
In your app registration, under **Manage**, select **Certificates & secrets** → **Client secrets** → click **+ New client secret**. Add a description, choose an expiry, and click **Add**. See Microsoft's guide: [Add a client secret](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials).

:::warning
Copy the secret **Value** immediately — it is shown only once and cannot be retrieved later. Be sure to copy the **Value**, not the **Secret ID** (the Secret ID is not used for authentication).
:::

***

### 4. Send Credentials to InsCipher

Share the three parameters above securely with your InsCipher implementation specialist. They will configure the integration on the portal side.

***

### How Login Works After Activation

Once SSO is enabled:

1. Users go to [https://surpluslines.inscipher.com](https://surpluslines.inscipher.com).
2. They click the **Login with SSO** button on the login screen.
3. They enter their Microsoft Exchange email address.
4. On first login, they are prompted to enter their Microsoft password.
5. After the first successful login, the portal stores a session cookie — future logins only require the email address.

:::warning
After SSO is activated, users who attempt to change their InsCipher password will see a message indicating that password management is disabled. This is expected behavior. Direct password changes are no longer available once SSO is active.
:::

![Password edit page showing SSO-locked message](/images/password-locked.png)

***

### Ongoing Maintenance

If any of the Azure credentials (Application ID, Client Secret, or Tenant ID) change, you must update them in the portal. You have two options:

* **Contact InsCipher support** to request the update.
* **Update yourself:** Go to User Settings → click **Authentication Providers Setup** in the top-right corner of the page → update the relevant fields.

![Authentication Providers Setup button in User Settings](/images/auth-provider-settings.png)


## Okta SSO Setup

If your organization already uses Okta, you can integrate it with the InsCipher Connect® or Filing Services® portal for a faster, more secure login experience. Once enabled, your users will authenticate through Okta instead of a legacy username/password.

:::warning
**Email addresses must match.** The email address assigned to each user in Okta must exactly match the email address registered for that user in the InsCipher portal. Mismatched emails will prevent login.
:::

***

### Before You Begin

* You need **Okta admin access** to complete the setup.
* InsCipher uses **OAuth 2.0 / OIDC** (OpenID Connect) with a **Web Application** integration type. SAML is not supported.
* Once SSO is enabled, users will no longer be able to log in with their legacy InsCipher username/password.
* Make sure your users are aware of this change before enabling SSO.

***

### 1. Create an App Integration in Okta

1. Sign in to the **Okta Admin Console** as an administrator.
2. Go to **Applications → Applications**.
3. Click **Create App Integration**.
4. Select **OIDC - OpenID Connect** as the sign-in method.
5. Select **Web Application** as the application type, then click **Next**.
6. Enter a name for the app (for example, `InsCipher SSO`).
7. Complete the wizard and assign the applicable users to the new application.

:::tip
Okta updates the Admin Console UI periodically. For the current step-by-step screens, see Okta's official guide: [Create OpenID Connect app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm).
:::

***

### 2. Add the Callback (Sign-In Redirect) URI

In your new Okta app's **General Settings**, add the following sign-in redirect URI:

```
https://surpluslines.inscipher.com/sso/connect/check/okta
```

***

### 3. Collect Your Credentials

You will need to securely send the following parameters to the InsCipher implementation team:

| Parameter         | Where to find it                |
| ----------------- | ------------------------------- |
| **Client ID**     | Okta app settings → General tab |
| **Client Secret** | Okta app settings → General tab |
| **Issuer URL**    | Okta app settings → Sign On tab |

:::note
The Issuer URL must include the `/oauth2` path. For example:
`https://dev-74470422.okta.com/oauth2`
:::

The **Client ID** and **Client Secret** are generated automatically when you save the app, and appear on the app's **General** tab. For details, see Okta's guide: [Create OIDC app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm).

***

### 4. Send Credentials to InsCipher

Share the three parameters above securely with your InsCipher implementation specialist. They will configure the integration on the portal side.

***

### How Login Works After Activation

Once SSO is enabled:

1. Users go to [https://surpluslines.inscipher.com](https://surpluslines.inscipher.com).
2. They click the **OKTA** button on the login screen.
3. They enter their company email address.
4. On first login, they are prompted to enter their Okta password.
5. After the first successful login, the portal stores a session cookie — future logins only require the email address.

:::warning
After SSO is activated, users who attempt to change their InsCipher password will see a message indicating that password management is disabled. This is expected behavior. Direct password changes are no longer available once SSO is active.
:::

![Password edit page showing SSO-locked message](/images/password-locked.png)

***

### Ongoing Maintenance

If any of the Okta credentials (Client ID, Client Secret, or Issuer URL) change, you must update them in the portal. You have two options:

* **Contact InsCipher support** to request the update.
* **Update yourself:** Go to User Settings → click **Authentication Providers Setup** in the top-right corner of the page → update the relevant fields.

![Authentication Providers Setup button in User Settings](/images/auth-provider-settings.png)


import { SsoOverviewPage } from '../../components/SsoOverviewPage'

<SsoOverviewPage />


## Herald API

Surface InsCipher surplus lines taxes and fees inside Herald quotes.

Herald is a **partner-owned (Herald) integration**: Herald operates the API, and InsCipher provides the surplus lines tax and fee data it returns. If you are a Herald customer, your application can retrieve InsCipher-powered surplus lines taxes and fees as part of a quote, with no separate InsCipher integration.

InsCipher is the system of record for all surplus lines taxes and fees surfaced through Herald. Herald manages the API integration itself and attaches any related tax documents returned from InsCipher to the quote.

### How it works

Herald exposes surplus lines tax and fee details through the `priceDetails` object on its quote endpoint. When a request specifies a non-admitted (surplus lines) placement, Herald calls InsCipher behind the scenes and returns the applicable taxes, fees, and document information alongside the rest of the quote.

For the request requirements, response format, and error cases, see Herald's documentation:

* <a href="https://www.heraldai.com/docs/surplus-taxes-and-fees">Surplus Taxes and Fees</a>
* <a href="https://docs.heraldapi.com/">Herald API Reference</a>

### Responsibilities

| Area                                               | Owned by Herald | Owned by InsCipher |
| -------------------------------------------------- | --------------- | ------------------ |
| Herald API and the quote endpoint                  | ✓               |                    |
| Surfacing tax and fee data in `priceDetails`       | ✓               |                    |
| Attaching returned tax documents to the quote      | ✓               |                    |
| Surplus-lines and stamping-fee tax rates           |                 | ✓                  |
| Source of truth for surplus lines tax and fee data |                 | ✓                  |

### Getting started

If you are a Herald customer, see Herald's <a href="https://www.heraldai.com/docs/surplus-taxes-and-fees">Surplus Taxes and Fees</a> documentation for the request requirements and behavior, and the <a href="https://docs.heraldapi.com/">Herald API Reference</a> for the endpoint itself.

If you are not yet a Herald customer, contact Herald's sales team through their <a href="https://meetings.hubspot.com/jean-marc5/introduction-to-herald?uuid=75a0b30d-66e3-4a0e-a145-093accc07c90">introduction booking page</a>.


## Instanda

Calculate surplus lines taxes and sync surplus lines transactions and documents from INSTANDA into InsCipher.

INSTANDA is a no-code policy administration and distribution platform. This **partner-owned (INSTANDA) integration** connects INSTANDA workflows to InsCipher using InsCipher's APIs, configurable to fit your workflow.

### Supported functionality

**Transaction Import** — Surplus lines transactions are automatically retrieved from INSTANDA and pushed into InsCipher.

**Document Import** — Documents associated with surplus lines transactions are retrieved from INSTANDA and pushed into InsCipher.

**Tax Calculation** — Surplus lines tax rates are retrieved inside INSTANDA.

### Responsibilities

| Area                                            | Owned by INSTANDA | Owned by InsCipher |
| ----------------------------------------------- | ----------------- | ------------------ |
| Integration built inside the INSTANDA platform  | ✓                 |                    |
| Configuration and field mapping within INSTANDA | ✓                 |                    |
| InsCipher API endpoints and authentication      |                   | ✓                  |
| Surplus-lines and stamping-fee tax rates        |                   | ✓                  |

### Setup and implementation

These capabilities are not an out-of-the-box InsCipher product. They are a set of configurable solutions built by INSTANDA using InsCipher's APIs, available inside the INSTANDA product.

Setup time varies by customer and by the complexity of the configuration. The following timelines are typical for existing INSTANDA customers adding these features:

| Functionality                                       | Typical timeline |
| --------------------------------------------------- | ---------------- |
| Surplus lines tax calculation / rating              | \~A few days     |
| Sync surplus lines policy transactions to InsCipher | \~1–2 weeks      |
| Sync surplus lines policy documents to InsCipher    | \~1–2 weeks      |

### Getting started

**Existing customers** — Contact your assigned INSTANDA account manager.

**New customers** — If you are not yet an INSTANDA customer and want these features in your workflow, contact <a href="mailto:sales.us@instanda.com">[sales.us@instanda.com](mailto\:sales.us@instanda.com)</a>.


import { IntegrationsOverviewPage } from '../../components/IntegrationsOverviewPage'

## Integrations

Integration products from InsCipher that automate data-intensive tasks to and from your agency management system (AMS).

InsCipher integrations automate key data processes between InsCipher and your AMS. Some integrations are built and maintained by InsCipher; others are built by a partner using InsCipher's APIs. The functionality is similar either way — what differs is who you work with to set it up and who maintains the integration.

### Functionality

InsCipher classifies integration functionality into four primary categories:

<div style={{display:'grid',gridTemplateColumns:'repeat(auto-fill,minmax(280px,1fr))',gap:20,margin:'24px 0'}}>
  <div style={{border:'1px solid var(--vocs-color_border,#e0e0e0)',borderRadius:8,padding:'20px 24px'}}>
    <p style={{fontWeight:600,fontSize:15,margin:'0 0 8px'}}>Transaction Import</p>
    <p style={{fontSize:14,color:'var(--vocs-color_text2,#555)',margin:0,lineHeight:1.5}}>Surplus lines transactions are automatically retrieved from the AMS and pushed into InsCipher. This processing usually occurs nightly at around 2 AM MST.</p>
  </div>

  <div style={{border:'1px solid var(--vocs-color_border,#e0e0e0)',borderRadius:8,padding:'20px 24px'}}>
    <p style={{fontWeight:600,fontSize:15,margin:'0 0 8px'}}>Document Import</p>
    <p style={{fontSize:14,color:'var(--vocs-color_text2,#555)',margin:0,lineHeight:1.5}}>Documents associated with surplus lines transactions are retrieved from the AMS and pushed into InsCipher.</p>
  </div>

  <div style={{border:'1px solid var(--vocs-color_border,#e0e0e0)',borderRadius:8,padding:'20px 24px'}}>
    <p style={{fontWeight:600,fontSize:15,margin:'0 0 8px'}}>Tax Calculation</p>
    <p style={{fontSize:14,color:'var(--vocs-color_text2,#555)',margin:0,lineHeight:1.5}}>Functionality for retrieving surplus lines tax rates inside of the AMS.</p>
  </div>

  <div style={{border:'1px solid var(--vocs-color_border,#e0e0e0)',borderRadius:8,padding:'20px 24px'}}>
    <p style={{fontWeight:600,fontSize:15,margin:'0 0 8px'}}>Payment Batch Reconciliation</p>
    <p style={{fontSize:14,color:'var(--vocs-color_text2,#555)',margin:0,lineHeight:1.5}}>Automates the population of payment reconciliation batches to the AMS to quickly and easily update payables.</p>
  </div>
</div>

### Supported systems

InsCipher integrates with several major agency systems, either as an InsCipher product or through a partner that uses InsCipher's functionality. If the system is **InsCipher-owned**, you work with the InsCipher team to set up an integration tailored to your workflow. If it is a **partner-owned** integration, you get similar functionality but go through that partner for setup.

#### InsCipher-owned integrations

| System                                                                         | Transaction Import | Document Import | Tax Calculation | Payment Reconciliation |
| ------------------------------------------------------------------------------ | :----------------: | :-------------: | :-------------: | :--------------------: |
| <a href="/integrations/applied-systems/applied-epic/overview">Applied Epic</a> |          ✓         |        —        |        —        |            —           |
| <a href="/integrations/insurity/concept-one/overview">Concept One</a>          |          ✓         |        —        |        —        |            —           |
| <a href="/integrations/vertafore/aim/overview">AIM</a>                         |          ✓         |        —        |        —        |            ✓           |
| <a href="/integrations/vertafore/ams360/overview">AMS360</a>                   |          ✓         |        —        |        —        |            —           |

#### Partner-owned integrations

| System                                                                     | Partner   | Transaction Import | Document Import | Tax Calculation |
| -------------------------------------------------------------------------- | --------- | :----------------: | :-------------: | :-------------: |
| <a href="/integrations/herald-api">Herald API</a>                          | Herald    |          —         |        —        |        ✓        |
| <a href="/integrations/instanda">Instanda</a>                              | INSTANDA  |          ✓         |        ✓        |        ✓        |
| <a href="/integrations/insurity/isg">Insurity Submission Gateway (ISG)</a> | Insurity  |          ✓         |        ✓        |        ✓        |
| <a href="/integrations/vertafore/surefyre">Surefyre</a>                    | Vertafore |          ✓         |        —        |        ✓        |
| <a href="/integrations/vertafore/mga-systems">Vertafore MGA Systems</a>    | Vertafore |          ✓         |        ✓        |        ✓        |

### Setup timeline

The time to complete integration setup depends on a few factors:

* The type of integration and the functionality you want.
* Your team's internal knowledge of the agency system.
* The resources allocated to field mapping, which is the most time-intensive part of setup.

Time to go-live generally ranges from a few days to about a month, depending on the factors above.

### FAQ

#### Can I upgrade my AMS version if I have an integration with InsCipher?

Yes. InsCipher's integration products are designed so you can update your AMS without disruption. However, **report any changes to your database schema to the InsCipher team** so we can confirm the data mapping isn't affected and minimize any impact to your team's workflow.

***

<IntegrationsOverviewPage />


## Vertafore MGA Systems

:::note
Vertafore MGA Systems was formerly known as Insurance Management Systems (IMS). You may see it referred to as "IMS" in older documentation or in conversation.
:::

Sync surplus lines transactions and documents, and perform tax rate lookups, between Vertafore MGA Systems and InsCipher.

For customers using (or evaluating) Vertafore MGA Systems, this **partner-owned (Vertafore) integration** provides a configurable set of capabilities inside MGA Systems that use InsCipher's APIs to transmit surplus lines policy data and related artifacts into InsCipher. It is configurable to match your workflow and data-mapping requirements.

InsCipher is the system of record for surplus lines and stamping-fee tax rates: InsCipher manages all regulatory updates and rate changes, and MGA Systems retrieves those rates through the API connection so they stay current without manual updates on your side.

### Service models

The capabilities enabled in the integration depend on your InsCipher service agreement.

| Service model | What InsCipher provides                                                                            | What's available in the integration                       |
| ------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| DIY           | Surplus-lines and stamping-fee tax calculations only. You handle your own filings and submissions. | Tax Calculation only.                                     |
| Full-service  | InsCipher calculates, manages, and files taxes on your behalf.                                     | Tax Calculation, Transaction Import, and Document Import. |

Confirm your service agreement with InsCipher before configuration begins — it determines which system settings need to be enabled inside MGA Systems. Using Tax Calculations requires an active contract with InsCipher for the Tax Calculator API.

### Supported functionality

**Transaction Import** — Surplus lines transactions (new business, endorsements, cancellations, and other surplus lines policy transactions) are pushed from MGA Systems into InsCipher one transaction at a time, so you don't re-key policy data after binding.

**Document Import** — Policy-related documents (applications, endorsements, filings, supporting documentation) stored in MGA Systems can be uploaded to InsCipher, providing a full document trail linked to the corresponding surplus lines transactions.

:::note[Document Handler requirement]
Only documents stored within the MGA Systems Document Handler are eligible for sync. Documents stored locally, on shared drives, or in other systems outside MGA Systems cannot be uploaded through the integration. Move compliance documents into the Document Handler before relying on this capability. The policy must also be in **Bound** status before its documents become eligible for upload.
:::

**Tax Calculation** — When you need surplus lines tax rates or jurisdictional tax lookups inside MGA Systems, the integration retrieves rates (or calls InsCipher's tax APIs) and returns the applicable tax calculations and rate metadata into the MGA Systems workflow. Because InsCipher maintains the rate library, you don't need to manually update tax tables when regulations change.

### Responsibilities

The integration spans two systems. The table below shows who handles what.

| Area                                                                        | Owned by Vertafore | Owned by InsCipher |
| --------------------------------------------------------------------------- | ------------------ | ------------------ |
| Integration code inside MGA Systems                                         | ✓                  |                    |
| Configuration UI (fee setup, LOB mapping, InsCipher Administration screens) | ✓                  |                    |
| MGA Systems Document Handler                                                | ✓                  |                    |
| API key provisioning to the customer                                        |                    | ✓                  |
| InsCipher API endpoints and authentication                                  |                    | ✓                  |
| Surplus-lines and stamping-fee tax rates                                    |                    | ✓                  |
| Transaction processing and filing (full-service customers)                  |                    | ✓                  |

For MGA Systems configuration, billing, or product features, start with your Vertafore account manager. For tax calculations, filings, or InsCipher service models, start with your InsCipher technical account manager or support.

### Prerequisites

Before MGA Systems-side configuration begins, confirm:

* The Lines of Business you write (so they can be mapped during setup).
* The companies / carriers writing those Lines of Business.
* Your service agreement with InsCipher (DIY vs. full-service).
* The API key(s) for your subscribed InsCipher services. You are responsible for obtaining these from InsCipher and providing them to Vertafore for configuration.
* That Vertafore's Professional Services team is engaged to perform the system-setting configuration; all required system settings should be enabled before customer-side setup begins.

### Setup and implementation

These features are not an out-of-the-box InsCipher product. They are a partner-owned integration developed by Vertafore that leverages InsCipher APIs, implemented inside MGA Systems as a configurable solution.

At a high level, configuration covers:

* Enabling the InsCipher integration in MGA Systems' system settings, using the provisioned API key(s).
* Configuring fee entries (surplus-lines tax, stamping fee, broker fee, policy fee, state-specific fees) for each state where business is written.
* Setting up InsCipher as a payable entity under Fee Automation.
* Mapping Lines of Business to InsCipher's reference codes inside MGA Systems.
* End-to-end testing of policy submission.

Step-by-step instructions for each are maintained by Vertafore — see Vertafore's product documentation for current setup procedures.

Setup time varies by customer and by the configuration, mapping, and testing required. New MGA Systems customers should also expect Vertafore account setup and product onboarding — contact Vertafore Sales for details. Additional fees may apply from Vertafore depending on the functionality selected.

### Getting started

**Existing Vertafore customers** — Contact your assigned Vertafore account manager or implementation lead to request enablement of the InsCipher integration for MGA Systems. Vertafore coordinates configuration and billing.

**Customers not yet using Vertafore** — Contact Vertafore Sales or your InsCipher sales representative to discuss licensing and implementation options.

**InsCipher API or service questions** — For authentication, sandbox credentials, or questions about the InsCipher side, contact your InsCipher technical account manager or support.


## Surefyre

Calculate surplus lines taxes inside Surefyre and import Surefyre policy transactions into InsCipher.

Surefyre is Vertafore's configurable agent portal and underwriting workbench. This **partner-owned (Vertafore) integration** connects InsCipher's surplus lines tax solutions to Surefyre's workflows.

### Supported functionality

**Tax Calculation** — Retrieve real-time surplus lines tax calculations within Surefyre. For example, supplying premium and line of business returns the correct tax rates for a policy — useful for displaying tax information to an underwriter during quoting, or for accurate tax line items on invoices and mid-term endorsements.

**Transaction Import** — Automatically import policy transactions from Surefyre into InsCipher. For bound transactions, this removes manual data entry and starts the filing automation, where transactions can be reviewed in the InsCipher platform after import.

Most configurations are unique, so these functionalities can sit at different points in a customer's workflow.

### Responsibilities

| Area                                                | Owned by Vertafore | Owned by InsCipher |
| --------------------------------------------------- | ------------------ | ------------------ |
| Integration built inside Surefyre                   | ✓                  |                    |
| Field mapping and workflow triggers within Surefyre | ✓                  |                    |
| InsCipher API endpoints and authentication          |                    | ✓                  |
| Surplus-lines and stamping-fee tax rates            |                    | ✓                  |
| Transaction review and filing (InsCipher platform)  |                    | ✓                  |

### Setup and implementation

These capabilities are not an out-of-the-box InsCipher product. They are configurable solutions built by Vertafore inside Surefyre. Setup is typically handled by Surefyre's professional services team during a new system implementation or as an addition for an existing client.

Setup uses Surefyre's remote call framework to map fields from your Surefyre instance to the required InsCipher API fields. Triggers are then configured in your workflow to determine when API calls are made — for example, retrieving surplus lines tax and fee rates when a quote is generated or a policy is bound. Because the integration affects core financial data used for bordereaux and reporting, it is strongly recommended to work with the Surefyre services team on configuration within the Surefyre transaction module.

### Cost and timeline

Cost and timeline vary by customer need and current setup. Customers setting up a new Surefyre system can generally expect three to six months or more, depending on the complexity of the build, with an implementation fee as part of the larger system setup. Existing customers can expect as little as a few weeks depending on their configuration, with an implementation fee likely applying. Contact Surefyre for accurate details.

### Getting started

**Existing customers** — Contact your dedicated Surefyre account manager to add this integration.

**New customers and other questions** — Reach out to <a href="mailto:bwallace@vertafore.com">[bwallace@vertafore.com](mailto\:bwallace@vertafore.com)</a>.


## Import Policy Data

To connect your AMS360 instance to InsCipher and start importing policy data, complete the four-part process in the InsCipher Integration Wizard.

To open the wizard, log into your Connect® account, then go to the **Settings** cog (top-right) → **Integrations** → **ADD NEW**. Select **Vertafore AMS360** from the dropdown to add the integration.

### 1. Setup & Connection

Enter the credentials gathered during <a href="/integrations/vertafore/ams360/overview">setup</a> — **Email**, **Instance Id**, **Username** (Client ID), and **Password** (Client Secret). These four fields are required to continue to Step 2.

Two optional settings are also available here:

* **Import Transactions in a Saved status** — include transactions that are still in a Saved status.
* **Enable Additional EMS Service** — turns on the EMS connection and reveals the **EMS Settings** fields. Leave it off if your agency doesn't use EMS.

<img src="/images/integrations/ams360/step-1-agency-management-system.png" alt="Integration Wizard Step 1 — Agency Management System settings" style={{width: '80%'}} />

### 2. Initiate Mappings and install API connection

InsCipher establishes the connection to your AMS360 instance and pulls the fields needed for the mapping in Step 3. Unless the wizard reports an API connection error or a problem retrieving mapping data, no manual input is needed here — continue to Step 3.

<img src="/images/integrations/ams360/step-2-connection.png" alt="Integration Wizard Step 2 — Integration Setup & Connection" style={{width: '80%'}} />

### 3. Field Mapping

After the connection completes and the Integration Tool syncs with Connect®, map the data pulled from AMS360 to standard InsCipher values so the two systems stay in parity. You must complete all of these tables before continuing to Step 4:

* Taxes and Fees
* Line of Business (LOB)
* Business Units
* Filing Types
* Insurance Companies

#### Map Taxes and Fees

The integration pulls both the AMS Code and AMS Description for each AMS360 tax or fee. For each AMS Code line item, choose a value in the dropdown under InsCipher Taxable Fees and State Taxes. The options are:

* Do Not Import
* Broker Fee
* Carrier Fee
* Stamping Fee
* Sl Tax
* EMPA Tax
* FM Tax
* Municipal Fee
* Sl Service Charge

<img src="/images/integrations/ams360/map-taxes-and-fees.png" alt="Taxes and Fees mapping table" style={{width: '80%'}} />

#### Map Lines of Business

Map the derived AMS codes for each Line of Business (LOB) to an InsCipher Generic Line of Business code. Use the <a href="https://lookerstudio.google.com/reporting/41dce747-d045-4e1f-884d-07d23581a90a">State Specific to Generic LOB mapping worksheet</a> or the simpler <a href="https://lookerstudio.google.com/reporting/41dce747-d045-4e1f-884d-07d23581a90a/page/p_4q66kh8crc">Generic Lines of Business worksheet</a>. If needed, map specific LOB codes per AMS code under the **InsCipher State Specific Codes** column, where you can select a state and LOB description.

See also Vertafore's reference on <a href="https://help.vertafore.com/ams360/content/contextsensitive/system_admin/cssetuplineofbusiness.htm">Line of Business in AMS360</a>.

<img src="/images/integrations/ams360/map-lines-of-business.png" alt="Line of Business mapping table" style={{width: '80%'}} />

#### Map Business Units

In the **Business Unit Map** section, enable or disable the import of policy data for each AMS360 business unit tag. By default, the integration can pull business unit information down to the Group level. Under the **Import** column, choose whether to enable import; the default state is **Import Disabled**.

See also Vertafore's reference on <a href="https://help.vertafore.com/AMS360/content/contextsensitive/system_admin/cssetupbusinessunit.htm">Business Units in AMS360</a>.

<img src="/images/integrations/ams360/map-business-units.png" alt="Business Unit Map table" style={{width: '80%'}} />

#### Map Filing Types

Filing/transaction type naming differs between AMS360 and InsCipher. The **Filing Types Mapping table** lets you map each type, with the option to use a different type for positive and negative amounts to match your workflow.

AMS360 Policy Transaction Codes appear under the **AMS Transaction Type** column with their **Comments** (description). Map each to an InsCipher transaction type using the InsCipher Positive Premium Filing Code and/or Negative Premium Filing Code dropdowns. The InsCipher transaction types are:

* PN (New Policy)
* PR (Renewal Policy)
* APE (Additional Premium Endorsement)
* RPE (Return Premium Endorsement)
* AE (Audit Endorsement)
* FC (Flat Cancellation)
* ZPE (Zero Premium Endorsement)
* PC (Pro Rata Cancellation)
* XE (Extension Endorsement)
* RI (Reinstatement)
* BO (Back-out / Reversal)
* BD (Binder)

See also Vertafore's reference on <a href="https://help.vertafore.com/AMS360/content/popuptext/ptpolicy_tran_codes.htm">Policy Transaction Codes in AMS360</a>.

<img src="/images/integrations/ams360/map-filing-types.png" alt="Filing Types mapping table" style={{width: '80%'}} />

#### Map Insurance Companies

Insurance Company Code and Name are pulled from AMS360 and shown in the first two columns. In the third column, **InsCipher Insurance Company**, map each AMS360 company to the corresponding Insurance Company on record in InsCipher.

<img src="/images/integrations/ams360/map-insurance-companies.png" alt="Insurance Company mapping table" style={{width: '80%'}} />

### 4. Summary

Step 4 reviews the completed steps and any outstanding issues. When the Summary items are all checked complete, the integration has no outstanding issues.

<img src="/images/integrations/ams360/step-4-summary.png" alt="Integration Wizard Step 4 — Summary" style={{width: '80%'}} />

:::note
A connection made during the day may not populate policy data until the next day, because of the integration's cadence. If data hasn't appeared in the Filings Import Log by the next day, contact InsCipher support.
:::

You can also pull up to two weeks of historical data using **Trigger a Manual Import**. The date picker is limited to two weeks prior to the current date.

<img src="/images/integrations/ams360/trigger-manual-import.png" alt="Trigger a Manual Import" style={{width: '80%'}} />

After submitting a manual import, it can take up to 30 minutes for the data to appear in the Filings Import Log. Any errors or status issues with the integration also appear on this page.

### How the import works

The integration uses an **OData pull model**: InsCipher reads your AMS360 instance directly through Vertafore's OData connection on a daily cadence (typically around 2 AM MST), importing the previous day's activity. A manual import covers a date range you choose.

**How invoices are selected.** InsCipher reads AMS360 **activity** records for the import window and picks up invoices from posting activity (`Invoice (Posting)`) and voids from void activity (`Invoice (Void)`). This is why the three Activity/Suspense checkpoints described in <a href="/integrations/vertafore/ams360/overview#configure-ams360">setup</a> must be enabled. For each posted invoice, InsCipher then loads the related policy and customer.

**What gets skipped.** An invoice is skipped if its business unit is set to **Import Disabled**, if its agency (GL Division) is mapped to **Do Not Import**, or if the policy or customer record can't be found. An invoice is imported only if it is a **surplus-lines policy** — determined when one of its charges maps to SL Tax (or a charge description matches a surplus-lines pattern). Non-surplus-lines invoices are skipped.

**Premium, lines of business, and insurers.** Premium is the sum of the invoice's premium-line amounts. Line of Business and non-admitted insurer (NAIC) values are aggregated per code, with a matching coverage breakdown — for insurers, each NAIC's share is expressed as a percentage of premium. NAIC is resolved from the writing company through your Insurance Company mapping.

**Taxes and fees.** Tax and fee lines are summed into their InsCipher buckets (SL tax, stamping fee, agency/broker fee, inspection/carrier fee, and so on) using your Taxes and Fees mapping. Non-billable policy charges are included in the same way. The transaction total is premium plus all mapped taxes and fees.

**Transaction type.** The InsCipher transaction type is derived from the AMS360 invoice transaction-type code through your Filing Types mapping, resolved by the sign of the premium (the positive or negative mapping you configured).

**Addresses.** The mailing address comes from the customer record. The physical address comes from the policy's first commercial location, if one exists; otherwise the physical address is treated as the same as the mailing address. If a location's state is blank, the import falls back to the customer's state and notes this on the transaction.

**Policy limit.** For states that require it, InsCipher derives the policy limit from the policy's coverage limits.

**Voids.** When an invoice is voided in AMS360 during the import window, InsCipher voids the previously imported transaction — but only when a matching imported transaction exists and hasn't already been voided. Voided invoices are excluded from the regular import.

**Saved status.** If **Import Transactions in a Saved status** is enabled, transactions are imported in a Saved status. Transactions that are missing insurer or line-of-business information are also brought in as Saved so you can review them before filing.

**Defaulted fields.** A few fields are set to fixed values rather than read from AMS360: `rpg`, `dba`, and `multi_state` default to false. `account_written_as` is derived from whether the customer is a broker customer (B for Brokerage, otherwise DC).

### AMS360 field mapping

The table below reflects what the import actually populates. A blank **AMS360 source** means the field is not supplied by the integration. The **Requirement** is the field's status in the shared InsCipher transaction schema; the same tiers apply across all InsCipher integrations. Fields not listed here are not supplied by the AMS360 integration — they are entered in Connect® or required only at state filing time.

**Legend:** R = Required · Rec = Recommended · O = Optional

| InsCipher Field                           | AMS360 source                                        | Notes                                                                                                      | Requirement |
| ----------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------- |
| id                                        | Invoice.InvoiceId                                    |                                                                                                            | O           |
| policy\_number                            | Policy.PolicyNumber                                  |                                                                                                            | R           |
| policy\_effective\_date                   | Policy.EffectiveDate                                 |                                                                                                            | R           |
| policy\_expiration\_date                  | Policy.ExpiryDate                                    |                                                                                                            | Rec         |
| transaction\_effective\_date              | Policy.EffectiveDate or Invoice.InvoiceEffectiveDate | Policy effective date for new business and renewals; invoice effective date otherwise                      | R           |
| invoice\_date                             | Invoice.InvoiceDate                                  |                                                                                                            | Rec         |
| invoice\_number                           | Invoice.InvoiceNumber                                |                                                                                                            | Rec         |
| transaction\_type                         | invoice transaction TransactionType                  | Mapping required; resolved by the sign of premium                                                          | R           |
| account\_written\_as                      | Customer.IsBrokerCustomer                            | Broker customer maps to B (Brokerage); otherwise DC (Direct to Client)                                     | R           |
| rpg                                       | 0                                                    | Hardcoded false                                                                                            | R           |
| dba                                       | 0                                                    | Hardcoded false                                                                                            | O           |
| multi\_state                              | 0                                                    | Hardcoded false                                                                                            | O           |
| risk\_description                         | policy Nature of Business (Description)              |                                                                                                            | O           |
| transaction\_line\_of\_business\_list     | invoice transaction LineOfBusiness                   | Mapped to LOB; aggregated per code, sorted, pipe-joined                                                    | R           |
| transaction\_line\_of\_business\_coverage | invoice transaction GrossAmount                      | Summed per LOB code, pipe-joined                                                                           | R           |
| non\_admitted\_insurer\_code\_list        | invoice transaction WritingCompanyCode → NAIC        | Resolved via the company list and Insurance Company mapping; pipe-joined                                   | Rec         |
| non\_admitted\_insurer\_code\_coverage    | invoice transaction GrossAmount                      | Each insurer's share of premium as a percentage; pipe-joined                                               | Rec         |
| premium                                   | invoice transaction GrossAmount (premium lines)      | Sum of premium-line amounts                                                                                | O           |
| agency\_fee                               | invoice transaction fee/tax lines                    | Broker Fee; summed by Taxes and Fees code mapping                                                          | R           |
| inspection\_fee                           | invoice transaction fee/tax lines                    | Carrier Fee; summed by Taxes and Fees code mapping                                                         | R           |
| sl\_tax                                   | invoice transaction fee/tax lines                    | Summed by Taxes and Fees code mapping                                                                      | O           |
| stamping\_fee                             | invoice transaction fee/tax lines                    | Summed by Taxes and Fees code mapping                                                                      | O           |
| sl\_service\_charge                       | invoice transaction fee/tax lines                    | Summed by Taxes and Fees code mapping                                                                      | O           |
| municipal\_fee                            | invoice transaction fee/tax lines                    | Summed by Taxes and Fees code mapping                                                                      | O           |
| fm\_tax                                   | invoice transaction fee/tax lines                    | Summed by Taxes and Fees code mapping                                                                      | O           |
| empa\_tax                                 | invoice transaction fee/tax lines                    | Summed by Taxes and Fees code mapping                                                                      | O           |
| total                                     | computed                                             | Premium plus all mapped taxes and fees                                                                     | O           |
| insured\_email                            | Customer.EMail                                       |                                                                                                            | O           |
| insured\_phone                            | Customer business phone, or cell phone               | Business phone (with area code) when present; otherwise cell phone                                         | O           |
| policy\_limit                             | policy coverage limits                               | Largest applicable coverage limit; only for states that require a policy limit                             | O           |
| mailing\_insured\_name                    | Customer.FirmName, or FirstName + Last               | Firm name when present; otherwise first and last name                                                      | R           |
| mailing\_address                          | Customer.AddressLine1                                |                                                                                                            | R           |
| mailing\_address2                         | Customer.AddressLine2                                |                                                                                                            | O           |
| mailing\_city                             | Customer.City                                        |                                                                                                            | R           |
| mailing\_zip\_code                        | Customer.ZipCode                                     |                                                                                                            | R           |
| mailing\_state\_code                      | Customer.State                                       |                                                                                                            | R           |
| physical\_same\_as\_mailing               | computed                                             | Set to true (same) when the policy has no commercial location                                              | R           |
| physical\_address                         | Commercial Location.AddressLine1                     | From the first commercial location, when one exists                                                        | Rec         |
| physical\_address2                        | Commercial Location.AddressLine2                     | From the first commercial location                                                                         | O           |
| physical\_city                            | Commercial Location.City                             | From the first commercial location                                                                         | Rec         |
| physical\_zip\_code                       | Commercial Location.ZipCode                          | From the first commercial location                                                                         | Rec         |
| physical\_state\_code                     | Commercial Location.State                            | Falls back to the customer (mailing) state when the location state is blank                                | R           |
| agent\_id                                 | Invoice.GeneralLedgerDivisionCode                    | Mapped via Agency mapping (GL Divisions); invoices whose division is mapped to "Do Not Import" are skipped | O           |
| agent\_notes                              | generated                                            | Generated: "AMS360 Invoice #\<number>, Division: ..."                                                      | Rec         |


## AMS360™

Automates the import of surplus lines policy data from Vertafore AMS360 into InsCipher using Vertafore's OData connection method.

### Ownership & responsibilities

This integration is **built and maintained by InsCipher**. Your agency sets up Vertafore OData access and completes setup inside InsCipher Connect®, with support from the InsCipher team. The table below shows who handles what.

| Area                                                       | InsCipher | Your agency |
| ---------------------------------------------------------- | --------- | ----------- |
| Integration tool and import logic                          | ✓         |             |
| AMS360 OData subscription (via Vertafore)                  |           | ✓           |
| Vertafore Developer Portal OData app and OAuth credentials |           | ✓           |
| AMS360 Activity/Suspense and EMS configuration             |           | ✓           |
| Field mapping in the Integration Wizard                    | ✓         |             |
| Surplus-lines tax rates and compliance updates             | ✓         |             |
| Integration support and maintenance                        | ✓         |             |

:::tip[What this integration does]
Uses Vertafore's OData connection method to automatically retrieve policy data from AMS360 into InsCipher.
:::

:::note[What this integration does not do]
* It cannot pull documents associated with policy data.
* There is no Tax Calculation or Payment Reconciliation functionality yet. Both are being researched for future phases.
:::

### Before you start

This service is not available to all clients. At a minimum, you must be subscribed through Vertafore to the AMS360 **OData connection method**. If you are an AMS360 customer but don't use the OData connection, contact your Vertafore representative or account manager to find out whether it can be set up for your agency.

### Set up Vertafore OData access

This setup happens in Vertafore's Developer Portal. Because Vertafore's portal screens change over time, follow Vertafore's official guide and use the steps below as an outline: <a href="https://help.vertafore.com/devportal/content/getstarted/gettingstarted.htm">Vertafore API Developer Portal — Getting Started</a>.

1. **Obtain a Vertafore API Developer Portal account** for your agency. If you are new to this, work with your Vertafore contact to set it up.
2. **Create a new OData app** under **My Applications** in the <a href="https://developer.vertafore.com/portal/MyApps#/">developer portal</a>. Fill in Name, Description, and Contact Email, and add the application. It starts in *sandbox* mode.
3. **Ask Vertafore support to push the sandbox app to Live.** This adds a Live tab alongside sandbox in your app overview.
4. **Apply the AMS360 OData API and its scopes to the sandbox app.** In the Required APIs block, click View / Manage APIs, set the AMS360 OData API toggle to Yes, then under Scopes click Add/Remove and toggle all scopes to Yes.
5. **Sync the sandbox app's API and scopes to Live.** From the app overview, click Sync Application to Live and confirm. The OData API scopes then appear under Required APIs for the Live app.

Gather these four OAuth credentials from your **Live** app — you will enter them in Step 1 of the InsCipher integration wizard:

| Credential           | Where to find                                                                                                                                            |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email                | My Applications → your Live OData app → Application Information → Contact Email                                                                          |
| Instance / Agency ID | In AMS360 under Agency or Company Information, or shown when selecting the Agency at login. If you can't find it, contact your Vertafore representative. |
| Username             | My Applications → your Live OData app → OAuth Credentials → Show Details → Client ID                                                                     |
| Password             | My Applications → your Live OData app → OAuth Credentials → Show Details → Client Secret                                                                 |

### Configure AMS360

A few settings are required in AMS360 so InsCipher can pull invoice activity. In AMS360, go to the **Administration** tab → **Agency Overview** → **Activity/Suspense Setup**. In the Checkpoints table, enable (check **Active** and **Require Activity**) these three settings (you may need to click **Edit** first):

* Invoice (Posting) Center Billed Only
* Invoice (Void)
* Invoice Correction (Posting)

For the current AMS360 screens, see Vertafore's AMS360 documentation.

#### EMS Settings (optional)

EMS is optional. If your agency uses it, select **Enable Additional EMS Service** in Step 1 of the wizard to reveal the EMS Settings fields, then provide:

* App Key
* Agency No
* EMS Username
* EMS Password

Once you have your OAuth credentials and AMS360 is configured, continue to <a href="/integrations/vertafore/ams360/import-policy-data">Import Policy Data</a> to run the setup wizard.


## Troubleshooting

InsCipher notifies you by email and in the notification center when any of the cases below occur.

### Warnings

Prompts that encourage you to act on something that could lead to an adverse outcome if left too long.

| Title                  | Description                                                    | Suggested action                                        |
| ---------------------- | -------------------------------------------------------------- | ------------------------------------------------------- |
| Integration Incomplete | The system detects an incomplete integration before Step 3.    | Complete the integration steps through Step 3.          |
| Fields Need Mapping    | Required field mapping on Step 3 was started but not finished. | Complete the mapping exercise for all tables on Step 3. |

### Errors

System messages indicating technical problems that lead to partial or lost functionality.

| Title                          | Description                                    | Suggested action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Integration Connection is Lost | The integration tool cannot connect to AMS360. | **1. Reinitiate the AMS360 connection.** In the <a href="https://help.vertafore.com/devportal/content/getstarted/gettingstarted.htm">Vertafore API Developer Portal</a>, go to My Applications → your Live OData app → OAuth Credentials → Manage OAuth Credentials → Edit, then click **Save** without making changes (this re-initiates the connection). **2. Manually import data missed during the outage.** On Step 4 / Summary, click **Trigger a Manual Import** and select the date your connection was lost and your agency stopped receiving data. |

For any other errors, contact <a href="mailto:support@inscipher.com">InsCipher support</a>.


## Create a Payment Batch

How to create a payment reconciliation batch in the Vertafore AIM® accounting module using the InsCipher Connect® State Reporting Task (SRT) feature and integration.

In Vertafore AIM®, creating payment reconciliation batches normally requires selecting transactions (invoices) one at a time, which can take hours in high-volume states and risks human error. InsCipher's engine has the various state reporting and payment rules built in — maintained by InsCipher's compliance team — and automatically groups transactions submitted into Connect® into relevant chunks based on state reporting and payment requirements.

These groups appear in Connect® as a task assigned to a filer or accountant with a state due date. When an SL Tax or Stamping Fee payment is ready, a user clicks a button in Connect® to automatically create a payment reconciliation batch in AIM® in an unposted status.

### Prerequisites

You must be contracted with InsCipher and have the AIM® integration tool set up on your AIM® SQL Server. For setup, see <a href="/integrations/vertafore/aim/import-policy-data">Import Policy Data</a>.

#### Database permissions

Before using this feature, ensure InsCipher is permissioned to perform the following procedures on the AIM® AFD database:

* GetKeyField — function
* spacGetBankAccount — function
* Batchttl — write permission to the table
* spacChkGetPayeeDetail — function
* spacPostActivity — function
* tacCheck — write permission to the table
* AP — read from the table permission
* spacChkCreatePendingPay — function
* spacChkSumCheckAmount — function

:::note
InsCipher does not need permission to the individual tables within every section of the AFD database — only permission to execute the procedures in general.
:::

### Setup

If you have completed the prerequisites, configuring the payment batch feature in Connect® is straightforward:

**Step 1** — Ensure the AIM® integration tool is installed and connected to your SQL database.

**Step 2** — Go to **Setup → Integrations → Details → Step 1 "Agency Management System"**, enable the **Create Payment Batch** setting, and click **Continue** to save, then exit the section.

<img src="/images/integrations/aim/payment-batch-enable.png" alt="Enable Create Payment Batch" style={{width: '80%'}} />

**Step 3** — On the **Field Mapping** page, ensure the **User ID Mapping** is set for each user. This is the user associated with the payment batch created in AIM.

<img src="/images/integrations/aim/payment-batch-user-id-mapping.png" alt="User ID mapping" style={{width: '80%'}} />

**Step 4** — Provide your implementation manager a report with four columns. They will set up your PayeeID mapping in the InsCipher backend settings (a customer-facing mapping table is planned for a later iteration):

1. State
2. TaxCode ID
3. Payee ID
4. Payee Code

:::warning[Important]
This mapping is critical to setup — without it, the feature will not work. Contact your Implementation Manager or support with questions.
:::

### How to create a payment batch

Once set up, create a payment batch from the State Reporting Task module in Connect®.

**Step 1** — In the State Reporting Task module, find a payment task that needs to be completed and open its details page.

**Step 2** — Review the task to confirm the correct transactions are in the **Related Filings** section. You can view the filings via the link or download a CSV to review.

**Step 3** — Once verified and ready to pay, add the **Payment Approved** date. This makes a button appear; click **CREATE PAYMENT BATCH IN AIM**.

<img src="/images/integrations/aim/payment-batch-create-button.png" alt="Create Payment Batch in AIM button" style={{width: '80%'}} />

**Step 4** — Confirm by clicking **YES**. A payment batch is generated in your AIM® accounting database.

<img src="/images/integrations/aim/payment-batch-confirm.png" alt="Payment batch confirmation" style={{width: '80%'}} />

### Response and validation messages

If there are errors, they display. Otherwise you see a success message:

<img src="/images/integrations/aim/created-successfully.png" alt="AIM batch payment created successfully" style={{width: '60%'}} />

The status also appears at the bottom of the Task Details section:

<img src="/images/integrations/aim/pending.png" alt="AIM Payment Batch status — Pending" style={{width: '60%'}} />

A payment batch is created for each PayeeID associated with the AIM® invoice transactions included in the State Reporting Task. The system uses the mapping from setup to create a batch in AIM with the correct PayeeID. If any AIM® invoice transactions have an incorrect PayeeID on the invoice header, they are flagged in the error messages. To view the error message, click the **Summary** link next to the status.

<img src="/images/integrations/aim/failed.png" alt="AIM Payment Batch Summary — failed with Summary link" style={{width: '70%'}} />

:::danger[Caution]
Once the "Create Payment Batch in AIM" action is performed, it cannot be undone or modified within the InsCipher portal. Later modifications must be made directly in Vertafore AIM®.
:::

:::warning[Important]
Only transactions imported into InsCipher using the AIM® integration tool and that have a valid Invoice Number can be exported back into AIM® via payment batches. This feature is not designed to be used separately from importing transactions. Validation errors appear if you attempt to create a payment batch without a valid AIM invoice number.
:::

### Next step

After this action completes, go into AIM® and review the payment batch in the **Tax Payables** section of your AIM® Accounting Module. To edit the batch, do so in Tax Payables. Once it looks correct, post it and continue creating checks.


## Import Policy Data

A guide to automating the import of your agency's policy data from AIM to InsCipher.

The Integration Client automatically extracts relevant surplus lines policy data from your local AIM® database and imports it into Connect® on a daily basis, typically around **2 AM Mountain Standard Time (MST)**. The import selects invoices whose post date falls in the import window and that meet either of these conditions:

* The invoice is **exported and taxed** and is not an installment — from a developer's perspective, `StatusID = "E"`, `Taxed = "Y"`, and `InstallmentFlag = "N"` on the invoice header.
* The invoice is a **memo invoice** in a reviewed or pending status — `MemoInvoiceFlag = "Y"` and `StatusID IN ("R", "P")`.

Invoices in other statuses are not included because they may still change before being exported to accounting; importing only these invoices keeps the transaction list in Connect® cleaner and more current.

In the standard import (no custom view), a transaction is additionally skipped unless at least one of its invoice detail lines is collected by the agency (`CollectedBy = "A"`).

If your agency uses the [custom SQL view](#custom-sql-view-option), these conditions are defined inside your view instead — the integration then selects from the view by post date only.

:::warning[Important]
The InsCipher Integration Tool always runs in the background, even after you reboot your server. All imported batches appear on the **Filings Import Log** page in Connect® for your review.
:::

:::tip
For plans billed in installments, it is best practice to charge the entire SL taxes and fees up front so they can be reported and paid to the state. If a policy later cancels, create an offsetting invoice so you can report the unrealized premium to the state and return the SL taxes and fees to the insured.
:::

:::note
Duplicate transactions with the same Invoice ID are not imported. They appear in the Filings Import Log as "Not Imported" transactions.
:::

### 1. Set up a new integration in InsCipher

Log into your Connect® account, then go to **Setup** in the left navigation → **Integrations** → **ADD NEW** to start the Integration Wizard. The wizard guides you through a four-step process.

<img src="/images/integrations/aim/step-1-agency-management-system.png" alt="Integration Wizard — selecting Vertafore AIM" style={{width: '80%'}} />

* Select **Vertafore AIM** and click **Continue**.
* Select **Create Payment Batch** if you want to use the payment reconciliation feature (see <a href="/integrations/vertafore/aim/create-payment-batch">Create a Payment Batch</a>).
* Under **Choose Physical State Field**, indicate which AIM value to use for the Physical / Tax State in Connect®:
  * **Quote State** pulls from the `Quote.State` field.
  * **Quote Tax State** pulls from the `Quote.TaxState` field.

### 2. Download and initialize the Integration tool

In this step you download and install the InsCipher Integration Tool and receive your InsCipher Integration Token, which you use during installation.

<img src="/images/integrations/aim/step-2-download-token.png" alt="Integration Wizard — download tool and token" style={{width: '80%'}} />

:::warning[Important]
You have **10 minutes** to use the token before you need to regenerate it.
:::

<img src="/images/integrations/aim/integration-tool.png" alt="InsCipher Integration Tool — SQL credentials and token" style={{width: '80%'}} />

During installation, enter your SQL Server login credentials and your Integration Token, then click **Connect** to link to InsCipher. Processing can take a few minutes. If you have trouble connecting, confirm that your SQL login credentials are correct and that the account has read-only access to all AIM tables the IC queries:

* **For mappings:** `Division`, `Coverage`, `InvoiceTranCode`, `Product`
* **For transaction export:** `InvoiceHeader`, `InvoiceDetail`, `Insured`, `Quote`, `Policy`, `Company`, `taaTaxInfo`, `Endorse`, `taaCompanyContract`, `taaContractSyndicate`, `taaPremiumAllocation`, `Producer`

If problems persist, click **Send diagnostics** in the top-right corner of the Integration Client tool.

:::note
Once the connection completes, you get an "Installation successful" message. The application continues running in the background and starts automatically with each reboot. To cancel, disconnect, or adjust the connection, click the application icon in the Windows tray menu.
:::

### 3. Map division and coverage codes from AIM to InsCipher

Complete the following mapping tables to configure the integration:

* Agencies
* User ID
* Fees
* Line of Business (LOB)
* Filing Types

#### Map Agencies

Map the agencies or divisions in AIM to the agencies created in Connect®. You can map multiple AIM divisions to a single Connect® agency, or use a one-to-one relationship. You must map your agencies before the integration is fully set up. To create additional agencies, see the "Creating Agency Admin User" topic in the Getting Started help section.

<img src="/images/integrations/aim/map-agencies.png" alt="Agencies mapping" style={{width: '80%'}} />

#### Map Fees — reportable Broker and Carrier fees

You decide which AIM fees import into Connect® as **Broker Fees** or **Carrier Fees**. The Fee Mapping section has three columns:

1. **AIM Transcode** — the transaction code pulled from your AIM instance. As pulled from AIM, these can include both taxes and fees.
2. **AIM TransCode Description** — the description of the fee associated with the AIM transaction code, pulled from your AIM instance.
3. **InsCipher Taxable Fee** — the InsCipher fee/tax field that the AIM Transcode and Description maps to.

The dropdown under the InsCipher Taxable Fees column offers these options:

* **Broker Fee** — fees charged or retained by the broker (policy fee, filing fee, agency fee, etc.) that must be reported to the state.
* **Carrier Fee** — carrier-mandated fees added to the policy (inspection, underwriting, audit, etc.) that must be reported to the state.
* **Do Not Import Fee as Broker or Carrier Fee** — choose this for any line item that is not a broker or carrier fee, specifically if you do not report the fee or amount to the state.

<img src="/images/integrations/aim/map-fees.png" alt="Fee mapping section" style={{width: '80%'}} />

<img src="/images/integrations/aim/map-fees-options.png" alt="InsCipher Taxable Fees dropdown options" style={{width: '40%'}} />

:::warning[What about taxes pulled into the fee mapping section?]
Although taxes are mapped automatically on import, they still appear in this section as needing to be mapped. For now, mark taxes as **Do Not Import Fee as Broker or Carrier Fee**. An enhancement to support both taxes and fees in this step is planned.
:::

#### Map Lines of Business — coverage codes

Lines of business codes vary from system to system. Where possible, InsCipher has compiled state-specific approved coverage codes and mapped generic lines of business codes to them. For additional generic code options or questions about generic mapping, contact your implementation specialist or <a href="mailto:support@inscipher.com">[support@inscipher.com](mailto\:support@inscipher.com)</a>.

:::tip
Use the **Mapped?** filter to view only the LOBs that still need to be mapped.
:::

:::warning[Important]
Select **All States** when configuring this feature. The ability to map to state-specific codes is not yet fully released.
:::

<img src="/images/integrations/aim/map-lines-of-business.png" alt="Line of Business mapping" style={{width: '80%'}} />

#### Map Filing Types

Filing/transaction types vary between AIM and InsCipher. Click the green **Add New** button to add an AIM transaction code for a filing type, then map it to an InsCipher filing type. Because this can vary for positive and negative amounts, you can set them differently to match your workflow.

<img src="/images/integrations/aim/map-filing-types.png" alt="Filing Type mapping" style={{width: '80%'}} />

### 4. Summary

Setup is now complete. If there is an issue, the system informs you and you can return to previous sections. You can also set up a manual trigger to import up to two weeks of historical data from your AIM® database.

:::note
To prevent timeout errors, batches are grouped into 100 transactions. If you import more than 100 transactions at a time, they arrive as multiple batches in the Filings Import Log.
:::

<img src="/images/integrations/aim/step-4-summary.png" alt="Integration Wizard — Summary" style={{width: '80%'}} />

:::warning[Important]
Regularly review the **Filings Import Log** to confirm all transactions import each day and to address any import errors. Import errors are described on the **Not Imported Filings** tab or by clicking a batch **Error Log**. Duplicate records are filtered out by Invoice ID.
:::

### How the import works

The integration uses a **push model**: the on-premise Integration Client reads your AIM database and sends transactions to InsCipher. The client supports two export paths.

**Standard export.** The client queries AIM directly (InvoiceHeader, Quote, Policy, Company, and related tables) for invoices matching the criteria above, attaches each invoice's raw detail lines, and pushes them to InsCipher. In this path, taxes and fees (SL tax, stamping fee, and so on) and syndicate breakdowns are calculated on the InsCipher side from those detail lines and contract data, using your Taxes and Fees mapping.

**Custom view export.** If your agency uses a [custom SQL view](#custom-sql-view-option), the client reads everything from that view, including pre-calculated taxes and fees. The custom view is also the only path that can supply several additional fields — declining carrier details (`dc_*`), service-of-process (`sop_*`), retail producer details, windstorm fields, and insured contact and limit fields. Fields marked "custom view only" in the mapping table are populated only through this path.

**Transaction type.** The InsCipher transaction type is derived from the AIM invoice type (`InvoiceTypeID`):

| AIM invoice type         | InsCipher transaction type |
| ------------------------ | -------------------------- |
| NBS (New Business)       | PN                         |
| REN (Renewal)            | PR                         |
| ADD (Additional Premium) | APE                        |
| AUD (Audit)              | AE                         |
| RMID (Reinstatement)     | APE                        |
| CXL (Cancellation)       | RPE                        |
| RET (Return Premium)     | RPE                        |
| ENX (Extension)          | PR in Texas, otherwise APE |
| Any other type           | PN                         |

**Defaulted fields.** A few fields are set to fixed values on export rather than read from AIM: `account_written_as` is set to B (Brokerage), `rpg` to 0, `commission_received` to 1, and `export_list` to 0, while `agent_notes` and `purchasing_group_name` are left empty.

### FAQs

#### What if I need to change my integration settings?

You can change your configuration after setup is complete.

#### Regenerating your InsCipher token

You may occasionally be asked to regenerate a new InsCipher Token, typically only after a major version update — InsCipher will let you know. In Connect®, go to **Setup → Integrations → Details** under the AIM integration → **Step 2** ("Integration Setup & Connect") → click **Regenerate Token**. Copy the token into the InsCipher Integration Tool: select the application icon in the Windows server tray menu → **Settings** → update the token → click **Connect**.

#### How do I edit my SQL login credentials?

Select the application icon in the Windows server tray menu → **Settings** → update your SQL login credentials → click **Connect**.

#### Deleting the integration connection in Connect®

Go to **Setup → Integrations** and click **Delete** next to the AIM® integration. If you delete it and later reconnect, you must restart the setup process from Step 1.

#### What if there are updates to the application?

Versions 1.6.0 and above support automatic updates. InsCipher communicates any changes so you are aware of updates to the integration tool.

#### How will I know if there is an issue?

There are a few ways:

**Review the Filings Import Log.** All transactions imported via the Integration Tool appear on the Filings Import Log page (left navigation). It lists how many transactions imported on a given day and which did not. If there was an error, the batch ID appears as a blue link; click it to download an error log. In most cases the error is duplicate transactions filtered out by AIM invoice ID. You can also rerun the import.

<img src="/images/integrations/aim/faq-import-log.png" alt="Filings Import Log with Error Log button" style={{width: '80%'}} />

The **Not Imported Filings** tab summarizes all not-imported filings and can be filtered by import date.

<img src="/images/integrations/aim/faq-not-imported.png" alt="Not Imported Filings tab" style={{width: '80%'}} />

**Email and dashboard notifications.** If there is a field-mapping or connection issue, the Filing Agency Admin user receives an email notification, and you are notified on the Connect® dashboard. For a connection issue, first reset your token, then open the InsCipher Integration application on your server (tray icon) → **Settings**, paste the updated token, and click **Connect**. If the issue persists, contact <a href="mailto:support@inscipher.com">[support@inscipher.com](mailto\:support@inscipher.com)</a>. For an out-of-sync field, go to the Integrations page in Connect® and click **Details** next to the integration (status will show that mapping is needed); map any highlighted fields, using the **Mapped?** filter to find them.

### AIM field mapping

The table below reflects what the import actually populates. A blank **Mapped AIM Field** means the field is not supplied by the integration. The **Requirement** is the field's status in the shared InsCipher transaction schema; the same tiers apply across all InsCipher integrations. Fields not listed here are not supplied by the AIM integration — they are entered in Connect® or required only at state filing time.

**Legend:** R = Required · Rec = Recommended · O = Optional

**Dashboard reference:** <a href="https://lookerstudio.google.com/reporting/41dce747-d045-4e1f-884d-07d23581a90a">lookerstudio.google.com</a>

| InsCipher Field                           | Mapped AIM Field                                                                 | Notes                                                                                                 | Requirement |
| ----------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------- |
| id                                        | InvoiceHeader.InvoiceKey\_PK                                                     |                                                                                                       | O           |
| policy\_number                            | InvoiceHeader.PolicyID                                                           | Non-unique field                                                                                      | R           |
| policy\_effective\_date                   | Policy.Effective                                                                 |                                                                                                       | R           |
| policy\_expiration\_date                  | Policy.Expiration                                                                |                                                                                                       | R           |
| transaction\_effective\_date              | Policy.Effective                                                                 |                                                                                                       | R           |
| expiring\_policy\_number                  | Quote.OldPolicyID                                                                |                                                                                                       | O           |
| invoice\_date                             | InvoiceHeader.InvoiceDate                                                        | State-renamed in some states                                                                          | Rec         |
| invoice\_number                           | InvoiceHeader.InvoiceID                                                          | "Invoice ID" field on the Tracking tab in Filing Details                                              | R           |
| transaction\_type                         | InvoiceHeader.InvoiceTypeID                                                      | Custom — configured in Integration Settings                                                           | R           |
| account\_written\_as                      | B                                                                                | Sent empty by the import; set during processing                                                       | O           |
| rpg                                       | 0 (No)                                                                           | Sent empty by the import                                                                              | O           |
| purchasing\_group\_name                   | Not mapped                                                                       | Sent empty by the import                                                                              | O           |
| risk\_description                         | Quote.RiskInformation (fallback: Quote.Description)                              | NY, OH, PA require manual entry post-import. Recommended populate for CA (SL1).                       | O           |
| ecp                                       | Insured.IsECP                                                                    | Defaults to "No" if unknown                                                                           | O           |
| exempt                                    | Quote.FlagTaxExempt                                                              | Imported value, not hardcoded                                                                         | O           |
| multi\_state                              | Quote.isMultiState                                                               | Imported value, not hardcoded                                                                         | O           |
| policy\_limit                             | taaTaxInfo.Limit1                                                                | Required for some states. Only pulls if Policy Limit 1 enabled + populated. See dashboard link above. | O           |
| export\_list                              | 0 (No)                                                                           | Hardcoded                                                                                             | O           |
| transaction\_line\_of\_business           | Quote.CoverageID                                                                 | Mapping defined in setup (Step 2: Field Mapping)                                                      | —           |
| transaction\_line\_of\_business\_list     | InvoiceDetail.CoverageID                                                         | Parsed from the Coverage list (CoverageID), pipe-joined                                               | R           |
| transaction\_line\_of\_business\_coverage | InvoiceDetail.Amount                                                             | Parsed from the Coverage list (Amount), pipe-joined                                                   | R           |
| non\_admitted\_insurer\_code              | Company.NAIC                                                                     | NAIC must exist in AIM; Lloyd's = AA-1122000                                                          | O           |
| non\_admitted\_insurer\_code\_list        | Not mapped                                                                       |                                                                                                       | Rec         |
| non\_admitted\_insurer\_code\_coverage    | Not mapped                                                                       |                                                                                                       | Rec         |
| syndicate\_list                           | taaPremiumAllocation + taaCompanyContact + taaaContractNumber + SyndicateCompany | Weighted avg of contract/property % (Type S)                                                          | Rec         |
| syndicate\_list\_coverage                 | Same as above                                                                    | Weighted avg calculation                                                                              | Rec         |
| premium                                   | InvoiceHeader.Premium                                                            |                                                                                                       | O           |
| agency\_fee                               | Integration mapping feature                                                      | Map agency-collected codes → "Broker Fee"                                                             | Rec         |
| inspection\_fee                           | Integration mapping feature                                                      | Map carrier-collected codes → "Carrier"                                                               | Rec         |
| sl\_tax                                   | InvoiceDetail.Amount (TransCd = SLT)                                             |                                                                                                       | O           |
| stamping\_fee                             | InvoiceDetail.Amount (TransCd = SOF)                                             | Stamping Fee / FSLO / Fire Marshal (OR)                                                               | O           |
| sl\_service\_charge                       | InvoiceDetail.Amount (TransCd = SLSC, TXA)                                       | OR, MS                                                                                                | O           |
| municipal\_fee                            | InvoiceDetail.Amount (TransCd = MUNI, MUNIT)                                     | KY                                                                                                    | O           |
| fm\_tax                                   | InvoiceDetail.Amount (TransCd = FMT)                                             | Fire Marshal Tax                                                                                      | O           |
| empa\_tax                                 | InvoiceDetail.Amount (TransCd = EMPA)                                            | Florida EMPA Tax                                                                                      | O           |
| total                                     | InvoiceHeader.InvoiceTotal                                                       | Premium + all taxes + fees                                                                            | O           |
| commission\_received                      | 1 (Yes)                                                                          | Hardcoded. Review if NH commission not collected.                                                     | O           |
| mailing\_insured\_name                    | Quote.NamedInsured                                                               | Quote.NamedInsured; fallback Insured.NamedInsured                                                     | R           |
| mailing\_address                          | Quote.MailAddress1                                                               | Quote.MailAddress1; fallback Insured.MailAddress1                                                     | R           |
| mailing\_address2                         | Quote.MailAddress2                                                               | Quote.MailAddress2; fallback Insured.MailAddress2                                                     | O           |
| mailing\_city                             | Quote.MailCity                                                                   | Quote.MailCity; fallback Insured.MailCity                                                             | R           |
| mailing\_zip\_code                        | Quote.MailZip                                                                    | Quote.MailZip; fallback Insured.MailZip                                                               | R           |
| mailing\_state\_code                      | Quote.MailState                                                                  | Quote.MailState; fallback Insured.MailState                                                           | R           |
| physical\_same\_as\_mailing               | Yes if addresses match                                                           | Sent as false by the import                                                                           | R           |
| physical\_address                         | Quote.Address1                                                                   | Quote.Address1; fallback Insured.Address1                                                             | Rec         |
| physical\_address2                        | Quote.Address2                                                                   | Quote.Address2; fallback Insured.Address2                                                             | O           |
| physical\_city                            | Quote.City                                                                       | Quote.City; fallback Insured.City                                                                     | Rec         |
| physical\_zip\_code                       | Quote.Zip                                                                        | Quote.Zip; fallback Insured.Zip                                                                       | Rec         |
| physical\_state\_code                     | Quote.State (fallback: Insured.State)                                            | Configurable in Setup → Integrations → Step 2                                                         | R           |
| retail\_producer\_name                    | tnm.Name                                                                         | Only if Account Written As = B                                                                        | O           |
| retail\_agency\_name                      | p.Name                                                                           | Only if Account Written As = B                                                                        | O           |
| retail\_address                           | p.Address1                                                                       | Only if Account Written As = B                                                                        | O           |
| retail\_address2                          | p.Address2                                                                       | Only if Account Written As = B                                                                        | O           |
| retail\_city                              | p.City                                                                           | Only if Account Written As = B                                                                        | O           |
| retail\_state                             | p.State                                                                          | Only if Account Written As = B                                                                        | O           |
| retail\_zip                               | p.Zip                                                                            | Only if Account Written As = B                                                                        | O           |
| agent\_notes                              | Null                                                                             | Hardcoded blank                                                                                       | Rec         |
| transaction\_code                         | Quote.SLA                                                                        | NJ only                                                                                               | O           |
| customer\_code                            | Quote.QuoteID                                                                    | Unique quote/submission ID                                                                            | —           |
| unique\_id                                | Quote.SLA                                                                        | Used for MO, IL, NY, etc.                                                                             | O           |
| windstorm\_exclusion                      | Not imported (custom view only)                                                  |                                                                                                       | O           |
| windstorm\_deductible                     | Not imported (custom view only)                                                  |                                                                                                       | O           |
| agent\_id                                 | DivisionID                                                                       | Mapped via Agency mapping; agencies mapped to "Do Not Import" are skipped                             | O           |
| invoice\_type\_id                         | InvoiceHeader.InvoiceTypeID                                                      |                                                                                                       | —           |
| product\_id                               | InvoiceHeader.ProductID                                                          |                                                                                                       | —           |
| entity                                    | InvoiceHeader.Entity                                                             |                                                                                                       | —           |
| payable\_id                               | InvoiceHeader.PayableID                                                          |                                                                                                       | —           |
| pay\_to\_code                             | InvoiceHeader.PayToCode                                                          |                                                                                                       | —           |
| physical\_tax\_state\_code                | Quote.TaxState                                                                   | Configurable physical/tax state                                                                       | —           |
| single\_contract                          | SingleContract (JSON)                                                            | Syndicate/contract data                                                                               | —           |
| multi\_contract                           | MultiContract (JSON)                                                             | Syndicate/contract data                                                                               | —           |
| endorsement\_effective                    | Endorsements (JSON)                                                              | Latest endorsement effective date                                                                     | —           |
| endorsement\_number                       | Endorsements (JSON)                                                              | Latest endorsement number                                                                             | —           |

### Custom SQL view option

For some clients, the standard SQL query and transaction code mapping may not be adequate and may require customization. If you need it, use the custom view feature, which lets AIM users create custom views in AIM that the InsCipher AIM integration tool can later retrieve.

Advantages:

* AIM users control what data feeds into InsCipher.
* AIM users can identify edge cases and modify the custom view SQL accordingly.
* Maintenance is simpler — no frequent re-installation or tool updates.

:::warning[Important consideration]
Only use the Custom View feature if necessary. Otherwise, use the standard SQL query and transaction code mapping built into the AIM Integration setup wizard and do **not** turn this feature on.
:::

The AIM user creates a custom view containing the filings/transactions and related information to feed to InsCipher. The view is saved on the same AIM database connected to the InsCipher Integration tool. With a custom view, the Transaction Code mapping settings in Connect® are ignored — meaning the mapping of which fees import as Carrier or Broker fees must be programmed into the view, and amounts for SL Taxes, Stamping Fees, and other state-specific fees must be specified in the view.

:::tip
InsCipher has default field names for tax titles, but these can vary slightly by state. See the tax-title mapping sheet for reference.
:::

**Step 1** — As a Connect® user, go to the AIM tool integration wizard → Step 1 (Agency Management System), check the **Use custom view** setting, and enter a custom view name.

<img src="/images/integrations/aim/custom-view-setting.png" alt="Use custom view setting in Integration Wizard Step 1" style={{width: '80%'}} />

**Step 2** — Ask your AIM database admin to create and save a custom SQL view on the same AIM database connected to the InsCipher Integration Tool. The view name must match the name referenced in Step 1.

#### Custom SQL view (starting point)

Here is the out-of-the-box custom SQL view your company can use as a starting point and modify as needed:

```sql
CREATE VIEW [dbo].[InsCipherCustomView] AS
WITH CTE AS
(SELECT
    ih.InvoiceKey_PK,
        ih.InvoiceID,
        ih.PolicyID,
        ih.QuoteID,
        ih.InvoiceTypeID,
        ih.Premium,
        ih.InvoiceTotal,
        ih.InvoiceDate,
        ih.ProductID,
        ih.DivisionID,
        ih.Entity,
        ih.PayableID,
        ih.PayToCode,
        ih.InsuredID,
        ih.CompanyID,
        ih.PostDate
    FROM InvoiceHeader ih WHERE ((ih.StatusID = 'E'
    AND ih.Taxed = 'Y'
    AND ih.InstallmentFlag = 'N')
    OR(ih.MemoInvoiceFlag = 'Y'
    AND ih.StatusID IN('R', 'P')))
    ) SELECT
    h.InvoiceKey_PK,
    h.InvoiceID,
    h.PolicyID,
    h.QuoteID,
    h.InvoiceTypeID,
    h.Premium,
    h.InvoiceTotal,
    h.InvoiceDate,
    h.ProductID,
    h.Entity AS Entity,
    h.PayableID AS PayableID,
    h.PayToCode AS PayToCode,
    h.PostDate,
    h.DivisionID AS DivisionID,
    p.Effective,
    p.Expiration,
    q.OldPolicyID,
    q.CoverageID,
    i.IsECP,
    q.RiskInformation AS RiskInformation,
    q.NamedInsured AS NamedInsured,
    q.MailAddress1 AS MailAddress1,
    q.MailAddress2 AS MailAddress2,
    q.MailCity AS MailCity,
    q.MailState AS MailState,
    q.MailZip AS MailZip,
    q.Address1 AS Address1,
    q.Address2 AS Address2,
    q.City AS City,
    q.Zip AS Zip,
    q.State AS State,
    q.SLA AS SLA,
    q.TaxState AS TaxState,
    q.FlagTaxExempt AS FlagTaxExempt,
    q.isMultiState AS isMultiState,
    ic.NAIC AS NAIC,
    ti.Limit1 AS Limit1,
    i.NamedInsured AS InsuredNamedInsured,
    i.MailAddress1 AS InsuredMailAddress1,
    i.MailAddress2 AS InsuredMailAddress2,
    i.MailCity AS InsuredMailCity,
    i.MailState AS InsuredMailState,
    i.MailZip AS InsuredMailZip,
    i.Address1 AS InsuredAddress1,
    i.Address2 AS InsuredAddress2,
    i.City AS InsuredCity,
    i.Zip AS InsuredZip,
    i.State AS InsuredState,
    q.Description AS RiskInformationFromDescription,
    d.AgencyFee,
    d.InspectionFee,
    d.StampingFee,
    d.SlTax,
    d.EmpaTax,
    d.FmTax,
    d.MunicipalFee,
    d.SlServiceCharge,
    NULL AS InsuredEntity,
    NULL AS InsuredPhone,
    NULL AS InsuredEmail,
    NULL AS InsuredCounty,
    NULL AS PropertyLimit,
    NULL AS LayeredRisk,
    NULL AS BrokerOfRecord,
    NULL AS RiskRetentionGroup,
    NULL AS ServiceOfProcessName,
    NULL AS ServiceOfProcessAddress,
    NULL AS ServiceOfProcessAddress2,
    NULL AS ServiceOfProcessCity,
    NULL AS ServiceOfProcessState,
    NULL AS ServiceOfProcessZip,
    NULL AS WindStormExclusion,
    0 AS WindStormDeductible,
    NULL AS DecliningCarriers,
    STUFF((SELECT ' | ' + details.CoverageID + ' ^ ' + CONVERT(varchar(255),details.Amount, 0)
              FROM InvoiceDetail AS details WHERE details.InvoiceKey_FK = h.InvoiceKey_PK AND details.LineTypeID = 'P'  FOR XML PATH(''),TYPE).value('.','varchar(MAX)'),1,3,'') AS Coverage,
    pr.Name AS RetailProducerName,
    pr.Name AS RetailAgencyName,
    pr.Address1 AS RetailAddress,
    pr.Address2 AS RetailAddress2,
    pr.City AS RetailCity,
    pr.Zip AS RetailZip,
    pr.State AS RetailState,
    pr.License AS RetailProducerLicense,
    pr.License AS RetailAgencyLicense,
    pr.Phone AS RetailPhoneNumber,
    pr.EMail AS RetailEmailAddress
    FROM CTE AS h (NOLOCK)
    JOIN Insured AS i (NOLOCK) ON h.InsuredID = i.InsuredID
    JOIN Quote AS q (NOLOCK) ON h.QuoteID = q.QuoteID
    JOIN POLICY AS p (NOLOCK) ON h.QuoteID = p.QuoteID
    LEFT OUTER JOIN Company AS ic (NOLOCK) ON h.CompanyID = ic.CompanyID
    LEFT OUTER JOIN taaTaxInfo AS ti (NOLOCK) ON h.QuoteID = ti.QuoteID
    LEFT OUTER JOIN Producer AS pr (NOLOCK) ON q.ProducerID = pr.ProducerID
        AND q.TaxState = 'WA'
        AND GETDATE() BETWEEN q.Effective AND q.Expiration
    LEFT JOIN (
        SELECT
            id.InvoiceKey_FK,
            SUM(CASE WHEN id.TransCd IN('ADF','AGCYF','ABF','CFF','JBL','MGF','MVR','OMNI','PLF','FEE','RMF','SVF','SLF','TPF','PRODF') THEN id.Amount ELSE 0 END) AS AgencyFee,
            SUM(CASE WHEN id.TransCd IN('LLF','EC','INF','MAF','AUF','ATF','MBF','IN2','MMVR','CPF','MRM','WCA','WCS','UNF') THEN id.Amount ELSE 0 END) AS InspectionFee,
            SUM(CASE WHEN id.TransCd IN('SOF')
                OR(hh.State='AK' AND id.TransCd='AKFF')
                OR(hh.State='KY' AND id.TransCd='KFE')
                OR(hh.State='MI' AND id.TransCd='REGF')
                OR(hh.State='OR' AND id.TransCd='FM')
                OR(hh.State='PR' AND id.TransCd='NIMAF')
                OR(hh.State='SD' AND id.TransCd='NIMAF')
                OR(hh.State='TN' AND id.TransCd='TNTRN')
                OR(hh.State='UT' AND id.TransCd='NIMAF')
                OR(hh.State='VI' AND id.TransCd='VIFF')
                OR(hh.State='VA' AND id.TransCd='VAF')
                OR(hh.State='WY' AND id.TransCd='NIMAF') THEN id.Amount ELSE 0 END) AS StampingFee,
            SUM(CASE WHEN id.TransCd IN('SLT')
                OR(hh.State='MT' AND id.TransCd='FP')
                OR(hh.State='NJ' AND id.TransCd='FFA') THEN id.Amount ELSE 0 END) AS SlTax,
            SUM(CASE WHEN id.TransCd IN('EMPA')
                OR(hh.State='FL' AND id.TransCd='FEM') THEN id.Amount ELSE 0 END) AS EmpaTax,
            SUM(CASE WHEN id.TransCd IN('FMT')
                OR(hh.State='AK' AND id.TransCd='WMT')
                OR(hh.State='IL' AND id.TransCd='ILS')
                OR(hh.State='MT' AND id.TransCd='FM')
                OR(hh.State='SC' AND id.TransCd='SCMMA')
                OR(hh.State='SD' AND id.TransCd='SDFIR') THEN id.Amount ELSE 0 END) AS FmTax,
            SUM(CASE WHEN id.TransCd IN('MUNI','MUNIT') THEN id.Amount ELSE 0 END) AS MunicipalFee,
            SUM(CASE WHEN id.TransCd IN('SLSC','TXA')
                OR(hh.State='MS' AND id.TransCd='MWUA') THEN id.Amount ELSE 0 END) AS SlServiceCharge
        FROM InvoiceDetail AS id
        LEFT JOIN InvoiceHeader AS hh ON id.InvoiceKey_FK = hh.InvoiceKey_PK
        GROUP BY id.InvoiceKey_FK
    ) AS d ON h.InvoiceKey_PK = d.InvoiceKey_FK
```

### Importing documents

:::tip
Many AIM clients choose, for now, to add documents to InsCipher only for the "State Export states" that require them — the states where InsCipher can batch file (programmatically or via an import file). With this workflow, most filing documents can be marked **Optional** in Connect®, so they don't need to be stored in InsCipher. You then only import documents for the states that require them for batch filing: **California, Mississippi, New Jersey, New York, Oregon, Pennsylvania, Washington**. For all other states, you can store policy documentation in ImageRight.
:::


## AIM™

Automates data-intensive surplus lines tasks between Vertafore AIM and InsCipher, including policy data import and payment batch reconciliation.

This integration uses the on-premise AIM Integration Client to read surplus lines data from your local AIM database and push it into InsCipher.

### Ownership & responsibilities

This integration is **built and maintained by InsCipher**. Your agency installs the InsCipher Integration Client on-premise and completes setup inside InsCipher Connect®, with support from the InsCipher team. The table below shows who handles what.

| Area                                                              | InsCipher | Your agency |
| ----------------------------------------------------------------- | --------- | ----------- |
| Integration Client (IC) and import logic                          | ✓         |             |
| On-premise MS SQL Server (AIM database) and Windows host          |           | ✓           |
| Read access to the AIM tables the IC queries                      |           | ✓           |
| Network access to InsCipher's Integration Management Server (IMS) |           | ✓           |
| Field mapping in the Integration Wizard                           | ✓         |             |
| Surplus-lines tax rates and compliance updates                    | ✓         |             |
| Integration support and maintenance                               | ✓         |             |

:::tip[What this integration does]
* Retrieves surplus lines policy data from AIM into InsCipher.
* Reconciles received and processed batch payments in AIM against InsCipher data.
:::

:::note[What this integration does not do]
* It does not automatically pull documents associated with policy data (see the document workflow in <a href="/integrations/vertafore/aim/import-policy-data">Import Policy Data</a>).
* There is no Tax Calculation functionality yet. It is being researched for future phases.
:::

### Technical installation details

The Integration Client (IC) must be installed on-premise so it can reach the MS SQL machine over your private network. Ideally the IC runs on the machine hosting the MS SQL server itself, but it can connect to a copy of the live database as long as the field names match and access is granted through your firewall.

Once installed, you configure the hostname and port of the MS SQL machine. The firewall and server software must allow connecting over the network. You also configure the IC to use a MS SQL user account to query insurance policy transactions — that account **must have at least read-only access** to the relevant tables in the AIM database (or a copy of it).

To integrate with InsCipher, the IC keeps a persistent connection to InsCipher's Integration Management Servers (IMS) using socket technology. The IC must be able to reach IMS over the internet and maintain the connection using the built-in socket client. This lets InsCipher control when import jobs run.

Using the MS SQL credentials configured in the IC, the client regularly queries the AIM database for new and updated insurance policy transactions and sends the results to InsCipher's API endpoints. Only the fields listed in the <a href="/integrations/vertafore/aim/import-policy-data">field mapping</a> — those required for surplus lines filing and for Connect® to function — are imported. Some AIM data is not imported due to field-mapping limitations.

For technical questions, contact <a href="mailto:support@inscipher.com">[support@inscipher.com](mailto\:support@inscipher.com)</a>.


## Troubleshooting

Helpful detail for understanding common AIM integration errors.

### Integration Connection is Lost

If the connection is lost, these initial steps can help resolve the issue quickly:

1. **Review your organization's network settings.** Confirm that the URL where the AIM integration service runs, <a href="https://ims.surpluslines.inscipher.com">[https://ims.surpluslines.inscipher.com](https://ims.surpluslines.inscipher.com)</a>, is not blocked by your organization's network or firewall.

2. **Manually restart the integration service and regenerate the token.** From the Windows Command Prompt (WIN + CMD), in the directory where the integration client is active, run:

   ```shell
   net stop "InsCipher AIM Integration"
   net start "InsCipher AIM Integration"
   ```

   The service should confirm that it stopped and started again successfully. Once complete, go to Integration Wizard Step 2 and regenerate a new token.

For any other errors, contact <a href="mailto:support@inscipher.com">InsCipher support</a>.


## Insurity Submission Gateway (ISG)

Automate surplus lines transaction import and real-time tax calculations between Insurity Submission Gateway and InsCipher.

Insurity Submission Gateway (ISG), formerly Sure Submission Gateway (SSG), is a platform for wholesale distribution and the London Market. This **partner-owned (Insurity) integration** connects ISG to InsCipher's portal and Tax Calculator APIs to automate two surplus lines compliance workflows.

### Supported functionality

**Transaction Import** — Transaction data is transferred from ISG to InsCipher for surplus lines tax filing and reporting, along with documents for policies (PN) and endorsements (AE, APE, RPE, ZPE, XE). Transactions processed in ISG — new business, renewals, endorsements, cancellations, and reinstatements — are sent to InsCipher, ready for review and submission to the appropriate state surplus lines offices.

**Tax & Fee Calculation** — ISG requests real-time surplus lines taxes and fees from InsCipher during quoting, for all U.S. states and territories, without manual lookups.

:::note[What this integration does not do]
* It does not generate diligent effort forms or related diligent-search documents (affidavits, and so on).
* It does not reconcile or remit tax payments.
:::

### How it works

**Transaction Import** uses the InsCipher Filing Connect API to create transactions in InsCipher from ISG data. When a qualifying transaction is completed in ISG, the integration sends the relevant filing details — policy number, state, transaction type, effective date, premium, and applicable fees — to InsCipher, where the data is available for review, approval, and submission to the state filing authority.

* Core call: `POST /api/v2/single/transaction`
* The response confirms receipt and returns an InsCipher transaction ID for tracking.

**Tax Calculation** uses the InsCipher Tax API to return real-time surplus lines tax calculations. When a quote is processed in ISG, the integration sends the state, premium, applicable fees, line of business, and transaction type to InsCipher, which returns a detailed breakdown of taxes and fees displayed directly in ISG.

* Core call: `POST /api/taxcalculator`

### Responsibilities

| Area                                                                  | Owned by Insurity | Owned by InsCipher |
| --------------------------------------------------------------------- | ----------------- | ------------------ |
| Integration built inside ISG                                          | ✓                 |                    |
| Configuration within ISG                                              | ✓                 |                    |
| InsCipher Filing Connect API and Tax API                              |                   | ✓                  |
| API key provisioning and access                                       |                   | ✓                  |
| Surplus-lines and stamping-fee tax rates                              |                   | ✓                  |
| Transaction review, approval, and state submission (InsCipher portal) |                   | ✓                  |

### Requirements

* An active InsCipher Filing Connect account with API access enabled.
* A licensed Insurity Submission Gateway product.
* The API key and endpoint provided by InsCipher.

### Support

* **Implementation guidance:** Daniel Seddon (Sikich) — <a href="mailto:daniel.seddon@sikich.com">[daniel.seddon@sikich.com](mailto\:daniel.seddon@sikich.com)</a>
* **API credentials and access:** Contact your InsCipher account manager or support.


## Import Policy Data

Once the Integration Connector Tool has been added to your agency, run the setup wizard to connect your Concept One database to InsCipher and start importing policy data. Setup is a four-part process in the InsCipher Integration Wizard.

To open the wizard, log into your Connect® account, then go to the **Settings** cog (top-right) → **Integrations** → **ADD NEW**. Select **Concept One** from the dropdown to add the integration.

### 1. Agency Management System

Step 1 confirms the initial setup. Review it and click **Continue** to move to Step 2.

<img src="/images/integrations/concept-one/step-1-agency-management-system.png" alt="Integration Wizard Step 1 — Agency Management System" style={{width: '80%'}} />

### 2. Integration Setup & Connection

In this step you download and start the Windows-based Integration Connector Tool, then connect it to InsCipher.

1. Download the **InsCipher Connector Tool** from the link in this step and install the `.exe`. Once installed, open the browser-based interface at `http://localhost:3080`.
2. Generate an integration token using the button under **Integration Token**.

<img src="/images/integrations/concept-one/step-2-integration-token.png" alt="Generate the integration token" style={{width: '80%'}} />

3. In the Connector Tool, go to **Settings**. Under **Connection Credentials**, paste the token into the **Integration Token** field and click **Save**.

4. Under **Integration Settings**, enter your MS SQL connection details and click **Save**:
   * **User** — SQL Server login username
   * **Password** — SQL Server login password
   * **Database** — Concept One database name (e.g. `dba.conceptone`)
   * **Port** — SQL Server port (default `1433`)
   * **Host** — hostname or IP of the SQL Server (e.g. `localhost`)

<img src="/images/integrations/concept-one/step-2-connector-settings.png" alt="Integration Connector Tool — Settings page" style={{width: '80%'}} />

Once both sections are saved, continue to Step 3 to begin field mapping.

### 3. Field Mapping

After the connection completes and the Integration Tool syncs with Connect®, map the data pulled from Concept One to standard InsCipher values so the two systems stay in parity. You must complete all of these tables before continuing to Step 4:

* Agencies
* Taxes and Fees
* Lines of Business
* Filing Types
* Insurance Companies

#### Map Agencies

The integration pulls both the Agency Code and Name for each Concept One agency. For each one, choose the matching InsCipher Agency to map it to.

<img src="/images/integrations/concept-one/map-agencies.png" alt="Agency mapping table" style={{width: '80%'}} />

#### Map Taxes and Fees

For each Concept One Code and Description line item, choose a value in the dropdown under InsCipher Taxable Fees and State Taxes. The options are:

* Do Not Import
* Broker Fee
* Carrier Fee
* Stamping Fee
* Sl Tax
* EMPA Tax
* FM Tax
* Municipal Fee
* Sl Service Charge

<img src="/images/integrations/concept-one/map-taxes-and-fees.png" alt="Taxes and Fees mapping table" style={{width: '80%'}} />

#### Map Lines of Business

Map the derived Concept One codes for each Line of Business (LOB) to an InsCipher Generic Line of Business code. Use the <a href="https://lookerstudio.google.com/reporting/41dce747-d045-4e1f-884d-07d23581a90a">State Specific to Generic LOB mapping worksheet</a> or the simpler <a href="https://lookerstudio.google.com/reporting/41dce747-d045-4e1f-884d-07d23581a90a/page/p_4q66kh8crc">Generic Lines of Business worksheet</a>. If needed, map specific LOB codes per AMS code under the **InsCipher State Specific Codes** column, where you can select a state and LOB description.

<img src="/images/integrations/concept-one/map-lines-of-business.png" alt="Line of Business mapping table" style={{width: '80%'}} />

#### Map Filing Types

Filing/transaction type naming differs between Concept One and InsCipher. The **Filing Types Mapping table** lets you map each type, with the option to use a different type for positive and negative amounts to match your workflow.

In Concept One, the transaction type is referred to as **Invoice Billing Class**. These values appear under the **Transaction Type** column with their **Comments** (description). Map each to an InsCipher transaction type using the InsCipher Positive Premium Filing Code and/or Negative Premium Filing Code dropdowns. The InsCipher transaction types are:

* PN (New Policy)
* PR (Renewal Policy)
* APE (Additional Premium Endorsement)
* RPE (Return Premium Endorsement)
* AE (Audit Endorsement)
* FC (Flat Cancellation)
* ZPE (Zero Premium Endorsement)
* PC (Pro Rata Cancellation)
* XE (Extension Endorsement)
* RI (Reinstatement)
* BO (Back-out / Reversal)
* BD (Binder)

<img src="/images/integrations/concept-one/map-filing-types.png" alt="Filing Types mapping table" style={{width: '80%'}} />

#### Map Insurance Companies

Map each insurance company pulled from Concept One to the corresponding Insurance Company on record in InsCipher.

### 4. Summary

Step 4 reviews the completed steps and any outstanding issues. When the Summary items are all checked complete, the integration has no outstanding issues.

<img src="/images/integrations/concept-one/step-4-summary.png" alt="Integration Wizard Step 4 — Summary" style={{width: '30%'}} />

:::note
A connection made during the day may not populate policy data until the next day, because of the integration's cadence. If data hasn't appeared in the Filings Import Log by the next day, contact InsCipher support.
:::

You can also pull up to two weeks of historical data using **Trigger a Manual Import**. The date picker is limited to two weeks prior to the current date.

<img src="/images/integrations/concept-one/trigger-manual-import.png" alt="Trigger a Manual Import" style={{width: '80%'}} />

After submitting a manual import, it can take up to 30 minutes for the data to appear in the Filings Import Log. Any errors or status issues with the integration also appear on this page.

### How the import works

The daily import runs for the previous day. You can also run a manual import for a date range (up to two weeks back).

The integration imports **posted surplus lines invoices** whose post date falls in the range — invoices in Posted status that cover non-admitted (surplus lines) risk. One InsCipher transaction is created per policy. It also handles **voided invoices** (those voided in the range, in Voided status): if a policy was voided in Concept One and a matching transaction had previously been imported into InsCipher, the integration voids that transaction. Voided policies with no previously imported transaction are skipped.

Premium, lines of business, and fees come from the policy's invoice items:

* Premium lines (transaction class **P**) provide the lines of business — each line code is mapped to an InsCipher LOB — and the premium amounts. The transaction premium is the sum of these.
* Tax and fee lines (transaction class **T** or **F**) provide taxes and fees, summed according to your Taxes and Fees mapping (keyed on the Concept One transaction code).

A few behaviors to be aware of:

* Agencies mapped to **Do Not Import** are skipped.
* A transaction's physical address is sent only when the physical state differs from the mailing state.

#### Transaction types

Concept One reports transactions using a fixed set of codes, which you map on the Filing Types step:

| Code | Description   |
| ---- | ------------- |
| A    | Audit         |
| C    | Cancel        |
| E    | Endorsement   |
| O    | New Business  |
| R    | Reinstatement |
| S    | Reissue       |
| N    | Renew         |
| W    | Rewrite       |

### Concept One field mapping

The table below reflects what the import actually populates. A blank **Concept One source** means the field is not supplied by the integration. The **Requirement** is the field's status in the shared InsCipher transaction schema; the same tiers apply across all InsCipher integrations. Fields not listed here are not supplied by the Concept One integration — they are entered in Connect® or required only at state filing time.

**Legend:** R = Required · Rec = Recommended · O = Optional

| InsCipher Field                           | Concept One source                                            | Notes                                                                                                              | Requirement |
| ----------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------- |
| id                                        | Invoice.Invoice\_ID                                           |                                                                                                                    | O           |
| policy\_number                            | Contract.Contract\_Num                                        |                                                                                                                    | R           |
| policy\_effective\_date                   | Contract.Eff\_Date                                            |                                                                                                                    | R           |
| policy\_expiration\_date                  | Contract.Exp\_Date                                            |                                                                                                                    | Rec         |
| transaction\_effective\_date              | Contract.Revision\_Eff\_Date                                  |                                                                                                                    | R           |
| expiring\_policy\_number                  | c3.Contract\_Num                                              |                                                                                                                    | Rec         |
| invoice\_date                             | Invoice.Post\_Date                                            |                                                                                                                    | Rec         |
| invoice\_number                           | Invoice.Invoice\_Num                                          |                                                                                                                    | Rec         |
| transaction\_type                         | Invoice.Billing\_Class (raw)                                  | Mapping required; resolved by the sign of premium. Concept One uses a fixed code set (see Transaction types above) | R           |
| account\_written\_as                      | Contract.Supplier\_Bill\_Ind (raw)                            | 'Y' maps to DC (Direct to Client); any other value maps to B (Brokerage)                                           | R           |
| rpg                                       |                                                               |                                                                                                                    | R           |
| dba                                       |                                                               |                                                                                                                    | O           |
| multi\_state                              | 0                                                             | Hardcoded false                                                                                                    | O           |
| risk\_description                         | Contract.Operations\_Desc                                     |                                                                                                                    | O           |
| purchasing\_group\_name                   |                                                               | Not supplied by the integration                                                                                    | Rec         |
| transaction\_line\_of\_business\_list     | invoice\_items\[].Line\_Code                                  | Mapped to LOB; pipe-joined per premium line                                                                        | R           |
| transaction\_line\_of\_business\_coverage | invoice\_items\[].Amount                                      | Pipe-joined per premium line                                                                                       | R           |
| non\_admitted\_insurer\_code\_list        | non\_admitted\_insurer\_list\[].naic                          | Pipe-joined                                                                                                        | Rec         |
| non\_admitted\_insurer\_code\_coverage    | non\_admitted\_insurer\_list\[].percentage                    | Pipe-joined                                                                                                        | Rec         |
| syndicate\_list                           |                                                               | Not supplied by the integration                                                                                    | Rec         |
| syndicate\_list\_coverage                 |                                                               | Not supplied by the integration                                                                                    | Rec         |
| premium                                   | Invoice.Total\_Prem                                           |                                                                                                                    | O           |
| agency\_fee                               | invoice\_items (raw)                                          | Broker Fee; summed by Taxes and Fees code mapping                                                                  | R           |
| inspection\_fee                           | invoice\_items (raw)                                          | Carrier Fee; summed by Taxes and Fees code mapping                                                                 | R           |
| sl\_tax                                   | invoice\_items (raw)                                          | Summed by Taxes and Fees code mapping                                                                              | O           |
| stamping\_fee                             | invoice\_items (raw)                                          | Summed by Taxes and Fees code mapping                                                                              | O           |
| sl\_service\_charge                       | invoice\_items (raw)                                          | Summed by Taxes and Fees code mapping                                                                              | O           |
| municipal\_fee                            | invoice\_items (raw)                                          | Summed by Taxes and Fees code mapping                                                                              | O           |
| fm\_tax                                   | invoice\_items (raw)                                          | Summed by Taxes and Fees code mapping                                                                              | O           |
| empa\_tax                                 | invoice\_items (raw)                                          | Summed by Taxes and Fees code mapping                                                                              | O           |
| total                                     | Invoice.Total\_Prem + Invoice.Total\_Fee + Invoice.Total\_Tax |                                                                                                                    | O           |
| mailing\_insured\_name                    | Entity.Entity\_Name                                           |                                                                                                                    | R           |
| mailing\_address                          | Address.Address\_Line\_1                                      |                                                                                                                    | R           |
| mailing\_address2                         | Address.Address\_Line\_2                                      |                                                                                                                    | O           |
| mailing\_city                             | Address.City                                                  |                                                                                                                    | R           |
| mailing\_zip\_code                        | Address.Zip                                                   |                                                                                                                    | R           |
| mailing\_state\_code                      | Address.State                                                 |                                                                                                                    | R           |
| insured\_email                            | contacts.email (Entity\_Det.Email\_Address)                   |                                                                                                                    | O           |
| insured\_phone                            | contacts.phone                                                |                                                                                                                    | O           |
| policy\_limit                             | limits.limit                                                  |                                                                                                                    | O           |
| physical\_same\_as\_mailing               | computed                                                      | True when the physical state equals the mailing state                                                              | R           |
| physical\_address                         | locations\[].Address\_Line\_1                                 | From the first location; only when physical differs from mailing                                                   | Rec         |
| physical\_address2                        | locations\[].Address\_Line\_2                                 | From the first location; only when physical differs from mailing                                                   | O           |
| physical\_city                            | locations\[].City                                             | From the first location; only when physical differs from mailing                                                   | Rec         |
| physical\_zip\_code                       | locations\[].Zip                                              | From the first location; only when physical differs from mailing                                                   | Rec         |
| physical\_state\_code                     | Contract.Controling\_State                                    |                                                                                                                    | R           |
| agent\_id                                 | Contract.Book\_Loc\_ID (agency)                               | Mapped via Agency mapping; agencies mapped to "Do Not Import" are skipped                                          | O           |
| agent\_notes                              |                                                               | Generated: "C1 Invoice #\<invoice number>"                                                                         | Rec         |


## Concept One™

Streamlines tax filing, reporting, and reconciliation by automatically importing policy data into InsCipher.

Insurity customers who use Concept One to manage policies, accounting, claims, and workflow automation can use this integration to automate the flow of policy data from Concept One into InsCipher.

### Ownership & responsibilities

This integration is **built and maintained by InsCipher**. Your agency installs the InsCipher Integration Connector Tool on-premise and completes setup inside InsCipher Connect®, with support from the InsCipher team. The table below shows who handles what.

| Area                                                    | InsCipher | Your agency |
| ------------------------------------------------------- | --------- | ----------- |
| Integration Connector Tool (ICT) and daily import logic | ✓         |             |
| On-premise MS SQL Server and Windows host               |           | ✓           |
| Read access to the SQL tables the ICT queries           |           | ✓           |
| Field mapping in the Integration Wizard                 | ✓         |             |
| Surplus-lines tax rates and compliance updates          | ✓         |             |
| Integration support and maintenance                     | ✓         |             |

:::tip[What this integration does]
Uses a web-based Integration Connector Tool to read your on-premise MS SQL database and automatically pull policy data into InsCipher.
:::

:::note[What this integration does not do]
* It cannot pull documents associated with policy data.
* There is no Tax Calculation or Payment Reconciliation functionality yet. Both are being researched for future phases.
:::

### Before you start

This service is not available to all clients. At a minimum, you must run an on-premise service such as MS SQL on Windows. If you are a Concept One customer but don't use an on-premise connection, contact your Insurity representative or account manager to find out whether it can be set up for your agency.

### How it works

The Integration Connector Tool (ICT) is an installable Windows service. Once installed, it runs in the background and has no graphical interface of its own — you configure it initially through a simple browser interface, similar to setting up a home router.

The ICT runs on a machine in your network, reads specific fields from your SQL database, and triggers daily batch imports into InsCipher.

Continue to <a href="/integrations/insurity/concept-one/import-policy-data">Import Policy Data</a> to install the tool and run the setup wizard.


## Troubleshooting

Tips for resolving issues with the Concept One integration. InsCipher notifies you by email and in the notification center when any of the cases below occur.

### Warnings

Prompts that encourage you to act on something that could lead to an adverse outcome if left too long.

| Title                  | Description                                                    | Suggested action                                        |
| ---------------------- | -------------------------------------------------------------- | ------------------------------------------------------- |
| Integration Incomplete | The system detects an incomplete integration before Step 3.    | Complete the integration steps through Step 3.          |
| Fields Need Mapping    | Required field mapping on Step 3 was started but not finished. | Complete the mapping exercise for all tables on Step 3. |

### Errors

System messages indicating technical problems that lead to partial or lost functionality.

| Title                          | Description                                         | Suggested action                                                                                                                                                                                                                                                      |
| ------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Integration Connection is Lost | The integration tool cannot connect to Concept One. | **Manually import data missed during the outage:** On Step 4 / Summary, click **Trigger a Manual Import** and select the date your connection was lost and your agency stopped receiving data. This pulls in the information that failed to import during the outage. |

For any other errors, contact <a href="mailto:support@inscipher.com">InsCipher support</a>.


## Import Policy Data

Once the integration setup tool has been added to your agency, run the setup wizard to connect your Applied Epic instance to InsCipher and start importing policy data. Setup is a four-part process in the InsCipher Integration Wizard.

To open the wizard, log into your Connect® account, then go to the **Settings** cog (top-right) → **Integrations** → **ADD NEW**. Select **Applied Epic Data Lake** from the dropdown to add the integration.

### 1. Agency Management System

Enter the credentials below to connect InsCipher to your BigQuery Data Lake:

* **Database Name**
* **Project ID**
* **JSON Key**

**Where to find these credentials**

* **Database Name** — the same as your BigQuery database name. In the Google Cloud console, open BigQuery, open the Explorer panel, and select your project.
* **JSON Key** — a `.json` file exported from the Google Cloud console. Go to your project → **IAM & Admin** → **Service accounts** → **Add Key**, choose **JSON** as the key type, and click **Create**. Upload this file to the **JSON Key** field in Step 1 of the wizard. For details, see Google's guide on <a href="https://cloud.google.com/iam/docs/keys-create-delete">creating service account keys</a>.
* **Project ID** — extracted automatically into the **Project ID** field once the JSON file is added.

<img src="/images/integrations/applied-epic/step-1-agency-management-system.png" alt="Integration Wizard Step 1 — Database Name, Project ID, and JSON Key fields" style={{width: '80%'}} />

### 2. Integration Setup & Connection

InsCipher establishes the connection to your Applied instance and pulls the fields needed for the mapping in Step 3. Unless the wizard reports an API connection error or a problem retrieving mapping data, no manual input is needed here — continue to Step 3.

<img src="/images/integrations/applied-epic/step-2-connection.png" alt="Integration Wizard Step 2 — connection established" style={{width: '80%'}} />

### 3. Field Mapping

After the connection completes and the Integration Tool syncs with Connect®, map the data pulled from Applied to standard InsCipher values so the two systems stay in parity. You must complete all of these tables before continuing to Step 4:

* Agencies
* Taxes and Fees
* Lines of Business
* Filing Types
* Insurance Companies

#### Map Agencies

The integration pulls both the Agency Code and Name for each Applied Epic agency. For each one, choose the matching InsCipher Agency to map it to, or choose **Do Not Import** to exclude that agency's transactions from import.

<img src="/images/integrations/applied-epic/map-agencies.png" alt="Agency mapping table" style={{width: '80%'}} />

#### Map Taxes and Fees

For each Applied Code and Description line item, choose a value in the dropdown under InsCipher Taxable Fees and State Taxes. The options are:

* Do Not Import
* Broker Fee
* Carrier Fee
* Stamping Fee
* Sl Tax
* EMPA Tax
* FM Tax
* Municipal Fee
* Sl Service Charge

<img src="/images/integrations/applied-epic/map-taxes-and-fees.png" alt="Taxes and Fees mapping table" style={{width: '80%'}} />

#### Map Lines of Business

Map the derived AMS codes for each Line of Business (LOB) to an InsCipher Generic Line of Business code. Use the <a href="https://lookerstudio.google.com/reporting/41dce747-d045-4e1f-884d-07d23581a90a">State Specific to Generic LOB mapping worksheet</a> or the simpler <a href="https://lookerstudio.google.com/reporting/41dce747-d045-4e1f-884d-07d23581a90a/page/p_4q66kh8crc">Generic Lines of Business worksheet</a>. If needed, map specific LOB codes per AMS code under the **InsCipher State Specific Codes** column, where you can select a state and LOB description.

<img src="/images/integrations/applied-epic/map-lines-of-business.png" alt="Line of Business mapping table" style={{width: '80%'}} />

#### Map Filing Types

Filing/transaction type naming differs between Applied Epic and InsCipher. The **Filing Types Mapping table** lets you map each type, with the option to use a different type for positive and negative amounts to match your workflow.

Applied Policy Transaction Codes appear under the **Transaction Type** column with their **Comments** (description). Map each to an InsCipher transaction type using the InsCipher Positive Premium Filing Code and/or Negative Premium Filing Code dropdowns. The InsCipher transaction types are:

* PN (New Policy)
* PR (Renewal Policy)
* APE (Additional Premium Endorsement)
* RPE (Return Premium Endorsement)
* AE (Audit Endorsement)
* FC (Flat Cancellation)
* ZPE (Zero Premium Endorsement)
* PC (Pro Rata Cancellation)
* XE (Extension Endorsement)
* RI (Reinstatement)
* BO (Back-out / Reversal)
* BD (Binder)

<img src="/images/integrations/applied-epic/map-filing-types.png" alt="Filing Types mapping table" style={{width: '80%'}} />

#### Map Insurance Companies

Map each insurance company pulled from Applied to the corresponding Insurance Company on record in InsCipher.

### 4. Summary

Step 4 reviews the completed steps and any outstanding issues. When the Summary items are all checked complete, the integration has no outstanding issues.

<img src="/images/integrations/applied-epic/step-4-summary.png" alt="Integration Wizard Step 4 — Summary" style={{width: '80%'}} />

:::note
A connection made during the day may not populate policy data until the next day, because of the integration's cadence. If data hasn't appeared in the Filings Import Log by the next day, contact InsCipher support.
:::

You can also pull up to two weeks of historical data using **Trigger a Manual Import**, which lets you import from a specific date.

<img src="/images/integrations/applied-epic/trigger-manual-import.png" alt="Trigger a Manual Import" style={{width: '80%'}} />

After submitting a manual import, it can take up to 30 minutes for the data to appear in the Filings Import Log. Any errors or status issues with the integration also appear on this page.

### How the import works

The integration imports **posted invoices** whose delivery date falls in the selected range. For each invoice it loads the invoice lines, the policy, and the policy lines, then creates one InsCipher transaction per policy on the invoice.

Only **surplus-lines transactions** are imported. A transaction is treated as surplus lines when one of its invoice lines is recognized as a surplus-lines tax (its description matches surplus-lines tax, SLT, or government payable) or when a line's code is mapped to SL Tax. Other transactions are skipped.

A few behaviors to be aware of:

* Taxes and fees are summed from the invoice line amounts according to your **Taxes and Fees** mapping.
* Agencies mapped to **Do Not Import** are skipped.
* A transaction fails to import if its policy lines carry more than one distinct transaction type.

### InsCipher field mapping

The table below reflects what the import actually populates. A blank **Applied source** means the field is not supplied by the integration. The **Requirement** is the field's status in the shared InsCipher transaction schema; the same tiers apply across all InsCipher integrations. Fields not listed here are not supplied by the Applied Epic integration — they are entered in Connect® or required only at state filing time.

**Legend:** R = Required · Rec = Recommended · O = Optional

| InsCipher Field                           | Applied source                                   | Notes                                                                                  | Requirement |
| ----------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------- |
| id                                        | Invoice.InvoiceID                                |                                                                                        | O           |
| policy\_number                            | Policy.PolicyNumber                              |                                                                                        | R           |
| policy\_effective\_date                   | Policy.EffectiveDate                             |                                                                                        | R           |
| policy\_expiration\_date                  | Policy.ExpirationDate                            |                                                                                        | Rec         |
| transaction\_effective\_date              | Policy.EffectiveDate or Invoice.DeliveryDateTime | Policy.EffectiveDate for new/renewal transactions, otherwise the invoice delivery date | R           |
| expiring\_policy\_number                  |                                                  | Not supplied by the integration                                                        | Rec         |
| invoice\_date                             | Invoice.DeliveryDateTime                         |                                                                                        | Rec         |
| invoice\_number                           | Invoice.InvoiceNumber                            |                                                                                        | Rec         |
| transaction\_type                         | CdLineStatus.CdLineStatusCode                    | Mapping required; resolved by the sign of premium (positive/negative)                  | R           |
| account\_written\_as                      | Line.BillModeCode                                | 'D' maps to DC (Direct to Client); any other value maps to B (Brokerage)               | R           |
| rpg                                       | 0                                                | Hardcoded false                                                                        | R           |
| purchasing\_group\_name                   |                                                  | Not supplied by the integration                                                        | Rec         |
| risk\_description                         | Policy.DescriptionOf                             |                                                                                        | O           |
| multi\_state                              | 0                                                | Hardcoded false                                                                        | O           |
| dba                                       | 0                                                | Hardcoded false                                                                        | O           |
| transaction\_line\_of\_business\_list     | CdPolicyLineType.CdPolicyLineTypeCode            | Pipe-joined across policy lines                                                        | R           |
| transaction\_line\_of\_business\_coverage | Policy.BilledPremium ÷ line count                | Pipe-joined; premium split evenly per line                                             | R           |
| non\_admitted\_insurer\_code\_list        | Company.NAICCode                                 | Pipe-joined across policy lines                                                        | Rec         |
| non\_admitted\_insurer\_code\_coverage    | 100 ÷ line count                                 | Pipe-joined; split evenly per line                                                     | Rec         |
| syndicate\_list                           |                                                  | Not supplied by the integration                                                        | Rec         |
| syndicate\_list\_coverage                 |                                                  | Not supplied by the integration                                                        | Rec         |
| premium                                   | Policy.BilledPremium                             |                                                                                        | O           |
| agency\_fee                               | Invoice line amount                              | Broker Fee; summed by Taxes and Fees code mapping                                      | R           |
| inspection\_fee                           | Invoice line amount                              | Carrier Fee; summed by Taxes and Fees code mapping                                     | R           |
| sl\_tax                                   | Invoice line amount                              | Summed by Taxes and Fees code mapping                                                  | O           |
| stamping\_fee                             | Invoice line amount                              | Summed by Taxes and Fees code mapping                                                  | O           |
| sl\_service\_charge                       | Invoice line amount                              | Summed by Taxes and Fees code mapping                                                  | O           |
| municipal\_fee                            | Invoice line amount                              | Summed by Taxes and Fees code mapping                                                  | O           |
| fm\_tax                                   | Invoice line amount                              | Summed by Taxes and Fees code mapping                                                  | O           |
| empa\_tax                                 | Invoice line amount                              | Summed by Taxes and Fees code mapping                                                  | O           |
| total                                     | Invoice lines                                    | Sum of all invoice line amounts                                                        | O           |
| mailing\_insured\_name                    | Line.ContactNameBillTo                           |                                                                                        | R           |
| mailing\_address                          | Line.Address1BillTo                              |                                                                                        | R           |
| mailing\_address2                         | Line.Address2BillTo                              |                                                                                        | O           |
| mailing\_city                             | Line.CityBillTo                                  |                                                                                        | R           |
| mailing\_zip\_code                        | Line.PostalCodeBillTo                            |                                                                                        | R           |
| mailing\_state\_code                      | Line.CdStateCodeBillTo                           |                                                                                        | R           |
| insured\_email                            | Line.Email                                       |                                                                                        | O           |
| insured\_phone                            | Line.Fax                                         | Sourced from the Fax field                                                             | O           |
| physical\_same\_as\_mailing               | 1                                                | Hardcoded true                                                                         | R           |
| physical\_address                         |                                                  | Not supplied by the integration                                                        | Rec         |
| physical\_city                            |                                                  | Not supplied by the integration                                                        | Rec         |
| physical\_zip\_code                       |                                                  | Not supplied by the integration                                                        | Rec         |
| physical\_state\_code                     | Line.CdStateCodeIssuing                          |                                                                                        | R           |
| agent\_id                                 | Policy.AgencyCode                                | Mapped via Agency mapping; agencies mapped to "Do Not Import" are skipped              | O           |
| agent\_notes                              |                                                  | Generated: "Applied Epic Invoice #\<invoice number>"                                   | Rec         |
| anniversary\_billing                      | 0                                                | Hardcoded false                                                                        | O           |


## Applied Epic™

Streamlines tax filing, reporting, and reconciliation by automatically importing policy data into InsCipher.

Applied Epic customers who use the Google BigQuery Data Lake connection method can import policy data into the InsCipher platform automatically.

### Ownership & responsibilities

This integration is **built and maintained by InsCipher**. Your agency completes setup inside InsCipher Connect® using the Integration Wizard, with support from the InsCipher team. The table below shows who handles what.

| Area                                                       | InsCipher | Your agency |
| ---------------------------------------------------------- | --------- | ----------- |
| Integration tool, wizard, and daily import logic           | ✓         |             |
| BigQuery Data Lake access (via your Applied subscription)  |           | ✓           |
| BigQuery credentials (Database Name, Project ID, JSON Key) |           | ✓           |
| Field mapping in the Integration Wizard                    | ✓         |             |
| Surplus-lines tax rates and compliance updates             | ✓         |             |
| Integration support and maintenance                        | ✓         |             |

:::tip[What this integration does]
Uses Applied Epic's Google BigQuery Data Lake connection to automatically pull policy data into InsCipher.
:::

:::note[What this integration does not do]
* It cannot pull documents associated with policy data.
* There is no Tax Calculation or Payment Reconciliation functionality yet. Both are being researched for future phases.
:::

### Before you start

This service is not available to all clients. At a minimum, you must be subscribed to Applied Epic's Google BigQuery Data Lake connection method. If you are an Applied Epic customer but don't use this connection, contact your Applied account representative or account manager to find out whether it can be enabled for your agency.

Connection via SDK or BDE is **not supported** at this time.

Before setup, check with your IT/security team to confirm that no firewalls or restrictions will block the integration or the data transfer. For setup questions not covered in this guide, contact <a href="mailto:support@inscipher.com">[support@inscipher.com](mailto\:support@inscipher.com)</a>.

### Technical requirements

To set up the Applied Epic policy import, you need:

* Access to the Google BigQuery Data Lake associated with your Applied account.
* Admin rights in BigQuery, so you can pull the credentials required by the InsCipher Integration Wizard.

Once you have these, continue to <a href="/integrations/applied-systems/applied-epic/import-policy-data">Import Policy Data</a> to run the setup wizard.


## Troubleshooting

Tips for resolving issues with the Applied Epic Data Lake integration. InsCipher notifies you by email and in the notification center when any of the cases below occur.

### Warnings

Prompts that encourage you to act on something that could lead to an adverse outcome if left too long.

| Title                  | Description                                                    | Suggested action                                        |
| ---------------------- | -------------------------------------------------------------- | ------------------------------------------------------- |
| Integration Incomplete | The system detects an incomplete integration before Step 3.    | Complete the integration steps through Step 3.          |
| Fields Need Mapping    | Required field mapping on Step 3 was started but not finished. | Complete the mapping exercise for all tables on Step 3. |

### Errors

System messages indicating technical problems that lead to partial or lost functionality.

| Title                          | Description                                          | Suggested action                                                                                                                                                                                                                                                      |
| ------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Integration Connection is Lost | The integration tool cannot connect to Applied Epic. | **Manually import data missed during the outage:** On Step 4 / Summary, click **Trigger a Manual Import** and select the date your connection was lost and your agency stopped receiving data. This pulls in the information that failed to import during the outage. |

For any other errors, contact <a href="mailto:support@inscipher.com">InsCipher support</a>.


## Authentication

InsCipher's API supports two methods of authentication: **API Key** and **OAuth 2.0**. Both can be used independently or simultaneously depending on your security requirements.

### Getting Your API Key

* **Connect® clients:** Go to **Settings > User List & Settings**, select the Agency Admin user, and click **Get a new API Key** under API & Batch Import Settings. One key covers all agencies in your account.
* **Filing Services® clients:** Go to **Settings > API > Edit > API Information** and click **Get a new API Key**.
* Alternatively, contact customer support for assistance.

:::danger[Keep Your API Key Safe]
Your API key is shown **once** at generation. Losing it requires generating a new one, which immediately **inactivates the old key**.
:::

### Endpoints

| Environment | Base URL                              |
| ----------- | ------------------------------------- |
| Sandbox     | `https://sandbox.inscipher.com/`      |
| Production  | `https://surpluslines.inscipher.com/` |

:::warning
All requests must be made over HTTPS.
:::

### API Key Authentication

Depending on the endpoint, pass your API key either as a query parameter or in the request header.

**Query parameter**

```
/api/v1/get-transaction-status.json?apikey=YOUR_API_KEY&transaction_id=1121168
```

**Request header**

```bash
curl --request POST \
     --url https://surpluslines.inscipher.com/api/tax-calculator/calculate-general-taxes \
     --header 'accept: application/json' \
     --header 'apiKey: YOUR_API_KEY' \
     --header 'content-type: application/json'
```

### OAuth 2.0 Authentication

OAuth 2.0 is available alongside API key authentication. To use it, you must have API access already enabled and know your username and password.

#### 1. Obtain Access Token

```http
POST /api/oauth2/token
Content-Type: application/json

{
  "grant_type": "password",
  "username": "your_username",
  "password": "your_password"
}
```

**Response fields**

| Field           | Description                                |
| --------------- | ------------------------------------------ |
| `access_token`  | Used for authenticated API requests        |
| `refresh_token` | Used to obtain a new access token          |
| `expires_in`    | Token lifetime in seconds (typically 3600) |

#### 2. Refresh Token

```http
POST /api/oauth2/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "your_refresh_token"
}
```

:::note
Refresh tokens are valid for 1 month. After expiry, re-authenticate with username and password (Step 1).
:::

#### 3. Use the Token

```http
GET /api/protected/resource
Authorization: Bearer your_access_token
```

An expired or invalid token returns `401 Unauthorized`.


## Introduction

Welcome to the InsCipher Developer Hub. Use our APIs, webhooks, and integrations to calculate surplus lines taxes, complete diligent effort forms, and import policy transactions and documents.

:::warning[Active Account Required]
This guide is for current InsCipher customers with an active account. If you're new, [book a demo](https://www.inscipher.com/demo) or [contact sales](https://www.inscipher.com/contact).
:::

### Available APIs and Webhooks

The following APIs and Webhooks are available for both **Filing Services®** and **Connect®** clients.

<img src="/images/connect-image.png" style={{width: '85%'}} />

| Type          | API                                                                     | Description                                                       | Use Cases / Benefits                                                                                                                         |
| ------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| POST          | <a href="/api/tax-calculations">SL Tax Calculator</a>                   | Calculate SL taxes using InsCipher's engine                       | Get calculated SL taxes and state-specific fees; retrieve filing document requirements; get state stamp wording; apply fee restriction logic |
| POST          | <a href="/api/diligent-forms">Diligent Forms</a>                        | Auto-fill state diligent effort forms and affidavits              | Submit policy data and diligent search results; receive a completed state form for all 50 states                                             |
| POST          | <a href="/api/transaction-import/overview">Transaction Import</a>       | Import policy transaction details and documents                   | **Single** — immediate success/fail response; **Batch** — submit batch, then poll for results                                                |
| GET           | <a href="/api/transaction-import/import-status">Batch Import Status</a> | Retrieve results for previously imported batches                  | Check import status; surface tax errors, missing fields, and missing documents                                                               |
| POST          | <a href="/api/document-import">Document Import</a>                      | Import policy documents and diligent effort affidavits separately | Attach documents after transactions have been imported                                                                                       |
| GET           | <a href="/api/transaction-search">Transaction Search</a>                | Search and retrieve transaction details and filing status         | Look up filed transactions by policy number, invoice, date range; get filing status, tax paid dates, SLA transaction IDs                     |
| GET           | <a href="/api/transaction-status">Transaction Status</a>                | Retrieve current status and full details for a single transaction | Check filing status, tax and fee breakdown, paid dates, and attached documents by transaction ID or invoice number                           |
| HTTP Callback | <a href="/webhooks/overview">Webhooks</a>                               | Receive event callbacks                                           | Get notified when transaction events occur                                                                                                   |

### Terminology

| Term                     | Definition                                                                     |
| ------------------------ | ------------------------------------------------------------------------------ |
| **Transaction / Filing** | Policy data, invoice details, or an individual policy filing.                  |
| **Surplus Lines**        | Non-admitted policies written on the Excess and Surplus Lines market.          |
| **Documents**            | Policy documents — declination pages, full policy docs, diligent effort forms. |
| **Line of Business**     | The Line of Business / Coverage Code associated with the policy.               |

### Rate Limits

:::warning[Rate Limit]
InsCipher API requests are limited to **10,000 requests per API key, per minute** across all public endpoints. Exceeding this limit returns a `429 Too Many Requests` response. Wait until the next minute to retry.
:::

### Errors

InsCipher uses standard HTTP response codes:

| Code  | Meaning                                            |
| ----- | -------------------------------------------------- |
| `2xx` | Success                                            |
| `4xx` | Client-side error — invalid or missing information |
| `5xx` | Server-side error                                  |


## Templates & Field Reference

Download the template for your account type. Each template has three sheets:

1. **Instructions** — overview and tips
2. **Field List & Definitions** — descriptions and accepted values for every field
3. **Import File > Save as .CSV** — fill in your data here, then save this sheet as `.csv` before uploading to InsCipher

| Account type                            | Template                                                                                                                                 |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Filing Services® and Connect® users** | <a href="/openapi/CSV_Transaction_Import_Template_Filing_Services_Connect.xlsx" download>Download Filing Services & Connect Template</a> |
| **Utah Broker users**                   | <a href="/openapi/CSV_Transaction_Import_Template_Utah.xlsx" download>Download Utah Broker Template</a>                                  |

For import codes (transaction types, lines of business, insurance companies, document types), refer to your mapping packet:

* [Filing Services® clients](https://lookerstudio.google.com/u/0/reporting/0b499657-4b92-4336-9bb3-c3650692bcf9/page/p_fxcbrpspyc)
* [Connect® clients](https://lookerstudio.google.com/u/0/reporting/41dce747-d045-4e1f-884d-07d23581a90a/page/p_fxcbrpspyc)
* [Utah Broker clients](https://datastudio.google.com/u/0/reporting/b58e42e6-38ac-4d36-9b03-422c45a6e83a/page/p_vw82sh8crc)

:::note
Boolean fields (`rpg`, `physical_same_as_mailing`, `layered_risk`, etc.) accept either `1`/`0` or `yes`/`no`. Both formats produce the same result.
:::


## Import Documents

<div style={{position: 'relative', width: '80%', paddingBottom: '45%'}}>
  <iframe src="https://veracityinsuranceso.sharepoint.com/sites/InsCipher/_layouts/15/embed.aspx?UniqueId=94b8e832-b189-4aec-8843-dff85f2c7762&embed=%7B%22hvm%22%3Atrue%2C%22ust%22%3Atrue%7D&referrer=StreamWebApp&referrerScenario=EmbedDialog.Create" frameborder="0" scrolling="no" allowfullscreen style={{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 'none'}} />
</div>

After importing transactions, you can bulk attach policy documents to them using the Document Import wizard.

:::note
There is a limit of 500 transactions per bulk document attachment session.
:::

### Open the Document Import Wizard

You can open the wizard from two places:

**From the Filings Import Log:**

1. In the top navigation bar, go to **Filings > Filings Import Log**.

<img src="/images/csv-import/log-navigation.png" alt="Filings top navigation" style={{width: '50%'}} />

2. Find the relevant batch.
3. Click **Attach Documents**.

<img src="/images/csv-import/attach_documents.png" alt="Filings Import Log — Attach Documents button" style={{width: '80%'}} />

**From the Filing List:**

1. Go to **Filings > All Filings**.

<img src="/images/csv-import/All_filings.png" alt="Filings menu — All Filings" style={{width: '50%'}} />

2. Select one or more transactions. A dialog will appear in the bottom right showing the number of selected items.

<img src="/images/csv-import/check_all.png" alt="Filing list with transactions selected" style={{width: '80%'}} />

3. Click the **Select an Action** dropdown and choose **Attach Documents**.
4. Click **Submit**, then confirm in the dialog that appears.

<img src="/images/csv-import/confirm_bulk_attachment.png" alt="Bulk Attach Documents confirmation" style={{width: '35%'}} />

### 1. Choose Upload Method

Select whether you want to upload **one file at a time** or **multiple files at once**.

| Method                     | Best for                                                                                                                  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **One file at a time**     | Reviewing a list of filings and dragging documents onto each one individually.                                            |
| **Multiple files at once** | Attaching all documents in a single upload, mapped to transactions either manually via CSV or automatically by InsCipher. |

<img src="/images/csv-import/Chose_method.png" alt="Select Upload Method screen" style={{width: '80%'}} />

### 2. Upload Documents

The next step depends on the method you selected.

#### One file at a time

You will see a list of transactions with unfulfilled document requirements. The **Document Description** column shows which required document is missing for each transaction.

<img src="/images/csv-import/document-description.png" alt="Transaction list with Document Description column" style={{width: '80%'}} />

Drag and drop the appropriate document onto the transaction, or click to select it from your computer.

The **Proceed without attaching all required documents** toggle lets you finalize and submit before all requirements are met — you can return later to attach remaining documents.

<img src="/images/csv-import/proceed-without-attaching-all.png" alt="Match and Submit — Proceed without attaching toggle" style={{width: '80%'}} />

:::tip
* Open the document importer in one window and your file explorer in another — drag and drop directly between them.
* You can save progress and return later for any documents you haven't attached yet.
:::

#### Multiple files at once

Upload all your document files at once. After uploading, use the **Would you like us to automatically classify your documents?** toggle to choose the mapping method.

<img src="/images/csv-import/would-you-like-to-classify-automatically.png" alt="Automatically classify documents toggle" style={{width: '80%'}} />

##### Map manually with a CSV file

Set the toggle to **No**. An additional **CSV Mapping File** upload area appears — upload your document files and your mapping CSV, then click **Continue**.

<img src="/images/csv-import/no-selected.png" alt="No selected — CSV Mapping File upload visible" style={{width: '80%'}} />

The CSV mapping file requires these headers:

| Header           | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `invoice_number` | The invoice number used when the transaction was imported. Used to match the document to the correct transaction. |
| `code`           | InsCipher's document import code for the document type. See the mapping packet for your client type below.        |
| `file`           | Exact file name including extension, matching the files you uploaded.                                             |

<img src="/images/csv-import/excel-example.png" alt="CSV mapping file example" style={{width: '25%'}} />

#### Document import code mapping packets

| Client type              | Mapping packet                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| Filing Services®         | [View](https://lookerstudio.google.com/u/0/reporting/0b499657-4b92-4336-9bb3-c3650692bcf9/page/p_otc1uchjqc) |
| Connect®                 | [View](https://lookerstudio.google.com/u/0/reporting/41dce747-d045-4e1f-884d-07d23581a90a/page/p_otc1uchjqc) |
| Utah-registered agencies | [View](https://lookerstudio.google.com/u/0/reporting/9b80f242-d698-4128-b457-e1875a7333b2/page/p_otc1uchjqc) |

[Download sample CSV mapping file](https://22769583.fs1.hubspotusercontent-na1.net/hubfs/22769583/documents%20\(3\).csv)

:::tip
If you are attaching more than 20 documents at a time, using a CSV mapping file speeds up the process.
:::

##### Let InsCipher classify documents automatically

Set the toggle to **Yes**. Upload your document files, then click **Continue**.

<img src="/images/csv-import/yes-selected.png" alt="Yes selected — documents only upload" style={{width: '80%'}} />

InsCipher will match each document to a transaction automatically. The progress bar at the top of the **Match & Submit** screen shows that mapping is in progress — this can take a few seconds to several minutes.

<img src="/images/csv-import/progress-bar.png" alt="Match and Submit — mapping in progress" style={{width: '80%'}} />

When mapping completes, any unresolved documents appear as **Unmapped documents**. Review these manually — select the correct transaction and document type for each unmapped file.

<img src="/images/csv-import/errors.png" alt="Match and Submit — unmapped documents" style={{width: '80%'}} />

<img src="/images/csv-import/manual-doc-type.png" alt="Manually selecting filing and document type" style={{width: '80%'}} />

### 3. Finalize the Mapping

When you are ready, click **Finalize Document Mapping**. Confirm in the dialog that appears.

<img src="/images/csv-import/finalise_document_mapping.png" alt="Finalize Document Mapping confirmation" style={{width: '30%'}} />

You will be redirected back to the page you started from — the Filings Import Log or the Filing List.


## Import Transactions

Rather than submitting policy transactions one by one through the tax calculator wizard, you can upload a batch of transactions at once using a spreadsheet file.

<div style={{position: 'relative', width: '80%', paddingBottom: '45%'}}>
  <iframe src="https://support.inscipher.com/hubfs/Dev%20Hub/FS%20CSV%20Batch%20Import%20Tutorial_04112025.mp4" frameborder="0" scrolling="no" allowfullscreen style={{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 'none'}} />
</div>

### Before You Begin

Download the template for your account type. The template includes all supported fields with descriptions and accepted values.

| Account type                            | Template                                                                                                                                 |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Filing Services® and Connect® users** | <a href="/openapi/CSV_Transaction_Import_Template_Filing_Services_Connect.xlsx" download>Download Filing Services & Connect Template</a> |
| **Utah Broker users**                   | <a href="/openapi/CSV_Transaction_Import_Template_Utah.xlsx" download>Download Utah Broker Template</a>                                  |

For additional notes on specific fields, see the <a href="/csv-imports/field-reference">Field Reference</a>.

### 1. Prepare Your File

You have two options:

* **Use the InsCipher template** — open the **Field List & Definitions** sheet for descriptions and accepted values for each field, then fill in your data in the **Import File > Save as .CSV** sheet and save the file as `.csv` before uploading.
* **Export from your policy management system** — if your system already produces a usable file, you can upload it with any column names. You will map them to InsCipher fields in [step 4](#4-map-columns).

:::note
Make sure your file is in `.csv` format — not `.csv (UTF-8)`, `.xls`, or `.xlsx`.
:::

### 2. Navigate to Batch Import

In the top navigation bar, go to **Filings > Batch Import**.

<img src="/images/csv-import/nav-top-batch-import.png" alt="Batch Import top navigation" style={{width: '80%'}} />

### 3. Upload the CSV File

Upload your file. Connect® clients: first select your **Agency** from the dropdown, then upload.

Click **Continue** to proceed to column mapping.

<img src="/images/csv-import/upload-fs.png" alt="Upload screen — Filing Services® clients" style={{width: '80%'}} />

### 4. Map Columns

Map the columns from your file to the required InsCipher headers.

**1. Use a saved mapping (if available)**

If you have imported before, click **Use saved mapping** to skip to step 5 — the system remembers your previous column mapping. To review or update it, click **Review column mapping**.

<img src="/images/csv-import/map-saved-mapping.png" alt="Column mapping — saved mapping option" style={{width: '80%'}} />

**2. Select the physical state column**

Select the column in your file that contains the physical/risk state. In the InsCipher template this is `physical_state_code`. In custom files it may have a different name.

<img src="/images/csv-import/map-physical-state-group-by.png" alt="Physical state column and Group By Column" style={{width: '80%'}} />

If your file has **multiple rows per transaction** (for example, one row per line of business), set **Group By Column** to the column that identifies each unique transaction — such as `Transaction #`. Leave it blank if each transaction is already on a single row.

<img src="/images/csv-import/map-group-by-example.png" alt="Multi-row CSV example" style={{width: '45%'}} />

**3. Map all remaining columns**

<img src="/images/csv-import/map-sections.png" alt="Column mapping sections" style={{width: '80%'}} />

Fields are grouped into three sections:

| Section         | Description                                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Required**    | Must be mapped to proceed. If you don't have data for a required field, map the header anyway and leave the data blank — you can fill in placeholders during Validate & Submit. |
| **Recommended** | Needed to complete the transaction for filing in most states.                                                                                                                   |
| **Other**       | Optional in most states.                                                                                                                                                        |

<img src="/images/csv-import/summary.png" alt="Column mapping progress summary" style={{width: '60%'}} />

**Multi-index fields** (marked in the UI) let you map multiple columns from your file into a single InsCipher field. For example, if you have separate columns per line of business:

* Map `LOB1`, `LOB2`, `LOB3` → **Line of Business List**
* Map `LOB1 Premium`, `LOB2 Premium`, `LOB3 Premium` → **Premium Breakdown**

The number of columns mapped to Line of Business List must match the number mapped to Premium Breakdown, or you will get an import error.

<img src="/images/csv-import/map-multi-index.png" alt="Multi-index field mapping" style={{width: '45%'}} />

To skip unmapped columns, click **Don't import data in unmapped columns** before proceeding.

### 5. Validate & Submit

Review your data before submitting. Two views are available:

* **View Error Rows Only** — shows only rows with validation errors. Click any highlighted cell to correct the value.
* **View All Rows** — shows all rows. Use this to make final adjustments before import.

<img src="/images/csv-import/validate-submit.png" alt="Validate & Submit screen" style={{width: '80%'}} />

**Quick ways to fix errors:**

| Option                                            | Effect                                                        |
| ------------------------------------------------- | ------------------------------------------------------------- |
| Click the number on a column header               | Shows a summary of all issues in that column                  |
| **Apply to identical error** (checkbox 1)         | Fixes all rows with the same error in the current import      |
| **Apply to future identical errors** (checkbox 2) | Auto-applies your fix to the same value in all future imports |

If there are too many errors to address, fix the underlying file and start a new import.

<img src="/images/csv-import/validate-error-checkboxes.png" alt="Error fix checkboxes" style={{width: '50%'}} />

For accepted values and field descriptions, see the <a href="/csv-imports/field-reference">Field Reference</a>.

When you are ready, click **Continue**. Your file will be queued for import. If any errors remain after import, they will appear in the **Filings Import Log**.


import { CsvOverviewPage } from '../../components/CsvOverviewPage'

<CsvOverviewPage />


## Troubleshooting Imports

All import batches are logged, including transactions that were imported successfully, transactions that were not imported, and the original import file. This page covers how to review the import log, fix errors, and manage batches.

### Open the Filings Import Log

In the top navigation bar, go to **Filings > Filings Import Log**.

<img src="/images/csv-import/log-navigation.png" alt="Filings Import Log — top navigation" style={{width: '50%'}} />

### Review Transactions in a Batch

Click **View Transactions** on the batch to see all transactions imported in that batch.

<img src="/images/csv-import/View-transactions.png" alt="Filings Import Log — View Transactions button" style={{width: '80%'}} />

### Download the Original Import File

To review the file that was imported, click **Import File** on the batch.

<img src="/images/csv-import/import-file.png" alt="Filings Import Log — Import File button" style={{width: '80%'}} />

### Download the Error Log

If a batch contains import errors, an **Error Log** button appears on the batch. Click it to download a list of all errors.

<img src="/images/csv-import/error-log.png" alt="Filings Import Log — Error Log button" style={{width: '80%'}} />

Each entry in the error log shows the reason for the error followed by the policy number that failed to import.

<img src="/images/csv-import/csv-sample1.png" alt="Error log content — errors with policy numbers" style={{width: '70%'}} />

### Fix Errors in a Batch

To fix errors, open the batch and correct the values in the affected rows.

<img src="/images/csv-import/csv2-correct-error.png" alt="CSV file with highlighted error values to correct" style={{width: '70%'}} />

For accepted values and field descriptions, see the <a href="/csv-imports/field-reference">Field Reference</a>.

### Delete a Batch

If a batch contains too many errors to fix individually, delete the entire batch using the **Delete** button on the batch. Then fix the underlying file and re-import.

<img src="/images/csv-import/delete-batch.png" alt="Filings Import Log — Delete button" style={{width: '80%'}} />

### Attach Documents to a Batch

To attach policy documents to transactions in a batch, click **Attach Documents**. This opens the <a href="/csv-imports/import-documents">Document Import wizard</a>.

<img src="/images/csv-import/attach-docs.png" alt="Filings Import Log — Attach Documents button" style={{width: '80%'}} />


## Changelog

Release notes for InsCipher APIs, integrations, and platform updates.

| Date      | Release                                                          | Areas                                                     |
| --------- | ---------------------------------------------------------------- | --------------------------------------------------------- |
| June 2026 | <a href="/changelog/tax-calculator-v2-2">Tax Calculator v2.2</a> | Tax Calculator · Transaction Import · Affidavit · Exports |


## Tax Calculator v2.2

**June 2026** · Tax Calculator · Transaction Import · Affidavit · Exports

New Jersey Fire Premium support — improving how Fire Premium is handled for New Jersey filings so your Fire Tax and Surplus Lines Tax calculate more accurately and stay aligned with the state's requirements. You can now tell us how much of your premium is Fire Premium, and InsCipher uses that to calculate the right taxes. The update applies across imports, tax calculations, affidavits, and exports, and is available now in Sandbox so your team can test ahead of the production release.

### What's changing for your integration

**Imports** (Transaction Import & Single Transaction Import): a new `fire_premium` field to report the premium allocated to fire. For multi-line-of-business filings, fire coverage is reported the same way you already report coverage today.

**Affidavit submissions**: a new `fire_premium` field is now accepted.

**Tax Calculator response** (new version 2.2): the response now includes Fire Premium tax logic. Specifically:

* The existing `premium` field has been renamed to `total_premium`, and a new `fire_premium` value is returned under it.
* A new `is_multiple_calculations_active` flag (`true`/`false`) has been added to the `tax_rule` section.
* A new `sl_tax_multiple` section is returned within `tax_rule` when multiple calculations apply (e.g. New Jersey), containing:
  * `sl_tax_amount_type`
  * `sl_tax_amount`
  * `sl_tax_amount_applies_to`
* A new `fm_tax` section is returned within `tax_rule`, containing:
  * `is_fire_tax_based_on_fire_premium_active` — indicates the state uses the Fire Premium total to calculate the Fire Marshal tax
  * `fm_tax_title` — the renamed tax title
  * `fm_tax_amount_type`
  * `fm_tax_amount`
  * `fm_tax_amount_applies_to`
* The `fm_tax` fields previously included per line of business in `line_of_business_list` have been removed and now live in the new `fm_tax` section above.

When a state's settings don't use Fire Premium for the requested period (expired or before the start date), the tax calculation is unchanged.

Because this is a new API version, your current integration keeps working until you choose to move up. See the <a href="/api/tax-calculations">Tax Calculator v2.2 reference</a> for full request and response details.

**Exports**: a new `FirePremium` column is included in your CSV and XLS exports.


import { ScalarApiRef } from '../../components/ScalarApiRef'

## Diligent Forms <span className="method-post">POST</span>

The Diligent Forms API automates surplus lines compliance document production, eliminating the manual process of downloading blank templates and filling them out by hand.

The API stores diligent search data and uses policy details passed in the request to auto-populate affidavits, state filing forms, and diligent effort forms, including carrier declination information sourced directly from your AMS. It returns a JSON response with download URLs for each generated document, along with field-level warnings for any data gaps requiring manual completion.

The API integrates into existing AMS, quote/bind, or rating systems, and the underlying compliance database is maintained by InsCipher's team with thousands of regulatory variables updated monthly, ensuring returned forms always reflect current state requirements.

* [Endpoint](#endpoint)
* [How It Works](#how-it-works)
* [Key Variables](#key-variables)
* [How to Use This Request](#how-to-use-this-request)

### Endpoint

| Environment    | URL                                                                         | Method |
| -------------- | --------------------------------------------------------------------------- | ------ |
| **Sandbox**    | `https://sandbox.inscipher.com/api/pdf-filing-affidavit/generate.json`      | POST   |
| **Production** | `https://surpluslines.inscipher.com/api/pdf-filing-affidavit/generate.json` | POST   |

:::warning
All API requests must be made over HTTPS and must include a valid API key in the `apikey` request header. See <a href="/getting-started/authentication">Authentication</a> for details.
:::

### How It Works

1. Submit a POST request with the policy and insured details.
2. InsCipher determines the applicable state forms and populates them using the request data and stored configuration (diligent search records, license info, signatures).
3. The API returns a JSON response containing time-limited download URLs for each generated document.
4. Retrieve the documents using the returned URLs.

:::note
Not every field is used in every document. When required information is not provided or cannot be determined, the document is returned with partial information and must be completed manually.
:::

#### Signatures

Signature fields (`insured_signature`, `sl_broker_signature`, `retail_producer_signature`) accept a **Base64-encoded PNG** image string. If signatures are already stored in the license/user configuration in InsCipher, they are applied automatically and do not need to be passed in the request.

### Key Variables

| Resource                                                                                                                             | Purpose                                            |
| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| [Transaction Types](https://datastudio.google.com/u/0/reporting/41dce747-d045-4e1f-884d-07d23581a90a/page/p_83noca0k9c)              | Map your transaction types to InsCipher codes      |
| [Generic Lines of Business](https://lookerstudio.google.com/u/0/reporting/f3c07407-ee34-4ec9-8a4a-f90b1d585e6b/page/p_4q66kh8crc)    | Map lines of business to InsCipher import codes    |
| [Complete Diligent Forms List](https://lookerstudio.google.com/u/0/reporting/0ee44eef-a838-4b25-99ca-1b61bf11b14b/page/p_r8qinkl7fd) | All state forms and their document codes           |
| [Declining Reasons](https://lookerstudio.google.com/u/0/reporting/0ee44eef-a838-4b25-99ca-1b61bf11b14b/page/p_anzzcq710d)            | Allowed values for `dc_declining_reason` by state  |
| [Received Declination Options](https://lookerstudio.google.com/u/0/reporting/0ee44eef-a838-4b25-99ca-1b61bf11b14b/page/p_fld9hmw20d) | Allowed values for `dc_who_received_declinations`  |
| [Underwriting Considerations](https://lookerstudio.google.com/u/0/reporting/0ee44eef-a838-4b25-99ca-1b61bf11b14b/page/p_wy2ov6z20d)  | Allowed values for `dc_underwriting_consideration` |
| [Policy Limit Requirements](https://lookerstudio.google.com/u/0/reporting/41dce747-d045-4e1f-884d-07d23581a90a/page/p_fxcbrpspyc)    | State-by-state `policy_limit` requirements         |

***

### How to Use This Request

<ScalarApiRef specUrl="/openapi/diligent-forms.yaml" minHeight="80vh" showResponseDesc expandResponse />


import { ScalarApiRef } from '../../components/ScalarApiRef'

## Document Import <span className="method-post">POST</span>

The Document Import API lets agencies programmatically attach policy-related documents to existing transactions. Use this endpoint when documents are not already included in a [Single](/api/transaction-import/single) or [Batch](/api/transaction-import/batch) Transaction Import request — documents should not be submitted through both methods for the same transaction.

* [Endpoint](#endpoint)
* [How It Works](#how-it-works)
* [Key Variables](#key-variables)
* [How to Use This Request](#how-to-use-this-request)

### Endpoint

| Environment    | URL                                                                                  | Method |
| -------------- | ------------------------------------------------------------------------------------ | ------ |
| **Sandbox**    | `https://sandbox.inscipher.com/api/v4/transaction/{idOrInvoiceNumber}/document`      | POST   |
| **Production** | `https://surpluslines.inscipher.com/api/v4/transaction/{idOrInvoiceNumber}/document` | POST   |

:::warning
All API requests must be made over HTTPS and must include a valid API key in the `apikey` request header. See <a href="/getting-started/authentication">Authentication</a> for details.
:::

### How It Works

#### Identifying the Transaction

The path parameter `idOrInvoiceNumber` accepts two forms:

| Form                     | Path example                                 | Query parameter             |
| ------------------------ | -------------------------------------------- | --------------------------- |
| InsCipher Transaction ID | `/api/v4/transaction/213426/document`        | *(omit `useInvoiceNumber`)* |
| Agency Invoice Number    | `/api/v4/transaction/INVSL42398300/document` | `?useInvoiceNumber=true`    |

`useInvoiceNumber` accepts both `true`/`false` and `1`/`0`.

#### Submitting Documents

Send a POST request with a JSON **array** where each element is one document object. A single request can include multiple documents — all will be grouped under the `batch_id` returned in the response.

Each document object requires three fields: `code`, `name`, and `file` (Base64-encoded content).

#### Ad-hoc Documents

If a `code` value is not recognized, the document is imported as an ad-hoc attachment. Ad-hoc documents are attached to the transaction but are not included in state filings unless manually mapped in InsCipher.

#### Reading the Response

A `200` response confirms the batch was received, not that all documents were saved. The `documents[].status` field always returns `0` — even for rejected documents — so it cannot be used to detect failures. To check whether each document actually imported, read `documents[].status_message`: a value of `"Success"` means the document was saved.

#### Supported File Types

The server decodes the Base64 content and identifies the file type from the content itself. The filename extension in `name` is used for display only and does not affect validation.

Supported formats: `pdf`, `png`, `tiff`, `jpeg`, `jpg`, `doc`, `docx`, `xls`, `xlsx`.

:::note
If the decoded content is an unsupported file type, `status_message` returns `"Not allowed type : bin, accepted: pdf, png, tiff, jpeg, jpg, doc, docx, xls, xlsx"`. If the Base64 string itself is invalid, `status_message` returns `"Document {code} base64 content invalid"`. In both cases, the HTTP response is still `200` — check `status_message` to detect the failure.
:::

### Key Variables

| Resource              | Purpose                                           | Connect®                                                                                                     | Filing Services®                                                                                             |
| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| Document Import Codes | Map your document types to InsCipher import codes | [View](https://lookerstudio.google.com/u/0/reporting/41dce747-d045-4e1f-884d-07d23581a90a/page/p_otc1uchjqc) | [View](https://lookerstudio.google.com/u/0/reporting/0b499657-4b92-4336-9bb3-c3650692bcf9/page/p_otc1uchjqc) |

***

### How to Use This Request

<ScalarApiRef specUrl="/openapi/document-import.yaml" minHeight="80vh" expandResponse />


import { ApiOverviewPage } from '../../components/ApiOverviewPage'

<ApiOverviewPage />


import { ScalarApiRef } from '../../components/ScalarApiRef'
import { VersionSwitcher, When } from '../../components/VersionedPage'

## Tax Calculations <span className="method-post">POST</span>

InsCipher's Tax Calculator API simplifies compliance by automatically calculating complex, state-specific insurance taxes and fees for single or multi-line transactions. By providing basic details like location, dates, and coverage types, you instantly receive a complete line-by-line tax breakdown, the exact state stamp wording, transparent calculation rules, and a list of necessary filing documents to ensure accurate quoting and compliance.

* [Endpoint](#endpoint)
* [Key Variables](#key-variables)
* [FAQs](#faqs)
* [How to Use This Request](#how-to-use-this-request)

<VersionSwitcher versions={['v2.2', 'general']} defaultVersion="v2.2" />

<When v="v2.2"><p style={{fontSize: '13px', fontStyle: 'italic', color: 'var(--vocs-color_text3, #888)', margin: '-8px 0 4px'}}>v2.2 launches July 1, 2026</p></When>

### Endpoint

:::warning
All API requests must be made over HTTPS and must include a valid API key in the `apikey` request header. See <a href="/getting-started/authentication">Authentication</a> for details.
:::

<When v="general">
  | Environment    | URL                                                                             | Method |
  | -------------- | ------------------------------------------------------------------------------- | ------ |
  | **Sandbox**    | `https://sandbox.inscipher.com/api/tax-calculator/calculate-general-taxes`      | POST   |
  | **Production** | `https://surpluslines.inscipher.com/api/tax-calculator/calculate-general-taxes` | POST   |
</When>

<When v="v2.2">
  | Environment | URL                                                                             | Method |
  | ----------- | ------------------------------------------------------------------------------- | ------ |
  | **Sandbox** | `https://sandbox.inscipher.com/api/v2.2/tax-calculator/calculate-general-taxes` | POST   |
</When>

### Key Variables

Reference the following data tables when constructing requests or interpreting the response:

| Resource                                                                                                                          | Purpose                                                   |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [Transaction Types](https://datastudio.google.com/u/0/reporting/f3c07407-ee34-4ec9-8a4a-f90b1d585e6b/page/p_hu3dx3gjqc)           | Map your transaction types to InsCipher codes             |
| [Generic Lines of Business](https://lookerstudio.google.com/u/0/reporting/f3c07407-ee34-4ec9-8a4a-f90b1d585e6b/page/p_4q66kh8crc) | Map lines of business to InsCipher import codes           |
| [Unique State Tax Titles](https://lookerstudio.google.com/u/0/reporting/f3c07407-ee34-4ec9-8a4a-f90b1d585e6b/page/p_xv4ud8gjqc)   | State-specific field label definitions                    |
| [State Stamp Wording](https://lookerstudio.google.com/s/pruKt8r4i3Q)                                                              | Required disclosure text by state                         |
| [Document Requirements](https://lookerstudio.google.com/u/0/reporting/f3c07407-ee34-4ec9-8a4a-f90b1d585e6b/page/p_otc1uchjqc)     | State-specific policy documents required to bind coverage |

### FAQs

<details>
  <summary>Can I calculate taxes for future policy effective dates?</summary>

  State taxes and fees can change at any time. However, most states update taxes in the fall (if they update taxes at all). InsCipher maintains at least one full calendar year of tax rates at a time. Tax rules are updated for the following year by the InsCipher Compliance Team (typically finalized Sept/Oct). Because future rates are unpredictable, best practice is to submit transactions within the current calendar year.
</details>

<details>
  <summary>How do I calculate taxes on endorsements?</summary>

  For endorsements, submit the **difference in premium** (not the new total).

  * **APE** (Additional Premium Endorsement): Submit the positive difference (e.g., original $500, new $650, submit $150).
  * **RPE** (Return Premium Endorsement): Submit the positive difference. The system recognizes the RPE transaction type and applies it as a credit automatically.
</details>

<details>
  <summary>How are Documents returned via this endpoint?</summary>

  * **Templates:** Links to download blank state forms.
  * **Requirements:** Informational flags indicating if a specific document is required for submission.
</details>

<details>
  <summary>How do Generic Lines of Business Import Codes work?</summary>

  Use our [Generic Import Codes](https://lookerstudio.google.com/u/0/reporting/f3c07407-ee34-4ec9-8a4a-f90b1d585e6b/page/p_4q66kh8crc) (GEN-XXXX) to simplify line of business mapping to state-specific codes. Some states have line-of-business-specific tax rates (not all). Custom mapping adjustments can be requested during implementation.
</details>

<details>
  <summary>How should I understand tax titles?</summary>

  In some states, rather than having a unique field name, we have chosen to repurpose field names for specific fees. Refer to the [Unique State Tax Titles](https://lookerstudio.google.com/u/0/reporting/f3c07407-ee34-4ec9-8a4a-f90b1d585e6b/page/p_xv4ud8gjqc) datasheet for definitions.
</details>

<details>
  <summary>Do states restrict broker or carrier fees?</summary>

  Certain states restrict fees. In the JSON response, InsCipher will automatically adjust the fee amounts where fee restrictions apply. For a summary, refer to the [Fee Restrictions Guide](https://lookerstudio.google.com/u/0/reporting/f3c07407-ee34-4ec9-8a4a-f90b1d585e6b/page/p_tz4ybpmhzc).
</details>

<details>
  <summary>What classifies as 'Taxable Fees'?</summary>

  InsCipher will determine whether or not a specific broker or carrier fee is taxable and return the calculated amount in the JSON response. Map the fees you charge to the insured (in excess of premium) to either **Broker Fees** \[`agency_fee`] or **Carrier Fees** \[`inspection_fee`]. For a summary of taxable fees, please refer to the [Taxable Fees Guide](https://lookerstudio.google.com/u/0/reporting/f3c07407-ee34-4ec9-8a4a-f90b1d585e6b/page/p_f7qdebf6sd).
</details>

<details>
  <summary>How do I calculate taxes for policies with installment payments?</summary>

  Always calculate taxes on the **full policy premium**, not on individual installment amounts. States require all taxes and fees to be reported as aggregated amounts upfront — the payment schedule between the insured and the broker does not affect the tax calculation.

  **Example:** A policy with a $10,000 premium, split into 5 installments of $2,000 each:

  |                         | ❌ Incorrect              | ✅ Correct              |
  | ----------------------- | ------------------------ | ---------------------- |
  | `premium`               | `2000` (one installment) | `10000` (full premium) |
  | `sl_tax` returned       | \~$20                    | $100                   |
  | `stamping_fee` returned | \~$4                     | $20                    |

  Submit the returned totals (`sl_tax: 100`, `stamping_fee: 20`) when creating the transaction — regardless of how many installments the insured will pay.
</details>

***

### How to Use This Request

<When v="general">
  <ScalarApiRef specUrl="/openapi/tax-calculator.yaml" minHeight="80vh" showResponseDesc expandResponse />
</When>

<When v="v2.2">
  <ScalarApiRef specUrl="/openapi/tax-calculator-v2-2.yaml" minHeight="80vh" showResponseDesc expandResponse />
</When>


import { ScalarApiRef } from '../../components/ScalarApiRef'

## Transaction Search <span className="method-post">POST</span>

The Transaction Search API retrieves policy transactions previously imported into InsCipher. Results are filtered by one or more date parameters and returned in paginated pages of up to 50 transactions.

* [Endpoint](#endpoint)
* [How It Works](#how-it-works)
* [How to Use This Request](#how-to-use-this-request)

### Endpoint

| Environment    | URL                                                             | Method |
| -------------- | --------------------------------------------------------------- | ------ |
| **Sandbox**    | `https://sandbox.inscipher.com/api/v1/search-transactions`      | POST   |
| **Production** | `https://surpluslines.inscipher.com/api/v1/search-transactions` | POST   |

:::warning
All API requests must be made over HTTPS and must include a valid API key in the `apikey` request header. See <a href="/getting-started/authentication">Authentication</a> for details.
:::

### How It Works

#### Filters

All request body filters are optional. Omitting the body entirely (or sending an empty object) returns all transactions for the agency, paginated.

Three date filters are supported: `date_filed`, `policy_effective_date`, and `transaction_effective_date`. Each accepts a `from` date, a `to` date, or both:

| Filter form          | Behavior                                           |
| -------------------- | -------------------------------------------------- |
| `from` only          | Returns transactions from that date forward        |
| `to` only            | Returns transactions up to and including that date |
| Both `from` and `to` | Returns transactions within the range (inclusive)  |

When multiple filters are provided, they are combined with logical AND — only transactions matching all filters are returned.

:::note
Providing a `from` date that is later than `to` is rejected with HTTP 422. Open-ended ranges (one boundary omitted) are valid.
:::

#### Pagination

Each page returns up to 50 transactions. Use the `page` query parameter to navigate pages (e.g., `?page=2`). The default is page 1.

The response includes a `pagination` object with the following fields:

| Field      | Description                                                            |
| ---------- | ---------------------------------------------------------------------- |
| `total`    | Total number of matching transactions across all pages                 |
| `per_page` | Transactions per page — fixed at 50                                    |
| `page`     | Current page number (1-based)                                          |
| `pages`    | Total number of available pages                                        |
| `next`     | Relative URL for the next page — **omitted entirely** on the last page |

To retrieve all results, follow `pagination.next` on each response until the field is absent.

***

### How to Use This Request

<ScalarApiRef specUrl="/openapi/transaction-search.yaml" minHeight="80vh" expandResponse />


import { ScalarApiRef } from '../../components/ScalarApiRef'

## Transaction Status <span className="method-get">GET</span>

Retrieve the current status and full details of a single transaction previously submitted into the InsCipher platform. Useful for accounting, reconciliation, and tracking where a policy sits in the filing lifecycle. Provide a `transaction_id` or an `invoice_number` and the endpoint returns the transaction's status code, tax and fee breakdown, paid dates, and any attached documents.

* [Endpoint](#endpoint)
* [How It Works](#how-it-works)
* [How to Use This Request](#how-to-use-this-request)

### Endpoint

| Environment    | URL                                                                     | Method |
| -------------- | ----------------------------------------------------------------------- | ------ |
| **Sandbox**    | `https://sandbox.inscipher.com/api/v1/get-transaction-status.json`      | GET    |
| **Production** | `https://surpluslines.inscipher.com/api/v1/get-transaction-status.json` | GET    |

:::warning
All API requests must be made over HTTPS and must include a valid API key. This endpoint accepts the key as either the `apikey` request **header** (recommended) or the `apikey` **query parameter** — the header takes priority when both are present. Some accounts are configured to accept the key from the header only. See <a href="/getting-started/authentication">Authentication</a> for details.
:::

### How It Works

#### Choosing an Identifier

Supply **either** `transaction_id` **or** `invoice_number` — at least one is required. If both are provided, `transaction_id` takes precedence. Each request resolves to exactly one transaction.

| Parameter        | Description                                     |
| ---------------- | ----------------------------------------------- |
| `transaction_id` | Unique InsCipher transaction identifier.        |
| `invoice_number` | Invoice number associated with the transaction. |

***

### How to Use This Request

<ScalarApiRef specUrl="/openapi/transaction-status.yaml" minHeight="80vh" expandResponse moveResponsesRight={false} />


import { ScalarApiRef } from '../../../components/ScalarApiRef'

## Transaction Import — Batch <span className="method-post">POST</span>

The Batch Import endpoint allows agencies to import multiple policy transactions in a single request. Processing is asynchronous — submit the batch, then retrieve results via webhook or a GET status request. Use this endpoint for daily batch jobs and high-volume integrations.

* [Endpoint](#endpoint)
* [How It Works](#how-it-works)
* [LOB and Carrier Format](#lob-and-carrier-format)
* [How to Use This Request](#how-to-use-this-request)

### Endpoint

| Environment    | URL                                                     | Method |
| -------------- | ------------------------------------------------------- | ------ |
| **Sandbox**    | `https://sandbox.inscipher.com/api/v4/transaction`      | POST   |
| **Production** | `https://surpluslines.inscipher.com/api/v4/transaction` | POST   |

:::warning
All API requests must be made over HTTPS and must include a valid API key in the `apikey` request header. See <a href="/getting-started/authentication">Authentication</a> for details.
:::

### How It Works

#### Submitting the Batch

Send a POST request with a JSON array where each element is one policy transaction. A `batch_id` is returned immediately in the response. Every Batch Import request generates a new unique `batch_id`.

The response includes a top-level `status` for the batch and a per-transaction `status` for each item:

**Batch-level `status`** (top-level field):

| Value                    | Description                                                 |
| ------------------------ | ----------------------------------------------------------- |
| `processing`             | Batch accepted and scheduled; transactions not yet imported |
| `waiting_for_processing` | Batch is queued and waiting                                 |
| `failed`                 | The entire batch processing attempt failed                  |

**Per-transaction `status`** (inside each `transactions[]` object):

| Value  | Description                                           |
| ------ | ----------------------------------------------------- |
| `0`    | Transaction imported successfully                     |
| `2001` | Validation error — check `status_message` for details |

:::note
A `200` HTTP response only confirms the batch was received and queued. Always check per-transaction `status` to know whether each transaction actually imported.
:::

#### Retrieving Results

##### Webhook (Recommended)

Configure a webhook to receive a callback when the batch status changes to `Processed`. This is the recommended approach for production integrations.

Event name: `webhook.batch.status.processed`

<a href="/webhooks/event-reference/batch-events">Read more about the Batch Status Processed webhook</a>

##### GET Request

Alternatively, poll the <a href="/api/transaction-import/import-status">Import Status</a> endpoint to check whether specific transactions imported successfully.

```
GET /api/v4/transaction-import-results?batch_id={batch_id}
```

See <a href="/api/transaction-import/import-status">Import Status</a> for the complete list of per-transaction result codes.

### LOB and Carrier Format

The Batch endpoint uses **pipe-delimited strings** for lines of business, carriers, and declining carriers — unlike the Single endpoint, which uses arrays of objects.

| Field                                   | Format                               | Notes                                          |
| --------------------------------------- | ------------------------------------ | ---------------------------------------------- |
| `transaction_line_of_business_list`     | `GEN-1001\|GEN-1002\|GEN-1003`       | Use for single and multiple LOBs               |
| `transaction_line_of_business_coverage` | `950.75\|2000.25\|157.50`            | Dollar amounts, same order as LOB list         |
| `non_admitted_insurer_code_list`        | `39381\|AA-1120841\|12833`           | Use for single and multiple carriers           |
| `non_admitted_insurer_code_coverage`    | `50\|30\|20`                         | Percentages, must sum to 100                   |
| `syndicate_list`                        | `AA-1120131\|AA-1120124`             | Lloyd's syndicates                             |
| `syndicate_list_coverage`               | `60\|40`                             | Percentages, must sum to 100                   |
| `dc_naic`                               | `54267\|37816\|49865`                | Declining carrier NAIC codes                   |
| `dc_date_declined`                      | `2017-02-02\|2017-02-03\|2017-02-04` | Decline dates, same order as `dc_naic`         |
| `dc_declining_reason`                   | `Underwriting reason\|Other\|Other`  | Decline reasons, state-specific allowed values |
| `dc_representative_name`                | `John Doe\|Jane Smith\|...`          | Carrier rep names                              |
| `dc_representative_email`               | `a@demo.com\|b@demo.com\|...`        | Carrier rep emails                             |
| `dc_representative_phone_number`        | `555-0100\|555-0101\|...`            | Carrier rep phone numbers                      |

***

### How to Use This Request

<ScalarApiRef specUrl="/openapi/transaction-import-batch.yaml" minHeight="80vh" expandResponse />


import { ScalarApiRef } from '../../../components/ScalarApiRef'

## Transaction Import — Import Status <span className="method-get">GET</span>

After a batch has been submitted via the <a href="/api/transaction-import/batch">Batch Import</a> endpoint, use this endpoint to retrieve the processing result for each transaction — including success, validation errors, and warnings.

* [Endpoint](#endpoint)
* [How to Use This Request](#how-to-use-this-request)

### Endpoint

| Environment    | URL                                                                    | Method |
| -------------- | ---------------------------------------------------------------------- | ------ |
| **Sandbox**    | `https://sandbox.inscipher.com/api/v4/transaction-import-results`      | GET    |
| **Production** | `https://surpluslines.inscipher.com/api/v4/transaction-import-results` | GET    |

:::warning
All API requests must be made over HTTPS and must include a valid API key in the `apikey` request header. See <a href="/getting-started/authentication">Authentication</a> for details.
:::

***

### How to Use This Request

<ScalarApiRef specUrl="/openapi/batch-import-status.yaml" minHeight="80vh" expandResponse moveResponsesRight={false} />


## Transaction Import — Overview

The Transaction Import API allows agencies to programmatically import transactional policy data and documents into the InsCipher portal. InsCipher provides two endpoints depending on your integration needs.

* <a href="/api/transaction-import/single">Single Import</a>
* <a href="/api/transaction-import/batch">Batch Import</a>

### Getting Started

1. Identify your use case:

|                              | <a href="/api/transaction-import/single">Single Import</a>        | <a href="/api/transaction-import/batch">Batch Import</a>   |
| ---------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- |
| **Transactions per request** | 1                                                                 | Multiple                                                   |
| **Response**                 | Synchronous — immediate result                                    | Asynchronous — queue-based                                 |
| **Result retrieval**         | Included in the response body                                     | Via webhook callback or GET request                        |
| **Batch ID**                 | Shared daily — one batch ID covers all calls made until 08:03 UTC | Per-request — a new batch ID is returned with each request |
| **Use when**                 | Real-time integrations, low volume, immediate feedback needed     | Daily batch jobs, high volume, async processing acceptable |

2. Choose your Mapping Packet

:::warning
InsCipher uses data tables outside of this documentation for every request to provide the most up-to-date filing requirements. Depending on your configuration, you may need to reference the mapping packets below.
:::

* [**Filing Services® clients**](https://lookerstudio.google.com/u/0/reporting/0b499657-4b92-4336-9bb3-c3650692bcf9/page/p_hu3dx3gjqc)

* [**Connect® clients**](https://lookerstudio.google.com/u/0/reporting/41dce747-d045-4e1f-884d-07d23581a90a/page/p_83noca0k9c)

3. Review the key variables

| Variable                  | Notes                                                                                     |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| **Transaction Types**     | Map your company policy types to InsCipher transaction codes                              |
| **Insurance Companies**   | Generally use the carrier's NAIC code                                                     |
| **Lines of Business**     | Use InsCipher Generic LOB Import Codes (recommended)                                      |
| **Description of Risk**   | A few states require specific coded values — use state-specific codes                     |
| **Fee Types**             | Map taxable fees to either `agency_fee` (broker/agency) or `inspection_fee` (carrier)     |
| **Document Requirements** | Map your policy documents to InsCipher document import codes                              |
| **Tax Titles**            | Map tax payable codes to state-specific fields (`sl_tax`, `stamping_fee`, `fm_tax`, etc.) |

### FAQs

<details>
  <summary>What is the difference between Broker Fees and Carrier Fees?</summary>

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

  **Broker Fees** (`agency_fee`) — Agency, policy, broker, filing, or other fees charged by or retained by the broker that are not mandated by the carrier.

  **Carrier Fees** (`inspection_fee`) — Inspection, audit, underwriting, or other fees charged or mandated by the carrier and retained by the carrier.

  Map your fees to the correct bucket so that InsCipher can accurately determine SL Tax calculations.
</details>

<details>
  <summary>How do state tax and fee field names work?</summary>

  InsCipher uses the following default field names for state taxes and fees:

  | Field               | Default Label                |
  | ------------------- | ---------------------------- |
  | `sl_tax`            | Surplus Lines Tax            |
  | `stamping_fee`      | Stamping Fee                 |
  | `sl_service_charge` | Surplus Lines Service Charge |
  | `fm_tax`            | Fire Marshal Tax             |
  | `empa_tax`          | EMPA Tax                     |
  | `municipal_fee`     | Municipal Tax                |

  In some states, InsCipher repurposes these field names for state-specific fees. Refer to the [Unique State Tax Titles](https://lookerstudio.google.com/u/0/reporting/0b499657-4b92-4336-9bb3-c3650692bcf9/page/p_xv4ud8gjqc) table for definitions.
</details>

<details>
  <summary>How do Generic Lines of Business Import Codes work?</summary>

  InsCipher maintains active coverage code lists by state. Use Generic Import Codes (`GEN-XXXX`) from the [Generic LOB List](https://docs.google.com/spreadsheets/d/1AvhAXYExgeRJ3nMw5NAzugDgl4_UhsvDyzv4MVBhSjE/edit?gid=0#gid=0) — the system automatically maps them to the correct state-specific line of business on import.

  :::warning
  It is your responsibility to review the mapping and ensure all needed codes are covered. InsCipher can add codes during implementation — submit all requested changes in a single email. Changes requested after implementation may be subject to an hourly rate.
  :::
</details>

<details>
  <summary>Can I import documents separately from transactions?</summary>

  Yes. After transactions have been imported successfully, documents can be added in a separate step using your internal invoice number or the InsCipher Transaction ID. See the <a href="/api/document-import">Document Import</a> guide for details.
</details>


import { ScalarApiRef } from '../../../components/ScalarApiRef'
import { VersionSwitcher, When } from '../../../components/VersionedPage'

## Transaction Import — Single <span className="method-post">POST</span>

The Single Import endpoint allows agencies to import one policy transaction per request and receive an immediate, synchronous response. Use this endpoint for real-time integrations where instant feedback is required.

* [Endpoint](#endpoint)
* [How It Works](#how-it-works)
* [LOB and Carrier Format](#lob-and-carrier-format)
* [How to Use This Request](#how-to-use-this-request)

<VersionSwitcher versions={['v2', 'v1']} />

### Endpoint

:::warning
All API requests must be made over HTTPS and must include a valid API key in the `apikey` request header. See <a href="/getting-started/authentication">Authentication</a> for details.
:::

<When v="v2">
  | Environment | URL                                                            | Method |
  | ----------- | -------------------------------------------------------------- | ------ |
  | Sandbox     | `https://sandbox.inscipher.com/api/v2/single/transaction`      | POST   |
  | Production  | `https://surpluslines.inscipher.com/api/v2/single/transaction` | POST   |

  The request body is sent as a plain JSON object — no wrapper key required.
</When>

<When v="v1">
  | Environment | URL                                                            | Method |
  | ----------- | -------------------------------------------------------------- | ------ |
  | Sandbox     | `https://sandbox.inscipher.com/api/v1/single/transaction`      | POST   |
  | Production  | `https://surpluslines.inscipher.com/api/v1/single/transaction` | POST   |

  The request body requires three envelope fields alongside `transaction`: `batch_id` (a unique UUID per request), `current_item` (always `1` for single-transaction imports), and `total_items` (always `1` for single-transaction imports).
</When>

### How It Works

#### Submitting a Transaction

The Single Import endpoint accepts one transaction per request. The response is returned synchronously — results are available immediately in the response body without any polling or webhook setup.

#### Batch ID Behavior

<When v="v2">
  Unlike the Batch endpoint (which issues a new `batch_id` with every request), the Single endpoint uses a **shared daily batch ID**. All Single Import calls submitted on the same calendar day are grouped under the same `batch_id`, which resets at 08:03 UTC.
</When>

<When v="v1">
  You must supply a unique `batch_id` in every v1 request. Once a `batch_id` has been associated with a completed import, it cannot be reused — the server returns HTTP 400 if you attempt to reuse one. A UUID is recommended (e.g., `crypto.randomUUID()` or Postman's `{{$guid}}`).
</When>

### LOB and Carrier Format

The Single endpoint uses **arrays of objects** for lines of business, carriers, and declining carriers — unlike the Batch endpoint which uses pipe-delimited strings.

<When v="v2">
  | Field                    | Format                                                                            | `coverage` unit    |
  | ------------------------ | --------------------------------------------------------------------------------- | ------------------ |
  | `line_of_business_list`  | `[{"item": "GEN-1001", "coverage": 3108.50}]`                                     | Dollar amount      |
  | `insurance_company_list` | `[{"item": "24856", "coverage": 100}]`                                            | Percentage (0–100) |
  | `syndicate_list`         | `[{"item": "AA-1126033", "coverage": 100}]`                                       | Percentage (0–100) |
  | `declining_carriers`     | `[{"naic": "54267", "date_declined": "2017-02-02", "declining_reason": "other"}]` | —                  |
</When>

<When v="v1">
  | Field                    | Format                                                                            | `coverage` unit |
  | ------------------------ | --------------------------------------------------------------------------------- | --------------- |
  | `line_of_business_list`  | `[{"item": "GEN-1001", "coverage": 3108.50}]`                                     | Dollar amount   |
  | `insurance_company_list` | `[{"item": "24856"}]`                                                             | —               |
  | `syndicate_list`         | `[{"item": "AA-1126033"}]`                                                        | —               |
  | `declining_carriers`     | `[{"naic": "54267", "date_declined": "2017-02-02", "declining_reason": "other"}]` | —               |

  The `coverage` field on `insurance_company_list` and `syndicate_list` is not supported in v1.
</When>

### How to Use This Request

<When v="v2">
  <ScalarApiRef specUrl="/openapi/transaction-import.yaml" minHeight="80vh" expandResponse />
</When>

<When v="v1">
  <ScalarApiRef specUrl="/openapi/transaction-import-v1.yaml" minHeight="80vh" expandResponse />
</When>