> ## 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 Files to a Checklist Item > Upload files to a public checklist item on a filing Uploads one or more files to a public checklist item on a filing belonging to the authenticated upstream entity. Returns the filing with the new attachments in place. Send it as `multipart/form-data`: `sourceCategoryId` and `sourceTaskId` as form fields, plus one or more `files` parts. ## 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**: both ids come from the state template a filing is built from, so the same pair appears on every filing in that state, across every tenant. Always resolve them against the checklist of the specific `filingId` you are posting to, never a cached checklist from a different filing. Checklist content Turris keeps internal is excluded from the checklist response entirely, so there is no id to obtain for it. That applies at two levels: a whole category can be internal, and so can an individual item inside an otherwise-visible category. Posting to a private or unknown item returns **404**, the same response as an unrecognized `filingId`, so a caller cannot distinguish "does not exist" from "not yours to see". ## Limits PDF, DOC, DOCX, JPEG, PNG. Anything else is rejected with **400** before the body is buffered. A file larger than that returns **413**. 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` is not a valid MongoDB ObjectId, no files are attached, or a file's type is not on the allowed list. ### Filing or Checklist Item Not Found (404) Returned when `filingId` does not exist, belongs to a different upstream entity, or the checklist item identified by `sourceCategoryId` / `sourceTaskId` is private or unknown. ### Payload Too Large (413) Returned when any attached file exceeds 10 MB. ### Unauthorized (401) Missing or invalid authentication token. See [Authentication](/authentication). ## OpenAPI ````yaml openapi/v2.json POST /v2/upstream/surplus-lines-filings/{filingId}/checklist-item/attachments 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/attachments: post: tags: - upstream/surplus-lines-filings summary: Attach files to a checklist item description: >- Uploads one or more files to a public checklist item on this filing. Returns the filing with the new attachments in place. Checklist categories Turris keeps internal are excluded entirely. operationId: SurplusLinesFilingsV2Controller_attachChecklistItemFiles_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: multipart/form-data: schema: allOf: - $ref: '#/components/schemas/AttachChecklistItemFilesDto' - type: object required: - files properties: files: type: array items: type: string format: binary description: One or more files to attach. Maximum 10MB per file. 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, missing files, or an unsupported file type 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, belongs to a different upstream entity, or the checklist item is private or unknown content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '413': description: A file is larger than 10MB content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: AttachChecklistItemFilesDto: 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 required: - sourceCategoryId - sourceTaskId 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 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 - [Attach Files to a Checklist Item](/api-reference/v2/downstream/surplus-lines-filings/attach-checklist-item-files.md) - [Reply to a Checklist Item Escalation](/api-reference/v2/downstream/surplus-lines-filings/reply-to-escalation.md) - [Upload the Policy Document](/api-reference/v2/downstream/surplus-lines-filings/upload-policy-document.md)