> ## 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. # List Surplus-Lines Filings > The surplus-lines filings your organization submitted Returns the surplus-lines filings your organization filed, covering your entity plus every branch beneath it, newest first. ## Filings you filed, not filings about you A filing records who submitted it and which agency the policy belongs to. This endpoint returns the ones **your organization submitted**. A filing a carrier made on your behalf is that carrier's workflow, with its own escalation thread and its own internal checklist, so it is not returned here. If you expect a filing and do not see it, that is usually why. Every row carries `downstreamEntityId`, naming the entity that filed it, because the list spans your whole subtree. ## Is Turris waiting on me `actionRequired` is `true` when an escalation on a checklist item you can see is waiting for your input. [Get a filing](/api-reference/v2/downstream/surplus-lines-filings/get-filing) has the thread itself. The flag only ever reflects items visible to you. Turris keeps some checklist categories internal, and a flag you could never clear would read as a permanent to-do. ## Access This surface needs the **Surplus-Lines Filing** product feature in addition to API access. Without it every request here returns **403** while the rest of the agency API keeps working. If you expect access and see a 403, that feature is the thing to check. ## Narrowing `status`, `stateCode`, `policyNumber` and `externalReference` all match exactly. `externalReference` is your own reference as recorded on the filing, which makes it the field to use for reconciling against your own system. `downstreamEntityId` limits the list to one of your entities. ## OpenAPI ````yaml openapi/v2.json GET /v2/downstream/surplus-lines-filings openapi: 3.0.0 info: title: Turris Public API description: API for managing insurance compliance data version: 2.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: /v2/downstream/surplus-lines-filings: get: tags: - downstream/surplus-lines-filings summary: List surplus-lines filings description: >- Returns the surplus-lines filings your organization filed: your entity plus every branch beneath it. Each row names the entity that filed it and whether Turris is waiting on you. Filings a carrier made on your behalf are that carrier’s workflow and are not returned here. Narrow with downstreamEntityId, status, stateCode, policyNumber or externalReference. Ordered newest first and paginated. operationId: DownstreamSurplusLinesController_getFilings_v2 parameters: - name: page required: false in: query description: 1-based page number schema: minimum: 1 default: 1 example: 1 type: number - name: limit required: false in: query description: Page size (max 100) schema: minimum: 1 maximum: 100 default: 50 example: 50 type: number - name: downstreamEntityId required: false in: query description: >- Narrow the results to a single entity in your organization. Defaults to your whole subtree (your entity plus every branch beneath it). Returns 404 if the id is not in your subtree. schema: example: 6610b3d2c2e0a51b8c0d1f02 type: string - name: status required: false in: query description: Only filings in this status schema: example: not started type: string enum: - not started - in progress - ready to file - filed - completed - on hold - canceled - name: stateCode required: false in: query description: Only filings for this state schema: example: PA 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: Exact policy number schema: example: POL-123456 type: string - name: externalReference required: false in: query description: Your own reference recorded on the filing, matched exactly schema: example: REF-2026-0001 type: string responses: '200': description: A page of surplus-lines filings content: application/json: schema: type: object properties: data: type: object properties: items: type: array items: $ref: >- #/components/schemas/DownstreamSurplusLinesFilingResponse total: type: integer description: Total rows matching the query across all pages example: 137 page: type: integer description: 1-based page number example: 1 limit: type: integer description: Page size example: 50 totalPages: type: integer description: Number of pages, or 0 when there are no rows example: 3 required: - items - total - page - limit - totalPages 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 parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '401': description: Invalid or missing auth token content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '403': description: >- Your organization is not entitled to the public API, or does not have the Surplus-Lines Filing feature content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '404': description: downstreamEntityId is not in your organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: DownstreamSurplusLinesFilingResponse: type: object properties: filingId: type: string description: The filing id example: 6650a1b2c3d4e5f6a7b8c9d0 downstreamEntityId: type: string description: >- Which of your entities filed it. Present because the list covers your whole subtree. example: 6610b3d2c2e0a51b8c0d1f02 externalReference: type: string description: Your own reference recorded on the filing nullable: true example: REF-2026-0001 policyNumber: type: string description: Policy number the filing covers example: POL-123456 stateCode: type: string description: The state the filing was made in 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: PA policyTransactionType: type: string description: What kind of transaction the filing records enum: - bind - endorsement - renewal - cancellation example: bind status: type: string description: Where the filing stands enum: - not started - in progress - ready to file - filed - completed - on hold - canceled example: not started actionRequired: type: boolean description: >- True when Turris is waiting on something from you. See the escalations on the detail endpoint. example: false effectiveDate: type: string description: Policy effective date nullable: true example: '2026-01-01T00:00:00.000Z' updatedAt: type: string description: When the filing last changed example: '2026-06-01T12:00:00.000Z' required: - filingId - downstreamEntityId - 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: >- Machine-readable error classification. Branch on this rather than on `errorMessage`, which is prose and may change. Authentication failures returned by our identity provider are forwarded verbatim, so a 401 can carry a code outside this list; treat an unrecognised value as a generic failure of its HTTP status. enum: - conflict - contact_not_authorized - document_exceeds_page_limit - downstream_entity_member_exists - duplicate_external_id_error - duplicate_member_email - duplicate_producer_code_error - forbidden - gateway_timeout - inactive_email - internal_server_error - invalid_email - invalid_email_for_invites - invalid_organization_category - invalid_organization_slug - invalid_phone_number - invalid_token - invite_limit_reached - jwt_invalid - m2m_client_not_found - not_found - organization_already_exists - organization_slug_already_used - payment_required - producer_agreement_required - product_feature_subscription_required - service_unavailable - session_authorization_error - some_custom_error_string - throttled - too_many_requests - unauthorized - unauthorized_client - unexpected_400_stytch_error - unexpected_403_stytch_error - unexpected_404_stytch_error - unexpected_error - unexpected_stytch_error - unprocessable_entity - validation_error example: validation_error 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 ```` ## Related topics - [Surplus Lines Filings](/api-reference/v2/surplus-lines-filings/list-filings.md) - [Surplus Lines Filing](/api-reference/v2/surplus-lines-filings/get-filing.md) - [Surplus Lines Filing Action Required](/guides/webhooks/surplus-lines-filing-action-required.md)