> ## 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 Agency API call in order, from finding your entity'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 Agency API calls in order and says which value to keep from each.

## The calls at a glance

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

## Before you start

* **Three product features.** Surplus-Lines Filing for the filing and state endpoints, Settings Org Structure for the entity list, and Settings Documents for uploading files. A missing one returns **403** with `errorType` `product_feature_subscription_required`. The carrier list needs API access only. The [full table](https://docs.turrisfi.com/guides/downstream-getting-started.md) is in Getting Started.
* **Mint the credential at your top company if you file for branches.** A credential sees its own entity and every branch beneath it, never anything above or beside it. See [The Agency API](https://docs.turrisfi.com/guides/agency-api.md).
* **There are no agency webhooks.** You follow a filing by polling (step 10).
* **Writes allow 30 requests per 60 seconds per route, counted per organization.** Reads allow 120. A burst of uploads past that gets **429**. See [Rate Limiting](https://docs.turrisfi.com/guides/rate-limiting.md).
* **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.

**2. Find your entity's downstreamEntityId**

Open Filing takes `downstreamEntityId`: the entity the policy belongs to, which is your own entity or one of its branches.

```bash theme={null}
curl "$TURRIS_API/v2/downstream/entities" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "items": [
      {
        "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
        "legalName": "Example Agency LLC",
        "isTopCompany": true
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  }
}
```

**Keep `downstreamEntityId`** of the row the policy is for. To file for a branch, use the branch's row. An entity outside your credential's scope returns **400** from Open Filing.

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

```bash theme={null}
curl "$TURRIS_API/v2/downstream/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/downstream/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/downstream/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/downstream/surplus-lines-states/get-tax-and-fees.md): the rates and what the taxable base includes.

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/downstream/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/downstream/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.

**Keep `data.filingId`.** 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. The filing belongs to the organization whose credential opened it, whichever entity `downstreamEntityId` names.

> [!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 your entity or one of its branches, 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 entity, 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/downstream/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. Use a new idempotency key for every file. **Keep `data.fileDocumentId`**, the file id.

Then set it on the filing:

```bash theme={null}
curl -X PUT "$TURRIS_API/v2/downstream/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. The file must be a Surplus Lines upload from your entity or a branch beneath it that is not on any filing yet; anything else returns **404**.

**7. Read the checklist**

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

```json theme={null}
{
  "data": {
    "filingId": "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. Categories Turris keeps internal are not in the response.

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/downstream/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: if any file is already on a filing, the whole call returns **404** and nothing is attached, 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/downstream-surplus-lines-files.md) covers uploads and downloads in more detail.

**9. Follow progress**

Poll [List Surplus-Lines Filings](https://docs.turrisfi.com/api-reference/v2/downstream/surplus-lines-filings/list-filings.md). It is paginated, newest first, with `page` and `limit` (up to 100 per page), and filters by `externalReference`, `policyNumber`, `status`, `stateCode` and `downstreamEntityId`. Each row has `status`, `actionRequired` and `updatedAt`; read the filing when `updatedAt` moves.

The list holds the filings your organization opened. A filing a carrier opened on your behalf belongs to that carrier and is not returned.

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/downstream/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 entity are fixed for the API.
* **Cancel or delete a filing.**
* **Set `status` or check off a checklist item.** Turris does both.
* **Show a filing a carrier opened for you.** Only the carrier sees it through the API.

To correct or cancel a filing, email [support@turrisfi.com](mailto:support@turrisfi.com) with its `filingId`. 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/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.