Skip to main content
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.
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, List Filings is paginated, and there are no webhooks, so you poll. The Agency API version of this walkthrough has every call.

The calls at a glance

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 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 and send a test event, but it cannot register one. Without a webhook, poll instead (step 10).
  • Build against the sandbox first. The examples below use it:
1

Get a token

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

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: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

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 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.
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.
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.
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.
6

Upload the policy and set it as the policy document

Two calls. First upload the file:
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:
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

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:
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 covers uploads and downloads in more detail.
9

Follow progress

With webhooks, two events cover a filing:Both payloads carry filingId and your externalReference. Read the filing for the detail.Without webhooks, poll List Surplus-Lines Filings. 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.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.
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 with its _id. Do not open a corrected copy instead: the original stays open with Turris until someone closes it.