> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Surplus Lines Filing
> Retrieve a single surplus lines filing by ID
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](/guides/request-response).
```json theme={null}
{
"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": "Acme 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](/api-reference/v1/surplus-lines-filings/list-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.
```json theme={null}
{
"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.
```json theme={null}
{
"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](/authentication).
## OpenAPI
````yaml openapi/v1.json GET /v1/surplus-lines-filings/{filingId}
openapi: 3.0.0
info:
title: Turris Public API
description: API for managing insurance compliance data
version: 1.0.0
contact: {}
servers:
- url: https://public.api.live.turrisfi.com
description: Production
- url: https://public.api.sandbox.turrisfi.com
description: Sandbox
security: []
tags: []
paths:
/v1/surplus-lines-filings/{filingId}:
get:
tags:
- surplus-lines-filings
operationId: SurplusLinesFilingsController_getFiling_v1
parameters:
- name: filingId
required: true
in: path
description: Unique identifier of the surplus-lines filing
schema:
example: 6650a1b2c3d4e5f6a7b8c9d0
type: string
responses:
'200':
description: >-
Surplus-lines filing detail with escalations and completion
artifacts
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/FilingDetailResponse'
requestId:
type: string
description: Unique request identifier
example: dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8
timestamp:
type: string
description: Response timestamp
example: '2025-11-12T20:49:03.293Z'
required:
- data
- requestId
- timestamp
'400':
description: Invalid filingId format
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'401':
description: Invalid or missing auth token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'404':
description: Filing not found or belongs to a different upstream entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
components:
schemas:
FilingDetailResponse:
type: object
properties:
_id:
type: string
description: Unique identifier of the filing
example: 6650a1b2c3d4e5f6a7b8c9d0
externalReference:
type: string
description: External reference identifier assigned by the caller
nullable: true
example: EXT-REF-12345
policyNumber:
type: string
description: Policy number
example: POL-2025-001
stateCode:
type: string
description: US state or territory code where the risk is located
enum:
- 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
policyTransactionType:
type: string
description: Type of policy transaction
enum:
- bind
- endorsement
- renewal
- cancellation
example: bind
status:
type: string
description: Current status of the filing
enum:
- not started
- in progress
- ready to file
- filed
- completed
- on hold
- canceled
example: in progress
actionRequired:
type: boolean
description: >-
True when at least one public-category escalation is waiting for the
customer
effectiveDate:
type: string
description: ISO 8601 policy effective date
nullable: true
example: '2025-01-01T00:00:00.000Z'
updatedAt:
type: string
description: ISO 8601 timestamp of the last update
example: '2025-06-15T12:00:00.000Z'
namedInsured:
type: string
description: Named insured on the policy
example: Acme Corp
carrier:
type: string
description: Carrier name
example: Lloyds of London
carrierNaicCode:
type: string
description: Carrier NAIC code
example: '12345'
grossPremium:
type: number
description: Gross premium amount in USD
example: 5000
totalTaxDue:
type: number
description: Total tax due in USD; null when no tax snapshot exists
nullable: true
escalations:
description: Public-category escalations for this filing (open or resolved)
type: array
items:
$ref: '#/components/schemas/EscalationResponse'
completionArtifacts:
description: >-
Completion artifacts uploaded when the filing reached Completed
status
type: array
items:
$ref: '#/components/schemas/CompletionArtifactResponse'
required:
- _id
- policyNumber
- stateCode
- policyTransactionType
- status
- actionRequired
- updatedAt
- namedInsured
- carrier
- carrierNaicCode
- grossPremium
- escalations
- completionArtifacts
ErrorResponseDto:
type: object
properties:
statusCode:
type: number
description: HTTP status code
requestId:
type: string
description: Unique request identifier for debugging
errorType:
type: string
description: Error type classification
errorMessage:
description: Array of error messages
type: array
items:
type: string
timestamp:
type: string
description: ISO timestamp when the error occurred
details:
type: object
description: Additional error context
required:
- statusCode
- requestId
- errorType
- errorMessage
- timestamp
EscalationResponse:
type: object
properties:
checklistItemLabel:
type: string
description: The checklist item label this escalation is attached to
status:
type: string
description: Current status of the escalation
enum:
- waiting turris input
- waiting customer input
- resolved
example: waiting customer input
openedAt:
type: string
description: ISO 8601 timestamp when the escalation was opened
nullable: true
resolvedAt:
type: string
description: ISO 8601 timestamp when the escalation was resolved
nullable: true
messages:
description: Chronological list of messages on this escalation
type: array
items:
$ref: '#/components/schemas/EscalationMessageResponse'
required:
- checklistItemLabel
- status
- messages
CompletionArtifactResponse:
type: object
properties:
type:
type: string
description: Type of completion artifact
enum:
- accepted stamped
- receipt
- confirmation
- tax remittance proof
example: accepted stamped
fileName:
type: string
description: Original file name of the artifact
example: stamped-filing.pdf
uploadedAt:
type: string
description: ISO 8601 timestamp when the artifact was uploaded
example: '2025-06-15T09:00:00.000Z'
downloadUrl:
type: string
description: Short-lived presigned URL to download the artifact file
viewUrl:
type: string
description: Short-lived presigned URL to view the artifact inline in the browser
required:
- type
- fileName
- uploadedAt
- downloadUrl
- viewUrl
EscalationMessageResponse:
type: object
properties:
authorLabel:
type: string
description: Display label for the message author (Turris or Agency)
example: Turris
body:
type: string
description: Message body text
createdAt:
type: string
description: ISO 8601 timestamp when the message was created
example: '2025-06-01T12:00:00.000Z'
required:
- authorLabel
- body
- createdAt
````