Manage File Attachments for Compliance Entities

This guide walks you through managing Attachments - files and documents that can be associated with clients, transactions, alerts, cases, and checklists in Corsa. Full API endpoint details are available in the API Reference (requires API credentials).

Overview

Attachments in Corsa can be linked to multiple entity types:

Entity Type	Value
Client	`client`
Transaction	`transaction`
Alert	`alert`
Case	`case`
Report	`report`
Comment	`comment`
Checklist Item	`checklist_item`

Step 1: Upload Files

Endpoint: POST /v1/attachments/upload Upload files directly and associate them with an entity. Files are sent as multipart form data. The response returns attachment IDs that you can use to relate files to additional entities later.

POST /v1/attachments/upload?entityType=client&entityId=client-uuid-123
Content-Type: multipart/form-data

files: [your-file.pdf]

const result = await corsa.attachments.uploadAttachments(
  "client",           // entityType
  "client-uuid-123",  // entityId
  { files: [fileBlob] }
);

from corsa_sdk.api.attachments.upload_attachments import _get_kwargs

resp = http.request(**_get_kwargs(
    entity_type="client",
    entity_id="client-uuid-123",
    body={"files": [file_blob]},
))
result = resp.json()

Constraints

Maximum file size: 10 MB (10,485,760 bytes) per file
Maximum files per request: 10
Maximum total request size: 110 MB (115,343,360 bytes), which covers 10 files at the per-file limit plus multipart overhead
All files must be sent in the files multipart field

Supported File Types

Format	Extensions
PDF	`.pdf`
Images	`.png`, `.jpg`, `.jpeg`
Text	`.txt`, `.csv`
Word	`.doc`, `.docx`
Excel	`.xls`, `.xlsx`, `.xlsm`
PowerPoint	`.pptx`

Files are validated by their content, not only their extension. A file whose content does not match its extension is rejected.

Error Responses

Status	Cause
`400`	More than 10 files, a multipart field other than `files`, or an unsupported file type
`413`	A file exceeds the per-file limit, or the request exceeds the total request size

Limit errors return JSON that includes the limit that was exceeded:

{
  "statusCode": 413,
  "message": "One or more files exceed the maximum allowed size",
  "maxFileSizeBytes": 10485760,
  "maxFileCount": 10
}

Step 2: Create from External URL

Endpoint: POST /v1/attachments/external-document If your documents are hosted externally (e.g., in your own storage or a vendor system), create attachment records by providing a download URL.

POST /v1/attachments/external-document
Content-Type: application/json

{
  "downloadUrl": "https://your-storage.com/documents/kyc-report.pdf",
  "fileName": "kyc-report.pdf",
  "fileType": "application/pdf",
  "fileSizeInBytes": 245000,
  "entityType": "client",
  "entityId": "client-uuid-123",
  "source": "DOCUMENT_REPOSITORY",
  "metadata": "{\"category\": \"KYC\", \"year\": 2024}"
}

const attachment = await corsa.attachments.createExternalDocument({
  downloadUrl: "https://your-storage.com/documents/kyc-report.pdf",
  fileName: "kyc-report.pdf",
  fileType: "application/pdf",
  fileSizeInBytes: 245000,
  entityType: "client",
  entityId: "client-uuid-123",
  source: "DOCUMENT_REPOSITORY",
  metadata: '{"category": "KYC", "year": 2024}',
});

from corsa_sdk.api.attachments.create_external_document import _get_kwargs
from corsa_sdk.models.create_external_document_dto import CreateExternalDocumentDto

resp = http.request(**_get_kwargs(
    body=CreateExternalDocumentDto(
        download_url="https://your-storage.com/documents/kyc-report.pdf",
        file_name="kyc-report.pdf",
        file_type="application/pdf",
        file_size_in_bytes=245000,
        entity_type="client",
        entity_id="client-uuid-123",
        source="DOCUMENT_REPOSITORY",
        metadata='{"category": "KYC", "year": 2024}',
    ),
))
attachment = resp.json()

Source Values

Source	Description
`CHECKLIST`	Attached via a checklist workflow
`DOCUMENT_REPOSITORY`	From a document management system
`DISCUSSION`	Attached in a discussion / comment
`ISSUE_DECISION`	Part of an issue decision
`EXTERNAL`	From an external system

Step 3: Relate Attachments to Entities

