> ## 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. # Attach Uploaded Files to a Checklist Item > Attach files you already uploaded to a public checklist item on a filing Attaches Surplus Lines files you already uploaded to a public checklist item on a filing belonging to the authenticated upstream entity, identified by `fileDocumentId`. Returns the filing with the new attachments in place. It replaces [Attach Files to a Checklist Item](/api-reference/v2/surplus-lines-filings/attach-checklist-item-files), which is deprecated. Send a JSON body: `sourceCategoryId` and `sourceTaskId`, plus `fileDocumentIds`, an array of 1 to 10 distinct ids. ## The flow 1. Upload each file with [Upload a Document](/api-reference/v2/file-documents/upload-document), using the category **Surplus Lines**. Each file can be a PDF, DOC, DOCX, JPEG or PNG, up to 10 MB. 2. Read the `_id` of each document the uploads return. Those are the `fileDocumentIds`. 3. Call this endpoint with the filing's id, the checklist item's ids, and the `fileDocumentIds`. ## Identifying the checklist item `sourceCategoryId` and `sourceTaskId` come from the filing's own checklist, returned by [Get a Surplus Lines Filing](/api-reference/v2/surplus-lines-filings/get-filing). That pair identifies an item **within one filing only**, so always resolve it against the checklist of the specific `filingId` you are posting to. Checklist content Turris keeps internal is excluded from the checklist response entirely, so there is no id to obtain for it. Posting to a private or unknown item returns **404**, the same response as an unrecognized `filingId`. ## Which files are accepted Every file must be a Surplus Lines upload of your own that is not on any filing yet. If any one of them is not, the whole call returns **404** and nothing is attached. That covers a file already on a filing, a file in another category, a file another organization uploaded, and a file that has been deleted. This endpoint supports idempotency. If you include an `idempotency-key` header, duplicate requests within **1 hour** return the original response without reprocessing. See [Idempotency](/guides/idempotency). ## Error Scenarios ### Bad Request (400) Returned when `filingId`, `sourceCategoryId`, `sourceTaskId` or a `fileDocumentIds` entry is not a valid MongoDB ObjectId, or `fileDocumentIds` is empty, has duplicates, or has more than 10 entries. ### Filing, Checklist Item or File Not Found (404) Returned when `filingId` does not exist or belongs to a different upstream entity, the checklist item is private or unknown, or a file is not an unattached Surplus Lines upload of yours. ### Unauthorized (401) Missing or invalid authentication token. See [Authentication](/authentication). ## OpenAPI ````yaml openapi/v2.json POST /v2/upstream/surplus-lines-filings/{filingId}/checklist-item/file-documents 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/upstream/surplus-lines-filings/{filingId}/checklist-item/file-documents: post: tags: - upstream/surplus-lines-filings summary: Attach uploaded files to a checklist item description: >- Attaches Surplus Lines files you already uploaded with the Upload a Document endpoint to a public checklist item on this filing, by fileDocumentId. Each file must be one of your Surplus Lines uploads that is not on any filing yet. Returns the filing with the new attachments in place. Checklist categories Turris keeps internal are excluded entirely. operationId: SurplusLinesFilingsV2Controller_attachChecklistItemFileDocuments_v2 parameters: - name: filingId required: true in: path description: Unique identifier of the surplus-lines filing schema: example: 6650a1b2c3d4e5f6a7b8c9d0 type: string - 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/AttachChecklistItemFileDocumentsDto' responses: '201': description: Filing with the new attachments 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, checklist ids or fileDocumentIds 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: >- 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: >- Filing not found or not yours, the checklist item is private or unknown, or a file is not an unattached Surplus Lines upload of yours content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: AttachChecklistItemFileDocumentsDto: type: object properties: sourceCategoryId: type: string description: >- sourceCategoryId of the checklist item, from the filing checklist response example: 6650a1b2c3d4e5f6a7b8c9d0 sourceTaskId: type: string description: >- sourceTaskId of the checklist item, from the filing checklist response example: 6650a1b2c3d4e5f6a7b8c9d1 fileDocumentIds: description: >- fileDocumentIds the upload returned for Surplus Lines files that are not yet on any filing. 1 to 10, no duplicates. example: - 6650a1b2c3d4e5f6a7b8c9d2 type: array items: type: string required: - sourceCategoryId - sourceTaskId - fileDocumentIds 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: Example 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' 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: >- Customer-visible checklist for this filing. 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 visible checklist items only allOf: - $ref: '#/components/schemas/ChecklistProgressResponse' required: - _id - 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 fileDocumentId: type: string description: The document id to pass to Get a Download URL for a Document example: 6650a1b2c3d4e5f6a7b8c9d1 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 - fileDocumentId - fileName - uploadedAt - downloadUrl - viewUrl PolicyDocumentResponse: type: object properties: fileDocumentId: type: string description: The document id to pass to Get a Download URL for a Document example: 6650a1b2c3d4e5f6a7b8c9d1 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: - fileDocumentId - 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: >- Identifies the attachment record on the checklist item. This is NOT a file document id: to download the file, pass fileDocumentId to Get a Download URL for a Document. example: 6650a1b2c3d4e5f6a7b8c9d0 fileDocumentId: type: string description: The document id to pass to Get a Download URL for a Document example: 6650a1b2c3d4e5f6a7b8c9d1 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 - fileDocumentId - 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 - [Attach Uploaded Files to a Checklist Item](/api-reference/v2/downstream/surplus-lines-filings/attach-checklist-item-file-documents.md) - [Attach Files to a Checklist Item](/api-reference/v2/downstream/surplus-lines-filings/attach-checklist-item-files.md) - [Upload a Document](/api-reference/v2/file-documents/upload-document.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.