Surplus Lines Filing

cURL

curl --request GET \
  --url https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings/{filingId}

const options = {method: 'GET'};

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));

{
  "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>"
      }
    ],
    "externalReference": "EXT-REF-12345",
    "effectiveDate": "2025-01-01T00:00:00.000Z",
    "totalTaxDue": 123
  },
  "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": {}
}

GET

upstream

surplus-lines-filings

{filingId}

cURL

curl --request GET \
  --url https://public.api.live.turrisfi.com/v2/upstream/surplus-lines-filings/{filingId}

const options = {method: 'GET'};

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));

{
  "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>"
      }
    ],
    "externalReference": "EXT-REF-12345",
    "effectiveDate": "2025-01-01T00:00:00.000Z",
    "totalTaxDue": 123
  },
  "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": {}
}

Returns a single surplus lines filing by its unique identifier, including its escalation / action-required state and notes, and any completion artifacts (accepted/stamped filing, receipt, confirmation, tax/remittance proof) as short-lived presigned download links. The filing must belong to the authenticated upstream entity.

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.

{
  "statusCode": 200,
  "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,
    "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",
        "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"
      }
    ]
  },
  "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)
`escalations`	array	Open and resolved escalations on public checklist items (see below)
`completionArtifacts`	array	Completion documents as presigned links (see below)

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`
`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 to download an artifact 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.

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

Agencies You Appoint

Contract Container Templates

Agents

Contacts

Market Contacts

Licenses

Appointments

Compliance Data Subscriptions

Compliance Status

File Documents

Policy Ingestion

Policy Transactions