Attach Uploaded Files to a Checklist Item

Attach uploaded files to a checklist item

curl --request POST \
  --url https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/checklist-item/file-documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
  "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
  "fileDocumentIds": [
    "6650a1b2c3d4e5f6a7b8c9d2"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sourceCategoryId: '6650a1b2c3d4e5f6a7b8c9d0',
    sourceTaskId: '6650a1b2c3d4e5f6a7b8c9d1',
    fileDocumentIds: ['6650a1b2c3d4e5f6a7b8c9d2']
  })
};

fetch('https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/checklist-item/file-documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/checklist-item/file-documents"

payload = {
    "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
    "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
    "fileDocumentIds": ["6650a1b2c3d4e5f6a7b8c9d2"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "filingId": "6650a1b2c3d4e5f6a7b8c9d0",
    "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
    "policyNumber": "POL-123456",
    "stateCode": "PA",
    "policyTransactionType": "bind",
    "status": "not started",
    "actionRequired": false,
    "updatedAt": "2026-06-01T12:00:00.000Z",
    "namedInsured": "Example Corp",
    "carrier": "Example Mutual Insurance Company",
    "carrierNaicCode": "12345",
    "grossPremium": 25000,
    "escalations": [
      {
        "checklistItemLabel": "<string>",
        "status": "waiting customer input",
        "messages": [
          {
            "authorLabel": "Turris",
            "body": "<string>",
            "createdAt": "2025-06-01T12:00:00.000Z"
          }
        ],
        "openedAt": "<string>",
        "resolvedAt": "<string>"
      }
    ],
    "completionArtifacts": [
      {
        "type": "accepted stamped",
        "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
        "fileName": "stamped-filing.pdf",
        "uploadedAt": "2025-06-15T09:00:00.000Z",
        "downloadUrl": "<string>",
        "viewUrl": "<string>"
      }
    ],
    "checklist": [
      {
        "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
        "name": "Documents we need from you",
        "tone": "primary",
        "order": 0,
        "items": [
          {
            "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
            "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
            "label": "Signed diligent search affidavit",
            "required": true,
            "order": 0,
            "checked": false,
            "referenceFields": [
              {
                "label": "Policy limit",
                "value": "<string>"
              }
            ],
            "templateFiles": [
              {
                "id": "6650a1b2c3d4e5f6a7b8c9d0",
                "fileName": "diligent-search-form.pdf",
                "mimeType": "application/pdf",
                "fileSize": 248310,
                "description": "<string>",
                "downloadUrl": "<string>",
                "viewUrl": "<string>"
              }
            ],
            "attachments": [
              {
                "_id": "6650a1b2c3d4e5f6a7b8c9d0",
                "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
                "fileName": "signed-form.pdf",
                "uploadedByType": "customer",
                "uploadedAt": "2026-06-01T12:00:00.000Z",
                "authorLabel": "Turris",
                "downloadUrl": "<string>",
                "viewUrl": "<string>"
              }
            ],
            "checkedAt": "2026-06-01T12:00:00.000Z",
            "escalation": {
              "checklistItemLabel": "<string>",
              "status": "waiting customer input",
              "messages": [
                {
                  "authorLabel": "Turris",
                  "body": "<string>",
                  "createdAt": "2025-06-01T12:00:00.000Z"
                }
              ],
              "openedAt": "<string>",
              "resolvedAt": "<string>"
            }
          }
        ]
      }
    ],
    "checklistProgress": {
      "checked": 3,
      "total": 5
    },
    "externalReference": "REF-2026-0001",
    "effectiveDate": "2026-01-01T00:00:00.000Z",
    "totalTaxDue": 875.5,
    "policyDocument": {
      "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
      "fileName": "policy-12345.pdf",
      "uploadedByType": "customer",
      "uploadedAt": "2025-06-15T09:00:00.000Z",
      "downloadUrl": "<string>",
      "viewUrl": "<string>"
    }
  },
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

POST

downstream

surplus-lines-filings

{filingId}

checklist-item

file-documents

Attach uploaded files to a checklist item

curl --request POST \
  --url https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/checklist-item/file-documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
  "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
  "fileDocumentIds": [
    "6650a1b2c3d4e5f6a7b8c9d2"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sourceCategoryId: '6650a1b2c3d4e5f6a7b8c9d0',
    sourceTaskId: '6650a1b2c3d4e5f6a7b8c9d1',
    fileDocumentIds: ['6650a1b2c3d4e5f6a7b8c9d2']
  })
};

