> ## 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 Filings
> List surplus lines filings belonging to the authenticated upstream entity
Returns the surplus lines filings owned by your upstream entity. Each item includes an `actionRequired` flag that is `true` when a public checklist escalation is currently waiting on your input. Results can be filtered by status, state, policy number, or the external reference you assigned.
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| **`status`** | string | No | Filter by filing status: `not started`, `in progress`, `ready to file`, `filed`, `completed`, `on hold`, or `canceled` |
| **`stateCode`** | string | No | Filter by 2-letter US state or territory code (e.g., `CA`) |
| **`policyNumber`** | string | No | Filter by exact policy number |
| **`externalReference`** | string | No | Filter by the external reference identifier you assigned to the filing |
## Filtering Examples
```bash theme={null}
# By status
GET /v1/surplus-lines-filings?status=filed
# By state
GET /v1/surplus-lines-filings?stateCode=CA
# By your external reference
GET /v1/surplus-lines-filings?externalReference=UNION-12345
```
## 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": false,
"effectiveDate": "2025-01-15T00:00:00.000Z",
"updatedAt": "2025-01-16T10:31:45.000Z"
}
],
"timestamp": "2025-01-16T10:31:50.000Z"
}
```
### Response Fields
| Field | Type | Description |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `_id` | string | Unique filing identifier |
| `externalReference` | string? | The external reference you assigned to the filing (null if not set) |
| `policyNumber` | string | Policy number the filing is for |
| `stateCode` | string | US state or territory code where the filing is made |
| `policyTransactionType` | string | Transaction type: `bind`, `endorsement`, `renewal`, or `cancellation` |
| `status` | string | Filing status: `not started`, `in progress`, `ready to file`, `filed`, `completed`, `on hold`, or `canceled` |
| `actionRequired` | boolean | `true` when a public checklist escalation is waiting on your input |
| `effectiveDate` | string? | Policy effective date (ISO 8601), null if not set |
| `updatedAt` | string | ISO 8601 timestamp of the last update |
Filings with `actionRequired: true` need your attention. Fetch the filing detail to read the open escalation and its notes.
## Error Scenarios
### Bad Request (400)
Returned when a query parameter has an invalid value (e.g., an unsupported `status`).
```json theme={null}
{
"statusCode": 400,
"errorType": "validation_error",
"errorMessage": ["Invalid value for status"],
"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
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:
get:
tags:
- surplus-lines-filings
operationId: SurplusLinesFilingsController_listFilings_v1
parameters:
- name: status
required: false
in: query
description: Filter by filing status
schema:
example: in progress
type: string
enum:
- not started
- in progress
- ready to file
- filed
- completed
- on hold
- canceled
- name: stateCode
required: false
in: query
description: Filter by US state or territory code
schema:
example: CA
type: string
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
- name: policyNumber
required: false
in: query
description: Filter by exact policy number
schema:
example: POL-2025-001
type: string
- name: externalReference
required: false
in: query
description: Filter by external reference identifier assigned by the caller
schema:
example: EXT-REF-12345
type: string
responses:
'200':
description: >-
List of surplus-lines filings belonging to the authenticated
upstream entity
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/FilingListItemResponse'
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 query parameter value
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'401':
description: Invalid or missing auth token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
components:
schemas:
FilingListItemResponse:
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'
required:
- _id
- policyNumber
- stateCode
- policyTransactionType
- status
- actionRequired
- updatedAt
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
````