> ## 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. # Open a Surplus-Lines Filing > Start a filing for your own entity or a child branch Opens a filing from the live state template and returns it with the checklist and tax detail Turris will work through. `downstreamEntityId` names which entity the policy is about: your own entity or one of its child branches. The filing itself is always owned by the credential that opened it, regardless of which entity `downstreamEntityId` names. ## What is decided for you A filing is a workflow Turris runs. The statuses past the first are our operational vocabulary, not yours to declare, so the field is not accepted. Frozen at the moment the filing opens. Later template edits never reshape a filing that already exists. Omit either one and it is treated as `0` for the initial tax calculation. Update the filing once you know the real number and the tax recomputes automatically. ## externalReference is a correlation id, not an idempotency key Store your own reference on the filing and it is echoed back on every read. It does **not** deduplicate: sending the same value twice opens two filings. Use the `idempotency-key` header below for that. ## One open filing per agency, state, policy number and transaction type A second filing matching all four is refused with **409** while the first is still active. A soft-deleted filing does not block a new one. ## States without a template Turris maintains a filing template per state. A state we have not templated yet returns **404** naming the state. Send an `Idempotency-Key` header. See [Idempotency](/guides/idempotency). ## OpenAPI ````yaml openapi/v2.json POST /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: - bearer: [] - restricted-access-token: [] tags: - name: auth description: Shared. Serves either organization category, so no persona applies. x-organization-category: null - name: downstream/actions-required description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/appointments description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/compliance-configs description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/contacts description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/corporate-registrations description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/documents description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/entities description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/license-overview description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/license-requests description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/licenses description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/markets description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/producers description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: downstream/surplus-lines-filings description: >- Agency surface. Requires a credential whose organization category is downstreamEntity. x-organization-category: downstreamEntity - name: heartbeat description: Shared. Serves either organization category, so no persona applies. x-organization-category: null - name: upstream/agents description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/agents-license-compliance description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/carriers description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/compliance-data-subscriptions description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/contacts description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/contract-container-templates description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/diligent-effort-requests description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/downstream-entity-associations description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/file-documents description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/market-contacts description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/npn-lookup description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/policies description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/products description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/surplus-lines-filings description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity - name: upstream/webhooks description: >- Carrier and MGA surface. Requires a credential whose organization category is upstreamEntity. x-organization-category: upstreamEntity paths: /v2/downstream/surplus-lines-filings: post: tags: - downstream/surplus-lines-filings summary: Open a surplus-lines filing description: >- Opens a new filing from the live state template for the named agency, which must be your own entity or one of its child branches. Snapshots that template's checklist and tax rates onto the filing at creation; later template edits never reshape it. brokerFee and otherTaxableFees may be omitted and filled in later. operationId: DownstreamSurplusLinesController_createFiling_v2 parameters: - name: idempotency-key in: header description: UUID to ensure idempotent request processing required: false schema: type: string example: 550e8400-e29b-41d4-a716-446655440000 - name: x-idempotency-key in: header description: Alternative UUID header for idempotent request processing required: false schema: type: string example: 550e8400-e29b-41d4-a716-446655440000 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSurplusLinesFilingDto' responses: '201': description: The newly-created filing content: application/json: schema: type: object properties: data: $ref: >- #/components/schemas/DownstreamSurplusLinesFilingDetailResponse 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 request body, a missing endorsementNumber on an endorsement filing, or an entity outside your own scope 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. Also returned with `errorType` `invalid_organization_category` when your credential's organization category does not match the one this endpoint serves; `details` names the expected and actual category. This endpoint can return 403 for other reasons too, so branch on `errorType`; the Error Handling guide lists them. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '404': description: Turris has no surplus-lines template for the given stateCode yet content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '409': description: >- A filing for this agency, state, policy number, and transaction type already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: CreateSurplusLinesFilingDto: type: object properties: downstreamEntityId: type: string description: >- Which of your eligible agencies the filing is for. For the carrier persona, any agency you are associated with. For the agency persona, your own entity or one of its child branches. example: 6610b3d2c2e0a51b8c0d1f02 stateCode: type: string description: >- The state or territory to file in. Turris must have a surplus-lines template for it. 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 policyNumber: type: string description: The policy number example: POL-2026-001 policyTransactionType: type: string description: What kind of policy transaction this filing records enum: - bind - endorsement - renewal - cancellation example: bind endorsementNumber: type: number description: >- Required when policyTransactionType is endorsement (enforced server-side) example: 1 riskAddress: type: string description: The risk address example: 123 Main St, San Francisco, CA namedInsured: type: string description: The named insured on the policy example: Example Corp carrier: type: string description: The carrier writing the policy example: Example Mutual Insurance Company carrierNaicCode: type: string description: The carrier NAIC code example: '12345' carrierId: type: string description: >- Id of an approved carrier (see the List Carriers endpoint). When supplied, the service resolves it and overrides carrier / carrierNaicCode with the resolved name and NAIC code. example: 6610b3d2c2e0a51b8c0d1f09 bindDate: type: string description: Policy bind date, date-only (YYYY-MM-DD) example: '2026-01-01' effectiveDate: type: string description: Policy effective date, date-only (YYYY-MM-DD) example: '2026-01-01' expirationDate: type: string description: Policy expiration date, date-only (YYYY-MM-DD) example: '2027-01-01' grossPremium: type: number description: Gross premium, in dollars example: 25000 nonTaxablePremium: type: number description: >- Informational premium portion that is NOT taxed. Never enters the tax calculation. example: 0 brokerFee: type: number description: >- The broker fee. Omit to let Turris fill it in later; the tax recomputes automatically. example: 0 otherTaxableFees: type: number description: >- Other taxable fees. Omit to let Turris fill it in later; the tax recomputes automatically. example: 0 externalReference: type: string description: >- Your own reference for this filing, echoed back on every read. A correlation id, not an idempotency key: it does not deduplicate, so a retry with the same value opens a second filing. example: REF-2026-0001 required: - downstreamEntityId - stateCode - policyNumber - policyTransactionType - namedInsured - carrier - bindDate - effectiveDate - expirationDate - grossPremium DownstreamSurplusLinesFilingDetailResponse: 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' namedInsured: type: string description: The insured named on the policy example: Example Corp carrier: type: string description: The carrier writing the policy example: Example Mutual Insurance Company carrierNaicCode: type: string description: The carrier NAIC code example: '12345' grossPremium: type: number description: Gross premium, in dollars example: 25000 totalTaxDue: type: number description: Total tax due once Turris has computed it, otherwise null nullable: true example: 875.5 escalations: description: Open and resolved escalations on the checklist items you can see type: array items: $ref: '#/components/schemas/EscalationResponse' completionArtifacts: description: Finished filing documents, each with short-lived presigned links type: array items: $ref: '#/components/schemas/CompletionArtifactResponse' policyDocument: description: >- The policy document attached to this filing, or null if none has been uploaded yet nullable: true type: object allOf: - $ref: '#/components/schemas/PolicyDocumentResponse' checklist: description: >- The checklist you can see for this filing. Turris-internal categories are never included, so this is the outstanding work you can act on. Each item nests its own escalation; the flat escalations[] above is the same set of threads, kept for backward compatibility. type: array items: $ref: '#/components/schemas/ChecklistCategoryResponse' checklistProgress: description: Checked/total counts over the checklist items you can see only allOf: - $ref: '#/components/schemas/ChecklistProgressResponse' required: - filingId - downstreamEntityId - policyNumber - stateCode - policyTransactionType - status - actionRequired - updatedAt - namedInsured - carrier - carrierNaicCode - grossPremium - escalations - completionArtifacts - checklist - checklistProgress 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 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 PolicyDocumentResponse: type: object properties: fileName: type: string description: Original file name of the policy document example: policy-12345.pdf uploadedByType: type: string description: Who uploaded the policy document enum: - admin - customer example: customer uploadedAt: type: string description: ISO 8601 timestamp when the policy document was uploaded example: '2025-06-15T09:00:00.000Z' downloadUrl: type: string description: Short-lived presigned URL to download the policy document viewUrl: type: string description: >- Short-lived presigned URL to view the policy document inline in the browser required: - fileName - uploadedByType - uploadedAt - downloadUrl - viewUrl ChecklistCategoryResponse: type: object properties: sourceCategoryId: type: string description: Identifier of the category example: 6650a1b2c3d4e5f6a7b8c9d0 name: type: string description: Category name example: Documents we need from you tone: type: string description: Display tone for the category enum: - primary - secondary - neutral - green - red - yellow example: primary order: type: number description: Display order of the category within the checklist example: 0 items: description: Items in this category type: array items: $ref: '#/components/schemas/ChecklistItemResponse' required: - sourceCategoryId - name - tone - order - items ChecklistProgressResponse: type: object properties: checked: type: number description: How many visible checklist items are done example: 3 total: type: number description: How many visible checklist items there are in total example: 5 required: - checked - total 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 ChecklistItemResponse: type: object properties: sourceCategoryId: type: string description: >- Identifier of the category this item belongs to. Repeated on the item as well as on its parent category so that the (sourceCategoryId, sourceTaskId) pair survives flattening: checklist.flatMap((category) => category.items) is how you find outstanding items, and it discards the parent. example: 6650a1b2c3d4e5f6a7b8c9d0 sourceTaskId: type: string description: >- Identifier of this item. Together with sourceCategoryId it identifies the item within THIS filing, which is what lets you match an item to the same item on a later poll. The pair is unique within one filing only: both ids come from the state template, so they are identical across every filing in the same state and across tenants. Key any client-side cache by filing id as well, or two filings in one state will collide. example: 6650a1b2c3d4e5f6a7b8c9d1 label: type: string description: What the item asks for example: Signed diligent search affidavit required: type: boolean description: True when the filing cannot complete without this item example: true order: type: number description: Display order of the item within its category example: 0 checked: type: boolean description: True once Turris has satisfied the item example: false checkedAt: type: string description: >- ISO 8601 timestamp when the item was checked off; null while outstanding nullable: true example: '2026-06-01T12:00:00.000Z' referenceFields: description: Reference values captured against this item type: array items: $ref: '#/components/schemas/ChecklistReferenceFieldResponse' templateFiles: description: >- Blank forms supplied for this item, each with short-lived presigned links type: array items: $ref: '#/components/schemas/ChecklistTemplateFileResponse' attachments: description: Files attached to this item, each with short-lived presigned links type: array items: $ref: '#/components/schemas/ChecklistItemAttachmentResponse' escalation: description: >- Escalation raised on this item; null when none was raised. Also listed on the filing escalations[]. nullable: true type: object allOf: - $ref: '#/components/schemas/EscalationResponse' required: - sourceCategoryId - sourceTaskId - label - required - order - checked - referenceFields - templateFiles - attachments ChecklistReferenceFieldResponse: type: object properties: label: type: string description: Field label as configured on the state template example: Policy limit value: type: string description: Value captured for this field; empty string when not yet filled in required: - label - value ChecklistTemplateFileResponse: type: object properties: id: type: string description: Identifier of the template file example: 6650a1b2c3d4e5f6a7b8c9d0 fileName: type: string description: Original file name example: diligent-search-form.pdf mimeType: type: string description: MIME type of the file example: application/pdf fileSize: type: number description: File size in bytes example: 248310 description: type: string description: Description of what the file is for; empty string when none was set downloadUrl: type: string description: Short-lived presigned URL to download the file viewUrl: type: string description: Short-lived presigned URL to view the file inline in the browser required: - id - fileName - mimeType - fileSize - description - downloadUrl - viewUrl ChecklistItemAttachmentResponse: type: object properties: _id: type: string description: Identifier of the attachment example: 6650a1b2c3d4e5f6a7b8c9d0 fileName: type: string description: Original file name example: signed-form.pdf uploadedByType: type: string description: Who uploaded the file enum: - admin - customer example: customer uploadedAt: type: string description: ISO 8601 timestamp when the file was uploaded example: '2026-06-01T12:00:00.000Z' authorLabel: type: string description: >- Who uploaded the file, as a display label: 'Turris' for a Turris upload, otherwise the name of the entity the filing belongs to. Uploader ids are never returned. example: Turris downloadUrl: type: string description: Short-lived presigned URL to download the file viewUrl: type: string description: Short-lived presigned URL to view the file inline in the browser required: - _id - fileName - uploadedByType - uploadedAt - authorLabel - downloadUrl - viewUrl securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http restricted-access-token: type: apiKey in: header name: x-restricted-access-token description: >- Alternative authentication: Restricted access token (if not using Bearer token) ```` ## Related topics - [Open a Surplus-Lines Filing](/api-reference/v2/surplus-lines-filings/open-filing.md) - [Surplus Lines Filing](/api-reference/v2/surplus-lines-filings/get-filing.md) - [Surplus Lines Filings](/api-reference/v2/surplus-lines-filings/list-filings.md)