> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Open a Surplus Lines Filing from Start to Finish

> Every call in order, from finding the agency's id to a completed filing, and which id each call hands to the next

Opening a filing is one call. Getting it to `completed` takes several more, and most of them need an id that an earlier call returned. This page lists the calls in order and says which value to keep from each.

> [!NOTE]
>
> **On the Agency API** the same sequence runs on `/v2/downstream/surplus-lines-filings`, with a few differences: `downstreamEntityId` is your own entity or one of your branches, the carrier list is [`GET /v2/downstream/carriers`](https://docs.turrisfi.com/api-reference/v2/downstream/carriers/list-carriers), List Filings is paginated, and there are no webhooks, so you poll. The [Agency API version of this walkthrough](https://docs.turrisfi.com/guides/downstream-surplus-lines-filing-walkthrough.md) has every call.

## The calls at a glance

| # | Call | Endpoint | Keep from the response |
| - | - | - | - |
| 1 | Get a token | `POST /v2/auth/jwt` | `data.accessToken` |
| 2 | Find the agency | `GET /v2/upstream/downstream-entity-associations` | `data[].downstreamEntity._id` |
| 3 | Check the state | `GET /v2/upstream/surplus-lines-states` | that your `stateCode` is listed |
| 4 | Find the carrier | `GET /v2/upstream/carriers` | `data.items[]._id` |
| 5 | Open the filing | `POST /v2/upstream/surplus-lines-filings` | `data._id`, the filing id |
| 6 | Upload a file | `POST /v2/upstream/file-documents` | `data._id`, the file id |
| 7 | Set the policy document | `PUT /v2/upstream/surplus-lines-filings/{filingId}/policy-document` | |
| 8 | Read the checklist | `GET /v2/upstream/surplus-lines-filings/{filingId}` | `sourceCategoryId` and `sourceTaskId` of each item |
| 9 | Attach files to an item | `POST /v2/upstream/surplus-lines-filings/{filingId}/checklist-item/file-documents` | |
| 10 | Follow progress | Webhooks, or `GET /v2/upstream/surplus-lines-filings` | `status`, `actionRequired` |
| 11 | Answer an escalation | `POST /v2/upstream/surplus-lines-filings/{filingId}/escalation/messages` | |

## Before you start

* **Three product features.** Surplus-Lines Filing for the filing and state endpoints, Downstream Entity for the agency lookup, and Tools for uploading files. A missing one returns **403** with `errorType` `product_feature_subscription_required`. The [full table](https://docs.turrisfi.com/guides/getting-started.md#what-your-credentials-can-reach) is in Getting Started.
* **Webhooks are registered in the Turris web app.** Open **Settings > Webhooks**, add your URL and select the two surplus lines filing events, status change and action required. The API can [list your webhooks](https://docs.turrisfi.com/api-reference/v2/webhooks/list-webhooks.md) and [send a test event](https://docs.turrisfi.com/api-reference/v2/webhooks/test-webhook.md), but it cannot register one. Without a webhook, poll instead (step 10).
* **Build against the sandbox first.** The examples below use it:

```bash theme={null}
export TURRIS_API="https://public.api.sandbox.turrisfi.com"
```

**1. Get a token**

```bash theme={null}
curl -X POST "$TURRIS_API/v2/auth/jwt" \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "your-client-id", "clientSecret": "your-client-secret" }'
```

Send `data.accessToken` as `Authorization: Bearer ...` on every call below; the examples hold it in `$TOKEN`. It is valid for 60 minutes. **Cache it.** The token endpoint allows four requests per window, so a client that fetches a token per call starts getting **429** almost at once. See [Rate Limiting](https://docs.turrisfi.com/guides/rate-limiting.md).

**2. Find the agency's downstreamEntityId**

Open Filing takes `downstreamEntityId`, the agency's own id. Most other carrier endpoints take `downstreamEntityAssociationId`, the id of your relationship with the agency. **They are different ids**, and sending the association id to Open Filing returns **400**.

```bash theme={null}
curl "$TURRIS_API/v2/upstream/downstream-entity-associations?downstreamEntityNpn=1234567" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": [
    {
      "_id": "6610b3d2c2e0a51b8c0d1f01",
      "downstreamEntity": {
        "_id": "6610b3d2c2e0a51b8c0d1f02",
        "legalName": "Example Agency LLC",
        "npn": "1234567"
      }
    }
  ]
}
```

Keep `downstreamEntity._id`, not the top-level `_id`. A branch of an agency is its own association with its own `downstreamEntity._id`, so filing for a branch means using the branch's row.

[List Associations](https://docs.turrisfi.com/api-reference/v2/downstream-entity-associations/list-associations.md) also filters by `licenseNumber` with `stateCode`, by `emailDomain` or by `email`. Leave the filter off to get every agency you are associated with.

**3. Check that Turris files in the state**

```bash theme={null}
curl "$TURRIS_API/v2/upstream/surplus-lines-states?limit=100" \
  -H "Authorization: Bearer $TOKEN"
```

`data.items` lists every state you can open a filing in, by `stateCode`, and `limit=100` returns them all in one call. A state that is not listed has no Turris template yet, and Open Filing returns **404** for it.

To see what a filing will ask for before you open one:

* [Get State Requirements](https://docs.turrisfi.com/api-reference/v2/surplus-lines-states/get-requirements.md): the filing deadline and the documents a filing needs, with the blank forms listed by id.
* [Get a Download URL for a State Template File](https://docs.turrisfi.com/api-reference/v2/surplus-lines-states/get-template-file-download-url.md): a link to one of those blank forms.
* [Get State Taxes and Fees](https://docs.turrisfi.com/api-reference/v2/surplus-lines-states/get-tax-and-fees.md): the rates and what the taxable base includes.

These state endpoints allow 120 requests per 60 seconds per organization. Each state carries `updatedAt`, so cache what you read and fetch a state again only when its `updatedAt` moves.

**4. Pick the carrier**

```bash theme={null}
curl "$TURRIS_API/v2/upstream/carriers?search=Example%20Mutual" \
  -H "Authorization: Bearer $TOKEN"
```

`search` matches the carrier name or NAIC code. **Keep the result's `_id`**: it is the required `carrierId` in the next step. The filing stores only that reference and every read returns the carrier as `carrier: { _id, name, companyCode }`, where `companyCode` is the NAIC code. A carrier that is not on this list cannot be filed against; ask [support@turrisfi.com](mailto:support@turrisfi.com) to add it.

**5. Open the filing**

Generate the idempotency key once per filing and keep it, so a retry can send the same one.

```bash theme={null}
FILING_KEY=$(uuidgen)

curl -X POST "$TURRIS_API/v2/upstream/surplus-lines-filings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $FILING_KEY" \
  -d '{
    "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
    "stateCode": "CA",
    "policyNumber": "POL-2026-001",
    "policyTransactionType": "bind",
    "namedInsured": "Example Corp",
    "carrierId": "6610b3d2c2e0a51b8c0d1f09",
    "bindDate": "2026-01-01",
    "effectiveDate": "2026-01-01",
    "expirationDate": "2027-01-01",
    "grossPremium": 25000,
    "brokerFee": 250,
    "otherTaxableFees": 0,
    "riskAddress": "123 Main St, San Francisco, CA",
    "externalReference": "REF-2026-0001"
  }'
```

`policyTransactionType` is `bind`, `endorsement`, `renewal` or `cancellation`; an `endorsement` also needs `endorsementNumber`. Dates are `YYYY-MM-DD`. `externalReference` is your own id for the filing and comes back on every read and in every webhook.

**Keep `data._id`.** It is the `filingId` in every call below, shown there as `$FILING_ID`. The new filing is always `not started`, and its checklist and tax rates are copied from the state at this moment: later changes to the state's requirements never reach it.

> [!WARNING]
>
> **Send `brokerFee` and `otherTaxableFees` now if you know them.** No endpoint changes a filing after it is opened. A fee you leave out counts as `0` in `totalTaxDue` until Turris updates it.

| Status | Cause | What to do |
| - | - | - |
| **400** | `downstreamEntityId` is not an agency you are associated with (most often the association id from step 2), an `endorsement` without `endorsementNumber`, a missing `carrierId` or one that is not on the carrier list, a `carrier` or `carrierNaicCode` field in the body, or an invalid body | Fix the request. `errorMessage` names the problem |
| **404** | Turris has no template for `stateCode` | Check the state list from step 3 |
| **409** | A filing for this agency, state, policy number and transaction type (and endorsement number, for an endorsement) already exists | Find it with List Filings and `policyNumber`, and carry on with that one |

A retry within an hour that sends the same `Idempotency-Key` gets the original response back, so a timeout is safe to retry. A retry with a new key gets **409**, because the filing already exists. See [Idempotency](https://docs.turrisfi.com/guides/idempotency.md).

**6. Upload the policy and set it as the policy document**

Two calls. First upload the file:

```bash theme={null}
curl -X POST "$TURRIS_API/v2/upstream/file-documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "category=Surplus Lines" \
  -F "file=@policy.pdf"
```

PDF, DOC, DOCX, JPEG or PNG, up to 10 MB. Leave `downstreamEntityAssociationId` out: on a Surplus Lines upload it returns **400**. Use a new idempotency key for every file. **Keep `data._id`**, the file id.

Then set it on the filing:

```bash theme={null}
curl -X PUT "$TURRIS_API/v2/upstream/surplus-lines-filings/$FILING_ID/policy-document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d2" }'
```

**Turris cannot start work until the policy document is set.** A filing without one stays `not started`. Setting it again replaces the previous one.

**7. Read the checklist**

```bash theme={null}
curl "$TURRIS_API/v2/upstream/surplus-lines-filings/$FILING_ID" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "_id": "6650a1b2c3d4e5f6a7b8c9d0",
    "status": "not started",
    "actionRequired": false,
    "carrier": { "_id": "6610b3d2c2e0a51b8c0d1f09", "name": "Example Mutual Insurance Company", "companyCode": "12345" },
    "checklistProgress": { "checked": 0, "total": 4 },
    "checklist": [
      {
        "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
        "name": "Documents",
        "items": [
          {
            "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
            "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
            "label": "Signed application",
            "required": true,
            "checked": false,
            "templateFiles": [
              { "id": "6650a1b2c3d4e5f6a7b8c9e1", "fileName": "application.pdf", "downloadUrl": "https://..." }
            ],
            "attachments": [],
            "escalation": null
          }
        ]
      }
    ]
  }
}
```

The items still open are the ones with `required: true` and `checked: false`. `checked` turns `true` when Turris has reviewed the item and is satisfied, not when you attach a file. `checklistProgress` counts checked items against the total.

An item with `templateFiles` comes with a blank form: download it from `downloadUrl`, fill it in, and upload it as in step 6. The links are short-lived, so read the filing again for fresh ones.

**Take the ids from this response, not from Get State Requirements.** `sourceTaskId` is the same on both, but the filing keeps the checklist as it was when it was opened, and the state can change after that. The `sourceCategoryId` and `sourceTaskId` pair is unique within one filing only, so key any cache by filing id as well.

**8. Attach files to checklist items**

Upload each file as in step 6, then attach it to its item:

```bash theme={null}
curl -X POST "$TURRIS_API/v2/upstream/surplus-lines-filings/$FILING_ID/checklist-item/file-documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
    "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
    "fileDocumentIds": ["6650a1b2c3d4e5f6a7b8c9d3"]
  }'
```

One to ten files per call, no duplicates. Each upload can be attached once: a file that is already on a filing returns **404**, so upload it again to use it twice. The response is the filing with the new attachments in place. [Files on a Surplus Lines Filing](https://docs.turrisfi.com/guides/surplus-lines-files.md) covers uploads and downloads in more detail.

**9. Follow progress**

**With webhooks**, two events cover a filing:

* [Surplus Lines Filing Status Change](https://docs.turrisfi.com/guides/webhooks/surplus-lines-filing-status-change.md) fires once when the filing is opened, with status `not started`, and again on every status change after that.
* [Surplus Lines Filing Action Required](https://docs.turrisfi.com/guides/webhooks/surplus-lines-filing-action-required.md) fires when Turris asks you something on a checklist item.

Both payloads carry `filingId` and your `externalReference`. Read the filing for the detail.

**Without webhooks**, poll [List Surplus-Lines Filings](https://docs.turrisfi.com/api-reference/v2/surplus-lines-filings/list-filings.md). It returns every filing in one array, not paged, and filters by `externalReference`, `policyNumber`, `status` and `stateCode`. Each row has `status` and `actionRequired`.

Only Turris changes `status`, and it can set any status after any other, so do not reject a transition you did not expect.

| `status` | What it means for you |
| - | - |
| `not started` | Turris has not begun. Check that the policy document is set |
| `in progress` | Turris is working through the checklist. Watch `actionRequired` |
| `ready to file` | Turris has what it needs to submit to the state |
| `filed` | Submitted to the state |
| `completed` | Done |
| `on hold` | Paused. Check `actionRequired`, and ask support if nothing is waiting on you |
| `canceled` | Closed without completing |

`completionArtifacts` on the filing lists the closing documents Turris attaches, such as a stamped acceptance or proof of tax remittance. It can be empty on a completed filing, so do not treat an empty list as an error.

**10. Answer an escalation**

When Turris needs something from you, it opens an escalation on a checklist item. The item's `escalation`, and the matching entry in the filing's `escalations`, has `status` `waiting customer input`, and the filing's `actionRequired` turns `true`. `messages` holds what Turris asked.

```bash theme={null}
curl -X POST "$TURRIS_API/v2/upstream/surplus-lines-filings/$FILING_ID/escalation/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
    "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
    "body": "Signed form attached.",
    "fileDocumentIds": ["6650a1b2c3d4e5f6a7b8c9d4"]
  }'
```

Send `body`, `fileDocumentIds` or both, as JSON. The escalation moves to `waiting turris input`. Only Turris resolves an escalation, and replying to a `resolved` one, or on an item with no escalation, returns **400**.

## What the API cannot do

* **Change a filing after it is opened.** Premium, fees, dates, policy number and agency are fixed for the API.
* **Cancel or delete a filing.**
* **Set `status` or check off a checklist item.** Turris does both.

To correct or cancel a filing, email [support@turrisfi.com](mailto:support@turrisfi.com) with its `_id`. Do not open a corrected copy instead: the original stays open with Turris until someone closes it.


## Related topics

- [Open a Surplus Lines Filing from Start to Finish](https://docs.turrisfi.com/guides/downstream-surplus-lines-filing-walkthrough.md)
- [Changelog](https://docs.turrisfi.com/changelog.md)
- [Open a Surplus-Lines Filing](https://docs.turrisfi.com/api-reference/v2/downstream/surplus-lines-filings/open-filing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.