Endpoint: POST /v1/attachments/relate Link existing attachments to a new entity. This is useful when the same document is relevant to multiple entities (e.g., a report that applies to both an alert and a case).

POST /v1/attachments/relate
Content-Type: application/json

{
  "fileIds": [
    "attachment-uuid-1",
    "attachment-uuid-2"
  ],
  "entityId": "case-uuid-456",
  "entityType": "case"
}

await corsa.attachments.relateAttachments({
  fileIds: ["attachment-uuid-1", "attachment-uuid-2"],
  entityId: "case-uuid-456",
  entityType: "case",
});

from corsa_sdk.api.attachments.relate_attachments import _get_kwargs
from corsa_sdk.models.relate_attachments_dto import RelateAttachmentsDto

resp = http.request(**_get_kwargs(
    body=RelateAttachmentsDto(
        file_ids=["attachment-uuid-1", "attachment-uuid-2"],
        entity_id="case-uuid-456",
        entity_type="case",
    ),
))

You can relate up to 100 attachments in a single request.

Step 4: Retrieve Attachments

List Attachments for an Entity

Endpoint: GET /v1/attachments

GET /v1/attachments?entityType=client&entityId=client-uuid-123

const attachments = await corsa.attachments.getAttachmentsByEntity(
  "client",
  "client-uuid-123"
);

from corsa_sdk.api.attachments.get_attachments_by_entity import _get_kwargs

resp = http.request(**_get_kwargs(entity_type="client", entity_id="client-uuid-123"))
attachments = resp.json()

Get Download URLs

Endpoint: GET /v1/attachments/download-urls Retrieve signed download URLs for specific attachments.

GET /v1/attachments/download-urls?ids=attachment-uuid-1,attachment-uuid-2

const urls = await corsa.attachments.getDownloadUrlsByIds(
  "attachment-uuid-1,attachment-uuid-2"
);

from corsa_sdk.api.attachments.get_download_urls_by_ids import _get_kwargs

resp = http.request(**_get_kwargs(ids="attachment-uuid-1,attachment-uuid-2"))
urls = resp.json()

Step 5: Update & Delete Attachments

Update an Attachment

Endpoint: PUT /v1/attachments/{attachmentId}

PUT /v1/attachments/attachment-uuid-1
Content-Type: application/json

{
  "fileName": "updated-report-name.pdf"
}

const updated = await corsa.attachments.updateAttachment(
  "attachment-uuid-1",
  { fileName: "updated-report-name.pdf" }
);

from corsa_sdk.api.attachments.update_attachment import _get_kwargs
from corsa_sdk.models.update_attachment_dto import UpdateAttachmentDto

resp = http.request(**_get_kwargs(
    attachment_id="attachment-uuid-1",
    body=UpdateAttachmentDto(file_name="updated-report-name.pdf"),
))
updated = resp.json()

Delete an Attachment

Endpoint: DELETE /v1/attachments/{attachmentId}

DELETE /v1/attachments/attachment-uuid-1

await corsa.attachments.deleteAttachment("attachment-uuid-1");

from corsa_sdk.api.attachments.delete_attachment import _get_kwargs

resp = http.request(**_get_kwargs(attachment_id="attachment-uuid-1"))

Data Ingestion

Manage File Attachments for Compliance Entities

Overview

Step 1: Upload Files

Constraints

Supported File Types

Error Responses

Step 2: Create from External URL

Source Values

Step 3: Relate Attachments to Entities

Step 4: Retrieve Attachments

List Attachments for an Entity

Get Download URLs

Step 5: Update & Delete Attachments

Update an Attachment

Delete an Attachment

What’s Next?

Ingest Alerts & Cases

Manage Alerts & Cases

​Overview

​Step 1: Upload Files

​Constraints

​Supported File Types

​Error Responses

​Step 2: Create from External URL

​Source Values

​Step 3: Relate Attachments to Entities

​Step 4: Retrieve Attachments

​List Attachments for an Entity

​Get Download URLs

​Step 5: Update & Delete Attachments

​Update an Attachment

​Delete an Attachment

​What’s Next?

Ingest Alerts & Cases

Manage Alerts & Cases

Overview

Step 1: Upload Files

Constraints

Supported File Types

Error Responses

Step 2: Create from External URL

Source Values

Step 3: Relate Attachments to Entities

Step 4: Retrieve Attachments

List Attachments for an Entity

Get Download URLs

Step 5: Update & Delete Attachments

Update an Attachment

Delete an Attachment

What’s Next?