> ## 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. # Reply to a Checklist Item Escalation > Reply to an open escalation thread, with an optional message and files Replies to an open escalation on a public checklist item, with an optional message body and optional file attachments, on a filing filed by your subtree. Moves the escalation to waiting on Turris. Returns the filing with the reply in place. Send it as `multipart/form-data`: `sourceCategoryId`, `sourceTaskId`, and an optional `body`, plus zero or more `files` parts. At least one of `body` or `files` is expected. A plain `application/json` body carrying just `sourceCategoryId`, `sourceTaskId`, and `body` also works, with no `files` key. ## Identifying the checklist item `sourceCategoryId` and `sourceTaskId` come from the filing's own checklist, returned by [Get a Surplus-Lines Filing](/api-reference/v2/downstream/surplus-lines-filings/get-filing), the same pair used by [Attach Files to a Checklist Item](/api-reference/v2/downstream/surplus-lines-filings/attach-checklist-item-files). Resolve them against the checklist of the specific `filingId` in the request path. A reply is refused with **404** when the checklist item is private, unknown, or has no open escalation, the same response as a `filingId` your subtree did not file. A resolved escalation cannot be replied to. ## Limits Files attached to a reply follow the same rules as the attachment endpoint: 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, a file's type is not on the allowed list, or the escalation is already resolved. ### Filing or Escalation Not Found (404) Returned when `filingId` does not exist, was not filed by your subtree, or the checklist item identified by `sourceCategoryId` / `sourceTaskId` is private, unknown, or has no open escalation. ### 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/downstream/surplus-lines-filings/{filingId}/escalation/messages 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/{filingId}/escalation/messages: post: tags: - downstream/surplus-lines-filings summary: Reply to a checklist item escalation description: >- Replies to an open escalation thread on a public checklist item, with an optional message body and optional file attachments. Send it either way: multipart/form-data with one or more files, or a plain application/json body with just the reply text and no files field at all. At least one of body or files is expected either way. Moves the escalation to waiting on Turris. Returns the filing with the reply in place. operationId: DownstreamSurplusLinesController_replyToEscalation_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/ReplyToEscalationDto' - type: object properties: files: type: array items: type: string format: binary description: >- Optional files to attach to the reply. Maximum 10MB per file. application/json: schema: $ref: '#/components/schemas/ReplyToEscalationDto' responses: '201': description: Filing with the escalation reply in place 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 filingId, an unsupported file type, or the checklist item has no open escalation 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: >- Filing not found, not filed by your subtree, 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: ReplyToEscalationDto: 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 body: type: string description: >- Reply message text; omit when the reply carries only file attachments example: Signed form attached. required: - sourceCategoryId - sourceTaskId 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 - [Reply to a Checklist Item Escalation](/api-reference/v2/surplus-lines-filings/reply-to-escalation.md) - [Surplus Lines Filing Action Required](/guides/webhooks/surplus-lines-filing-action-required.md) - [Attach Files to a Checklist Item](/api-reference/v2/surplus-lines-filings/attach-checklist-item-files.md)