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 Agency API calls in order and says which value to keep from each.

The calls at a glance

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

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: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.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.
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. Use a new idempotency key for every file. Keep data.fileDocumentId, 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. 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

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

Follow progress

Poll List Surplus-Lines Filings. 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.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 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 with its filingId. Do not open a corrected copy instead: the original stays open with Turris until someone closes it.