Open a surplus-lines filing
curl --request POST \
--url https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
"stateCode": "CA",
"policyNumber": "POL-2026-001",
"policyTransactionType": "bind",
"namedInsured": "Example Corp",
"carrier": "Example Mutual Insurance Company",
"bindDate": "2026-01-01",
"effectiveDate": "2026-01-01",
"expirationDate": "2027-01-01",
"grossPremium": 25000,
"endorsementNumber": 1,
"riskAddress": "123 Main St, San Francisco, CA",
"carrierNaicCode": "12345",
"carrierId": "6610b3d2c2e0a51b8c0d1f09",
"nonTaxablePremium": 0,
"brokerFee": 0,
"otherTaxableFees": 0,
"externalReference": "REF-2026-0001"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
downstreamEntityId: '6610b3d2c2e0a51b8c0d1f02',
stateCode: 'CA',
policyNumber: 'POL-2026-001',
policyTransactionType: 'bind',
namedInsured: 'Example Corp',
carrier: 'Example Mutual Insurance Company',
bindDate: '2026-01-01',
effectiveDate: '2026-01-01',
expirationDate: '2027-01-01',
grossPremium: 25000,
endorsementNumber: 1,
riskAddress: '123 Main St, San Francisco, CA',
carrierNaicCode: '12345',
carrierId: '6610b3d2c2e0a51b8c0d1f09',
nonTaxablePremium: 0,
brokerFee: 0,
otherTaxableFees: 0,
externalReference: 'REF-2026-0001'
})
};
fetch('https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings"
payload = {
"downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
"stateCode": "CA",
"policyNumber": "POL-2026-001",
"policyTransactionType": "bind",
"namedInsured": "Example Corp",
"carrier": "Example Mutual Insurance Company",
"bindDate": "2026-01-01",
"effectiveDate": "2026-01-01",
"expirationDate": "2027-01-01",
"grossPremium": 25000,
"endorsementNumber": 1,
"riskAddress": "123 Main St, San Francisco, CA",
"carrierNaicCode": "12345",
"carrierId": "6610b3d2c2e0a51b8c0d1f09",
"nonTaxablePremium": 0,
"brokerFee": 0,
"otherTaxableFees": 0,
"externalReference": "REF-2026-0001"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"_id": "6650a1b2c3d4e5f6a7b8c9d0",
"policyNumber": "POL-2025-001",
"stateCode": "CA",
"policyTransactionType": "bind",
"status": "in progress",
"actionRequired": true,
"updatedAt": "2025-06-15T12:00:00.000Z",
"namedInsured": "Example Corp",
"carrier": "Lloyds of London",
"carrierNaicCode": "12345",
"grossPremium": 5000,
"escalations": [
{
"checklistItemLabel": "<string>",
"status": "waiting customer input",
"messages": [
{
"authorLabel": "Turris",
"body": "<string>",
"createdAt": "2025-06-01T12:00:00.000Z"
}
],
"openedAt": "<string>",
"resolvedAt": "<string>"
}
],
"completionArtifacts": [
{
"type": "accepted stamped",
"fileName": "stamped-filing.pdf",
"uploadedAt": "2025-06-15T09:00:00.000Z",
"downloadUrl": "<string>",
"viewUrl": "<string>"
}
],
"checklist": [
{
"sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Documents we need from you",
"tone": "primary",
"order": 0,
"items": [
{
"sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
"sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
"label": "Signed diligent search affidavit",
"required": true,
"order": 0,
"checked": false,
"referenceFields": [
{
"label": "Policy limit",
"value": "<string>"
}
],
"templateFiles": [
{
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"fileName": "diligent-search-form.pdf",
"mimeType": "application/pdf",
"fileSize": 248310,
"description": "<string>",
"downloadUrl": "<string>",
"viewUrl": "<string>"
}
],
"attachments": [
{
"_id": "6650a1b2c3d4e5f6a7b8c9d0",
"fileName": "signed-form.pdf",
"uploadedByType": "customer",
"uploadedAt": "2026-06-01T12:00:00.000Z",
"authorLabel": "Turris",
"downloadUrl": "<string>",
"viewUrl": "<string>"
}
],
"checkedAt": "2026-06-01T12:00:00.000Z",
"escalation": {
"checklistItemLabel": "<string>",
"status": "waiting customer input",
"messages": [
{
"authorLabel": "Turris",
"body": "<string>",
"createdAt": "2025-06-01T12:00:00.000Z"
}
],
"openedAt": "<string>",
"resolvedAt": "<string>"
}
}
]
}
],
"checklistProgress": {
"checked": 3,
"total": 5
},
"externalReference": "EXT-REF-12345",
"effectiveDate": "2025-01-01T00:00:00.000Z",
"totalTaxDue": 123,
"policyDocument": {
"fileName": "policy-12345.pdf",
"uploadedByType": "customer",
"uploadedAt": "2025-06-15T09:00:00.000Z",
"downloadUrl": "<string>",
"viewUrl": "<string>"
}
},
"requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
"timestamp": "2025-11-12T20:49:03.293Z"
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}Surplus Lines Filings
Open a Surplus-Lines Filing
Start a filing for one of your associated agencies
POST
/
v2
/
upstream
/
surplus-lines-filings
Open a surplus-lines filing
curl --request POST \
--url https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
"stateCode": "CA",
"policyNumber": "POL-2026-001",
"policyTransactionType": "bind",
"namedInsured": "Example Corp",
"carrier": "Example Mutual Insurance Company",
"bindDate": "2026-01-01",
"effectiveDate": "2026-01-01",
"expirationDate": "2027-01-01",
"grossPremium": 25000,
"endorsementNumber": 1,
"riskAddress": "123 Main St, San Francisco, CA",
"carrierNaicCode": "12345",
"carrierId": "6610b3d2c2e0a51b8c0d1f09",
"nonTaxablePremium": 0,
"brokerFee": 0,
"otherTaxableFees": 0,
"externalReference": "REF-2026-0001"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
downstreamEntityId: '6610b3d2c2e0a51b8c0d1f02',
stateCode: 'CA',
policyNumber: 'POL-2026-001',
policyTransactionType: 'bind',
namedInsured: 'Example Corp',
carrier: 'Example Mutual Insurance Company',
bindDate: '2026-01-01',
effectiveDate: '2026-01-01',
expirationDate: '2027-01-01',
grossPremium: 25000,
endorsementNumber: 1,
riskAddress: '123 Main St, San Francisco, CA',
carrierNaicCode: '12345',
carrierId: '6610b3d2c2e0a51b8c0d1f09',
nonTaxablePremium: 0,
brokerFee: 0,
otherTaxableFees: 0,
externalReference: 'REF-2026-0001'
})
};
fetch('https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings"
payload = {
"downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
"stateCode": "CA",
"policyNumber": "POL-2026-001",
"policyTransactionType": "bind",
"namedInsured": "Example Corp",
"carrier": "Example Mutual Insurance Company",
"bindDate": "2026-01-01",
"effectiveDate": "2026-01-01",
"expirationDate": "2027-01-01",
"grossPremium": 25000,
"endorsementNumber": 1,
"riskAddress": "123 Main St, San Francisco, CA",
"carrierNaicCode": "12345",
"carrierId": "6610b3d2c2e0a51b8c0d1f09",
"nonTaxablePremium": 0,
"brokerFee": 0,
"otherTaxableFees": 0,
"externalReference": "REF-2026-0001"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"_id": "6650a1b2c3d4e5f6a7b8c9d0",
"policyNumber": "POL-2025-001",
"stateCode": "CA",
"policyTransactionType": "bind",
"status": "in progress",
"actionRequired": true,
"updatedAt": "2025-06-15T12:00:00.000Z",
"namedInsured": "Example Corp",
"carrier": "Lloyds of London",
"carrierNaicCode": "12345",
"grossPremium": 5000,
"escalations": [
{
"checklistItemLabel": "<string>",
"status": "waiting customer input",
"messages": [
{
"authorLabel": "Turris",
"body": "<string>",
"createdAt": "2025-06-01T12:00:00.000Z"
}
],
"openedAt": "<string>",
"resolvedAt": "<string>"
}
],
"completionArtifacts": [
{
"type": "accepted stamped",
"fileName": "stamped-filing.pdf",
"uploadedAt": "2025-06-15T09:00:00.000Z",
"downloadUrl": "<string>",
"viewUrl": "<string>"
}
],
"checklist": [
{
"sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Documents we need from you",
"tone": "primary",
"order": 0,
"items": [
{
"sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
"sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
"label": "Signed diligent search affidavit",
"required": true,
"order": 0,
"checked": false,
"referenceFields": [
{
"label": "Policy limit",
"value": "<string>"
}
],
"templateFiles": [
{
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"fileName": "diligent-search-form.pdf",
"mimeType": "application/pdf",
"fileSize": 248310,
"description": "<string>",
"downloadUrl": "<string>",
"viewUrl": "<string>"
}
],
"attachments": [
{
"_id": "6650a1b2c3d4e5f6a7b8c9d0",
"fileName": "signed-form.pdf",
"uploadedByType": "customer",
"uploadedAt": "2026-06-01T12:00:00.000Z",
"authorLabel": "Turris",
"downloadUrl": "<string>",
"viewUrl": "<string>"
}
],
"checkedAt": "2026-06-01T12:00:00.000Z",
"escalation": {
"checklistItemLabel": "<string>",
"status": "waiting customer input",
"messages": [
{
"authorLabel": "Turris",
"body": "<string>",
"createdAt": "2025-06-01T12:00:00.000Z"
}
],
"openedAt": "<string>",
"resolvedAt": "<string>"
}
}
]
}
],
"checklistProgress": {
"checked": 3,
"total": 5
},
"externalReference": "EXT-REF-12345",
"effectiveDate": "2025-01-01T00:00:00.000Z",
"totalTaxDue": 123,
"policyDocument": {
"fileName": "policy-12345.pdf",
"uploadedByType": "customer",
"uploadedAt": "2025-06-15T09:00:00.000Z",
"downloadUrl": "<string>",
"viewUrl": "<string>"
}
},
"requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
"timestamp": "2025-11-12T20:49:03.293Z"
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}{
"statusCode": 123,
"requestId": "<string>",
"errorType": "validation_error",
"errorMessage": [
"<string>"
],
"timestamp": "<string>",
"details": {}
}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.
What is decided for you
Status is always not started
Status is always not started
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.
The checklist and tax rates are snapshotted, not referenced
The checklist and tax rates are snapshotted, not referenced
Frozen at the moment the filing opens. Later template edits never reshape a filing that already exists.
brokerFee and otherTaxableFees can be filled in later
brokerFee and otherTaxableFees can be filled in later
Omit either one and it is treated as
0 for the initial tax calculation. Update the filing once you know the real number 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 theidempotency-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. Send anIdempotency-Key header. See Idempotency.Authorizations
bearerrestricted-access-token
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
UUID to ensure idempotent request processing
Example:
"550e8400-e29b-41d4-a716-446655440000"
Alternative UUID header for idempotent request processing
Example:
"550e8400-e29b-41d4-a716-446655440000"
Body
application/json
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"
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"
The policy number
Example:
"POL-2026-001"
What kind of policy transaction this filing records
Available options:
bind, endorsement, renewal, cancellation Example:
"bind"
The named insured on the policy
Example:
"Example Corp"
The carrier writing the policy
Example:
"Example Mutual Insurance Company"
Policy bind date, date-only (YYYY-MM-DD)
Example:
"2026-01-01"
Policy effective date, date-only (YYYY-MM-DD)
Example:
"2026-01-01"
Policy expiration date, date-only (YYYY-MM-DD)
Example:
"2027-01-01"
Gross premium, in dollars
Example:
25000
Required when policyTransactionType is endorsement (enforced server-side)
Example:
1
The risk address
Example:
"123 Main St, San Francisco, CA"
The carrier NAIC code
Example:
"12345"
Id of an approved carrier (see the List Carriers endpoint). When supplied, the service resolves it and overrides carrier / carrierNaicCode with the resolved name and NAIC code.
Example:
"6610b3d2c2e0a51b8c0d1f09"
Informational premium portion that is NOT taxed. Never enters the tax calculation.
Example:
0
The broker fee. Omit to let Turris fill it in later; the tax recomputes automatically.
Example:
0
Other taxable fees. Omit to let Turris fill it in later; the tax recomputes automatically.
Example:
0
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"
Was this page helpful?