Skip to main content
POST
Open a surplus-lines filing
Opens a filing from the live state template for the named agency and returns it with the checklist and tax detail Turris will work through. downstreamEntityId must name an agency your organization is associated with. An agency outside that set returns 400. carrierId is required and names the carrier writing the policy. Take it from List Carriers, Turris’s approved carrier list. A carrier Turris does not have returns 400, and so does a body that sends carrier or carrierNaicCode, which are no longer accepted. The filing’s carrier is returned as { _id, name, companyCode }, read from the carrier record.

What is decided for you

A filing is a workflow Turris runs. The statuses past the first are our operational vocabulary, not yours to declare, so the field is not accepted.
Frozen at the moment the filing opens. Later template edits never reshape a filing that already exists.
Omit either one and it is treated as 0 for the initial tax calculation. No endpoint changes a filing’s fees after it opens, so send them now if you know them. Turris fills in a fee you left out later and the tax recomputes automatically.

externalReference is a correlation id, not an idempotency key

Store your own reference on the filing and it is echoed back on every read. It does not deduplicate: sending the same value twice opens two filings. Use the idempotency-key header below for that.

One open filing per agency, state, policy number and transaction type

A second filing matching all four is refused with 409 while the first is still active. A soft-deleted filing does not block a new one.

States without a template

Turris maintains a filing template per state. A state we have not templated yet returns 404 naming the state. List Surplus Lines States returns every state you can open a filing in, and Get State Requirements what a filing there will ask for. Send an Idempotency-Key header. See Idempotency.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

idempotency-key
string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

x-idempotency-key
string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json
downstreamEntityId
string
required

Which of your eligible agencies the filing is for. For the carrier persona, any agency you are associated with. For the agency persona, your own entity or one of its child branches.

Example:

"6610b3d2c2e0a51b8c0d1f02"

stateCode
enum<string>
required

The state or territory to file in. Turris must have a surplus-lines template for it.

Available options:
AL,
AK,
AZ,
AR,
CA,
CO,
CT,
DE,
FL,
GA,
HI,
ID,
IL,
IN,
IA,
KS,
KY,
LA,
ME,
MD,
MA,
MI,
MN,
MS,
MO,
MT,
NE,
NV,
NH,
NJ,
NM,
NY,
NC,
ND,
OH,
OK,
OR,
PA,
RI,
SC,
SD,
TN,
TX,
UT,
VT,
VA,
WA,
WV,
WI,
WY,
GU,
PR,
VI,
DC
Example:

"CA"

policyNumber
string
required

The policy number

Example:

"POL-2026-001"

policyTransactionType
enum<string>
required

What kind of policy transaction this filing records

Available options:
bind,
endorsement,
renewal,
cancellation
Example:

"bind"

namedInsured
string
required

The named insured on the policy

Example:

"Example Corp"

carrierId
string
required

Id of the carrier writing the policy. Take it from the List Carriers endpoint, which both the Carrier & MGA API and the Agency API serve. A carrier id Turris does not have returns 400.

Example:

"6610b3d2c2e0a51b8c0d1f09"

bindDate
string
required

Policy bind date, date-only (YYYY-MM-DD)

Example:

"2026-01-01"

effectiveDate
string
required

Policy effective date, date-only (YYYY-MM-DD)

Example:

"2026-01-01"

expirationDate
string
required

Policy expiration date, date-only (YYYY-MM-DD)

Example:

"2027-01-01"

grossPremium
number
required

Gross premium, in dollars

Example:

25000

endorsementNumber
number

Required when policyTransactionType is endorsement (enforced server-side)

Example:

1

riskAddress
string

The risk address

Example:

"123 Main St, San Francisco, CA"

nonTaxablePremium
number

Informational premium portion that is NOT taxed. Never enters the tax calculation.

Example:

0

brokerFee
number

The broker fee. Omit to let Turris fill it in later; the tax recomputes automatically.

Example:

0

otherTaxableFees
number

Other taxable fees. Omit to let Turris fill it in later; the tax recomputes automatically.

Example:

0

externalReference
string

Your own reference for this filing, echoed back on every read. A correlation id, not an idempotency key: it does not deduplicate, so a retry with the same value opens a second filing.

Example:

"REF-2026-0001"

Response

The newly-created filing

data
object
required
requestId
string
required

Unique request identifier

Example:

"dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8"

timestamp
string
required

Response timestamp

Example:

"2025-11-12T20:49:03.293Z"