curl --request POST \
--url https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/escalation/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
"sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
"body": "Signed form attached.",
"fileDocumentIds": [
"6650a1b2c3d4e5f6a7b8c9d2"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sourceCategoryId: '6650a1b2c3d4e5f6a7b8c9d0',
sourceTaskId: '6650a1b2c3d4e5f6a7b8c9d1',
body: JSON.stringify('Signed form attached.'),
fileDocumentIds: ['6650a1b2c3d4e5f6a7b8c9d2']
})
};
fetch('https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/escalation/messages', 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}/escalation/messages"
payload = {
"sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
"sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
"body": "Signed form attached.",
"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": {
"_id": "6610b3d2c2e0a51b8c0d1f09",
"name": "Lloyds of London",
"companyCode": "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": {}
}Reply to a Checklist Item Escalation
Reply to an open escalation thread, with an optional message and files
curl --request POST \
--url https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/escalation/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
"sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
"body": "Signed form attached.",
"fileDocumentIds": [
"6650a1b2c3d4e5f6a7b8c9d2"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sourceCategoryId: '6650a1b2c3d4e5f6a7b8c9d0',
sourceTaskId: '6650a1b2c3d4e5f6a7b8c9d1',
body: JSON.stringify('Signed form attached.'),
fileDocumentIds: ['6650a1b2c3d4e5f6a7b8c9d2']
})
};
fetch('https://public.api.live.turrisfi.com/v2/downstream/surplus-lines-filings/{filingId}/escalation/messages', 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}/escalation/messages"
payload = {
"sourceCategoryId": "6650a1b2c3d4e5f6a7b8c9d0",
"sourceTaskId": "6650a1b2c3d4e5f6a7b8c9d1",
"body": "Signed form attached.",
"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": {
"_id": "6610b3d2c2e0a51b8c0d1f09",
"name": "Lloyds of London",
"companyCode": "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": {}
}fileDocumentIds: upload each one with Upload a Document (category Surplus Lines) first, then pass the returned ids in a JSON body.sourceCategoryId and sourceTaskId, plus an optional body (the message) and an optional fileDocumentIds array of 1 to 10 Surplus Lines files you already uploaded. Send at least a message or one file; a reply with neither returns 400. Files you send land on the checklist item’s attachments, linked to your message.
Identifying the checklist item
sourceCategoryId and sourceTaskId come from the filing’s own checklist, returned by Get a Surplus-Lines Filing: the item Turris is waiting on has escalation.status of waiting customer input. It is the same pair Attach Uploaded Files to a Checklist Item takes. 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 or unknown, the same response as a filingId your subtree did not file. An item with no escalation, or with a resolved escalation, is refused with 400.
Limits
These limits apply when you upload each file with Upload a Document:Allowed types
10 MB per file
idempotency-key header, duplicate requests within 1 hour return the original response without reprocessing. See Idempotency.
Error Scenarios
Bad Request (400)
Returned whenfilingId is not a valid MongoDB ObjectId, the reply has neither a message nor a file, the checklist item has no escalation, or the escalation is already resolved. Also returned when fileDocumentIds is empty, has duplicates, has more than 10 entries, or holds values that are not valid ids, and when the request is sent as multipart/form-data instead of a JSON body.
Filing or Escalation Not Found (404)
Returned whenfilingId does not exist, was not filed by your subtree, the checklist item identified by sourceCategoryId / sourceTaskId is private or unknown, or a fileDocumentIds entry is not an unattached Surplus Lines upload of your subtree.
Unauthorized (401)
Missing or invalid authentication token. See Authentication.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
UUID to ensure idempotent request processing
"550e8400-e29b-41d4-a716-446655440000"
Alternative UUID header for idempotent request processing
"550e8400-e29b-41d4-a716-446655440000"
Path Parameters
Unique identifier of the surplus-lines filing
"6650a1b2c3d4e5f6a7b8c9d0"
Body
sourceCategoryId of the checklist item, from the filing checklist response
"6650a1b2c3d4e5f6a7b8c9d0"
sourceTaskId of the checklist item, from the filing checklist response
"6650a1b2c3d4e5f6a7b8c9d1"
Reply message text; omit when the reply carries only file attachments
"Signed form attached."
Already-uploaded Surplus Lines files to attach to the reply, by the fileDocumentId the upload returned. 1 to 10, no duplicates. Omit for a reply with only a message.
["6650a1b2c3d4e5f6a7b8c9d2"]
Was this page helpful?