Surplus Lines Filing

cURL

curl --request GET \
  --url https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings/{filingId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings/{filingId}', 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/{filingId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, 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",
        "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
        "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",
                "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
                "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": {
      "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
      "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": {}
}

GET

upstream

surplus-lines-filings

{filingId}

cURL

curl --request GET \
  --url https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings/{filingId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings/{filingId}', 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/{filingId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, 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",
        "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
        "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",
                "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
                "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": {
      "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
      "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": {}
}

Returns a single surplus lines filing by its unique identifier: its checklist, with each item’s ids, files and escalation, the policy document, and any completion artifacts (accepted/stamped filing, receipt, confirmation, tax/remittance proof). Every file comes with short-lived presigned download links. The filing must belong to the authenticated upstream entity. This is where the sourceCategoryId and sourceTaskId come from that Attach Uploaded Files to a Checklist Item and Reply to a Checklist Item Escalation take. See Files on a Surplus Lines Filing.

Path Parameters

Parameter	Type	Required	Description
`filingId`	string	Yes	Unique identifier of the filing (MongoDB ObjectId)

Response Shape

All successful responses are wrapped in the standard response envelope. See Request/Response Conventions.

{
  "data": {
    "_id": "6650a1b2c3d4e5f6a7b8c9d0",
    "externalReference": "UNION-12345",
    "policyNumber": "POL-2025-001",
    "stateCode": "CA",
    "policyTransactionType": "bind",
    "status": "filed",
    "actionRequired": true,
    "effectiveDate": "2025-01-15T00:00:00.000Z",
    "updatedAt": "2025-01-16T10:31:45.000Z",
    "namedInsured": "Example Corp",
    "carrier": "Lloyd's of London",
    "carrierNaicCode": "12345",
    "grossPremium": 10000,
    "totalTaxDue": 494,
    "policyDocument": {
      "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9e1",
      "fileName": "policy-POL-2025-001.pdf",
      "uploadedByType": "customer",
      "uploadedAt": "2025-01-15T12:00:00.000Z",
      "downloadUrl": "https://s3.amazonaws.com/...&X-Amz-Expires=3600",
      "viewUrl": "https://s3.amazonaws.com/...&response-content-disposition=inline"
    },
    "checklist": [
      {
        "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9a0",
        "name": "Diligent effort",
        "tone": "primary",
        "order": 1,
        "items": [
          {
            "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9a0",
            "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9a1",
            "label": "Provide signed D-1 diligence form",
            "required": true,
            "order": 1,
            "checked": false,
            "checkedAt": null,
            "referenceFields": [],
            "templateFiles": [],
            "attachments": [],
            "escalation": {
              "checklistItemLabel": "Provide signed D-1 diligence form",
              "status": "waiting customer input",
              "openedAt": "2025-01-16T09:00:00.000Z",
              "resolvedAt": null,
              "messages": [
                {
                  "authorLabel": "Turris",
                  "body": "Please upload the signed D-1 form so we can complete the filing.",
                  "createdAt": "2025-01-16T09:00:00.000Z"
                }
              ]
            }
          }
        ]
      }
    ],
    "checklistProgress": { "checked": 0, "total": 1 },
    "escalations": [
      {
        "checklistItemLabel": "Provide signed D-1 diligence form",
        "status": "waiting customer input",
        "openedAt": "2025-01-16T09:00:00.000Z",
        "resolvedAt": null,
        "messages": [
          {
            "authorLabel": "Turris",
            "body": "Please upload the signed D-1 form so we can complete the filing.",
            "createdAt": "2025-01-16T09:00:00.000Z"
          }
        ]
      }
    ],
    "completionArtifacts": [
      {
        "type": "accepted stamped",
        "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9f2",
        "fileName": "CA-SL-2-stamped.pdf",
        "uploadedAt": "2025-01-16T10:31:00.000Z",
        "downloadUrl": "https://s3.amazonaws.com/...&X-Amz-Expires=3600",
        "viewUrl": "https://s3.amazonaws.com/...&response-content-disposition=inline"
      }
    ]
  },
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-01-16T10:31:50.000Z"
}

Response Fields

The filing carries the same summary fields as each item in List Surplus Lines Filings, plus the detail fields below.

Field	Type	Description
`namedInsured`	string	Name of the insured party
`carrier`	string	Insurance carrier name
`carrierNaicCode`	string	NAIC code of the carrier
`grossPremium`	number	Gross written premium
`totalTaxDue`	number?	Total surplus lines tax due, if a tax calculation exists (null otherwise)
`policyDocument`	object?	The filing’s policy document (see below), or null if none has been set
`checklist`	array	The checklist you can see, grouped into categories (see below). Categories Turris keeps internal are never included
`checklistProgress`	object	`checked` and `total`, counted over the visible checklist items only
`escalations`	array	Open and resolved escalations on public checklist items (see below). The same threads also sit on each checklist item
`completionArtifacts`	array	Completion documents as presigned links (see below)

Checklist category object

Field	Type	Description
`sourceCategoryId`	string	Id of the category
`name`	string	Category name
`tone`	string	Display tone: `primary`, `secondary`, `neutral`, `green`, `red` or `yellow`
`order`	number	Display order within the checklist
`items`	array	The category’s checklist items (see below)

Checklist item object

Field	Type	Description
`sourceCategoryId`	string	Id of the item’s category, repeated here so `checklist.flatMap((category) => category.items)` keeps it
`sourceTaskId`	string	Id of the item. Together with `sourceCategoryId` it identifies the item within this filing only: both come from the state template, so they repeat across filings in the same state
`label`	string	What the item asks for
`required`	boolean	True when the filing cannot complete without this item
`order`	number	Display order within its category
`checked`	boolean	True once Turris has satisfied the item
`checkedAt`	string?	ISO 8601 timestamp when the item was checked off (null while outstanding)
`referenceFields`	array	Reference values captured against the item
`templateFiles`	array	Blank forms supplied for the item, each with `downloadUrl` and `viewUrl`
`attachments`	array	Files attached to the item, each with `fileDocumentId`, `fileName`, `uploadedByType`, `uploadedAt`, `authorLabel`, `downloadUrl` and `viewUrl`. Files sent with an escalation reply land here too
`escalation`	object?	The escalation on this item (same shape as below), or null if none was raised. To find the item Turris is waiting on, look for `escalation.status` of `waiting customer input`

Policy document object

Field	Type	Description
`fileDocumentId`	string	Document id, for Get a Download URL for a Document
`fileName`	string	Original file name
`uploadedByType`	string	`admin` or `customer`
`uploadedAt`	string	ISO 8601 timestamp when it was set
`downloadUrl`	string	Presigned download link (expires in ~1 hour)
`viewUrl`	string	Presigned inline-view link (expires in ~1 hour)

Escalation object

Field	Type	Description
`checklistItemLabel`	string	The checklist item the escalation is attached to
`status`	string	`waiting turris input`, `waiting customer input`, or `resolved`
`openedAt`	string?	ISO 8601 timestamp when the escalation was opened
`resolvedAt`	string?	ISO 8601 timestamp when it was resolved (null if open)
`messages`	array	Thread of messages, each with `authorLabel` (`Turris` or your agency), `body`, and `createdAt`

Completion artifact object

Field	Type	Description
`type`	string	`accepted stamped`, `receipt`, `confirmation`, or `tax remittance proof`
`fileDocumentId`	string	Document id, for Get a Download URL for a Document
`fileName`	string	Original file name
`uploadedAt`	string	ISO 8601 timestamp when the artifact was attached
`downloadUrl`	string	Presigned download link (attachment; expires in ~1 hour)
`viewUrl`	string	Presigned inline-view link (expires in ~1 hour)

downloadUrl and viewUrl are short-lived presigned links. Fetch them fresh from this endpoint when you need a file rather than storing the URL.

Error Scenarios

Bad Request (400)

Returned when filingId is not a valid MongoDB ObjectId format.

{
  "statusCode": 400,
  "errorType": "validation_error",
  "errorMessage": ["filingId must be a mongodb id"],
  "requestId": "dev-abc123",
  "timestamp": "2025-01-16T10:30:00.000Z"
}

Filing Not Found (404)

Returned when filingId doesn’t exist or belongs to a different upstream entity.

{
  "statusCode": 404,
  "errorType": "not_found",
  "errorMessage": ["Surplus-lines filing not found"],
  "requestId": "dev-abc123",
  "timestamp": "2025-01-16T10:30:00.000Z"
}

Unauthorized (401)

Missing or invalid authentication token. See Authentication.

Authorizations

Authorization

string

header

required

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

Path Parameters

filingId

string

required

Unique identifier of the surplus-lines filing

Example:

"6650a1b2c3d4e5f6a7b8c9d0"

Response

Surplus-lines filing detail with escalations and completion artifacts

data

object

required

Show child attributes

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"

Start Here

Shared Endpoints

Products

Carriers

Agencies You Appoint

Contract Container Templates

Agents

Contacts

Market Contacts

Licenses

Appointments

Compliance Data Subscriptions

Compliance Status

File Documents

Policy Ingestion

Policy Transactions