fetch('https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/checklist-item/file-documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/checklist-item/file-documents"

payload = {
    "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
    "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
    "fileDocumentIds": ["6650a1b2c3d4e5f6a7b8c9d2"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "filingId": "6650a1b2c3d4e5f6a7b8c9d0",
    "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
    "policyNumber": "POL-123456",
    "stateCode": "PA",
    "policyTransactionType": "bind",
    "status": "not started",
    "actionRequired": false,
    "updatedAt": "2026-06-01T12:00:00.000Z",
    "namedInsured": "Example Corp",
    "carrier": "Example Mutual Insurance Company",
    "carrierNaicCode": "12345",
    "grossPremium": 25000,
    "escalations": [
      {
        "checklistItemLabel": "<string>",
        "status": "waiting customer input",
        "messages": [
          {
            "authorLabel": "Turris",
            "body": "<string>",
            "createdAt": "2025-06-01T12:00:00.000Z"
          }
        ],
        "openedAt": "<string>",
        "resolvedAt": "<string>"
      }
    ],
    "completionArtifacts": [
      {
        "type": "accepted stamped",
        "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
        "fileName": "stamped-filing.pdf",
        "uploadedAt": "2025-06-15T09:00:00.000Z",
        "downloadUrl": "<string>",
        "viewUrl": "<string>"
      }
    ],
    "checklist": [
      {
        "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
        "name": "Documents we need from you",
        "tone": "primary",
        "order": 0,
        "items": [
          {
            "sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
            "sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
            "label": "Signed diligent search affidavit",
            "required": true,
            "order": 0,
            "checked": false,
            "referenceFields": [
              {
                "label": "Policy limit",
                "value": "<string>"
              }
            ],
            "templateFiles": [
              {
                "id": "6650a1b2c3d4e5f6a7b8c9d0",
                "fileName": "diligent-search-form.pdf",
                "mimeType": "application/pdf",
                "fileSize": 248310,
                "description": "<string>",
                "downloadUrl": "<string>",
                "viewUrl": "<string>"
              }
            ],
            "attachments": [
              {
                "_id": "6650a1b2c3d4e5f6a7b8c9d0",
                "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
                "fileName": "signed-form.pdf",
                "uploadedByType": "customer",
                "uploadedAt": "2026-06-01T12:00:00.000Z",
                "authorLabel": "Turris",
                "downloadUrl": "<string>",
                "viewUrl": "<string>"
              }
            ],
            "checkedAt": "2026-06-01T12:00:00.000Z",
            "escalation": {
              "checklistItemLabel": "<string>",
              "status": "waiting customer input",
              "messages": [
                {
                  "authorLabel": "Turris",
                  "body": "<string>",
                  "createdAt": "2025-06-01T12:00:00.000Z"
                }
              ],
              "openedAt": "<string>",
              "resolvedAt": "<string>"
            }
          }
        ]
      }
    ],
    "checklistProgress": {
      "checked": 3,
      "total": 5
    },
    "externalReference": "REF-2026-0001",
    "effectiveDate": "2026-01-01T00:00:00.000Z",
    "totalTaxDue": 875.5,
    "policyDocument": {
      "fileDocumentId": "6650a1b2c3d4e5f6a7b8c9d1",
      "fileName": "policy-12345.pdf",
      "uploadedByType": "customer",
      "uploadedAt": "2025-06-15T09:00:00.000Z",
      "downloadUrl": "<string>",
      "viewUrl": "<string>"
    }
  },
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

Attaches Surplus Lines files you already uploaded to a public checklist item on a filing filed by your subtree, identified by fileDocumentId. Returns the filing with the new attachments in place. It replaces Attach Files to a Checklist Item, which is deprecated. Send a JSON body: sourceCategoryId and sourceTaskId, plus fileDocumentIds, an array of 1 to 10 distinct ids.

The flow

Upload each file with Upload a Document, using the category Surplus Lines. Each file can be a PDF, DOC, DOCX, JPEG or PNG, up to 10 MB.
Read the fileDocumentId in the response to each upload.
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. 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 categories Turris keeps internal are excluded from the checklist response entirely, so there is no id to obtain for one. Posting to a private or unknown item returns 404, the same response as a filingId your subtree did not file.

Which files are accepted

Every file must be a Surplus Lines upload made by your own entity or by any branch beneath it, and none may be on a filing yet. Each file is re-pointed to the entity that filed. If any one of them is not eligible, the whole call returns 404 and nothing is attached. That covers a file already on a filing, a file in another category, a file from outside your subtree, 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.

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 was not filed by your subtree, the checklist item is private or unknown, or a file is not an unattached Surplus Lines upload of your subtree.

Unauthorized (401)

Missing or invalid authentication token. See Authentication.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

idempotency-key

string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

x-idempotency-key

string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Path Parameters

filingId

string

required

Unique identifier of the surplus-lines filing

Example:

"6650a1b2c3d4e5f6a7b8c9d0"

Body

application/json

sourceCategoryId

string

required

sourceCategoryId of the checklist item, from the filing checklist response

Example:

"6650a1b2c3d4e5f6a7b8c9d0"

sourceTaskId

string

required

sourceTaskId of the checklist item, from the filing checklist response

Example:

"6650a1b2c3d4e5f6a7b8c9d1"

fileDocumentIds

string[]

required

fileDocumentIds the upload returned for Surplus Lines files that are not yet on any filing. 1 to 10, no duplicates.

Example:

["6650a1b2c3d4e5f6a7b8c9d2"]

Response

Filing with the new attachments

data

object

required

Show child attributes

requestId

string

required

Unique request identifier

Example:

"dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8"

timestamp

string

required

Response timestamp

Example:

"2025-11-12T20:49:03.293Z"

Start Here

Shared Endpoints

Licensed Entities

Producers

Contacts

Licenses

Actions Required

Licensing Overview

Appointments

License Requests

Compliance Configurations

Markets

Corporate Registrations

Documents

Surplus Lines

Attach Uploaded Files to a Checklist Item

The flow

Identifying the checklist item

Which files are accepted

Error Scenarios

Bad Request (400)

Filing, Checklist Item or File Not Found (404)

Unauthorized (401)

Authorizations

Headers

Path Parameters

Body

Response

​The flow

​Identifying the checklist item

​Which files are accepted

​Error Scenarios

​Bad Request (400)

​Filing, Checklist Item or File Not Found (404)

​Unauthorized (401)

Authorizations

Headers

Path Parameters

Body

Response

The flow

Identifying the checklist item

Which files are accepted

Error Scenarios

Bad Request (400)

Filing, Checklist Item or File Not Found (404)

Unauthorized (401)