> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage File Attachments for Compliance Entities

> Upload, link, and manage file attachments across clients, alerts, cases, and transactions via the Corsa API.

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](https://api.corsa.finance/api-spec.json) (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.

<CodeGroup>
  ```bash REST API theme={null}
  POST /v1/attachments/upload?entityType=client&entityId=client-uuid-123
  Content-Type: multipart/form-data

  files: [your-file.pdf]
  ```

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

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

### Constraints

* Maximum file size: **5 MB** per file
* Maximum files per request: **10**

The response returns attachment IDs that you can use to relate files to additional entities later.

***

## 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.

<CodeGroup>
  ```json REST API theme={null}
  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}"
  }
  ```

  ```typescript Javascript theme={null}
  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}',
  });
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

### 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).

<CodeGroup>
  ```json REST API theme={null}
  POST /v1/attachments/relate
  Content-Type: application/json

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

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

  ```python Python theme={null}
  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",
      ),
  ))
  ```
</CodeGroup>

<Note>You can relate up to 100 attachments in a single request.</Note>

***

## Step 4: Retrieve Attachments

### List Attachments for an Entity

**Endpoint:** `GET /v1/attachments`

<CodeGroup>
  ```bash REST API theme={null}
  GET /v1/attachments?entityType=client&entityId=client-uuid-123
  ```

  ```typescript Javascript theme={null}
  const attachments = await corsa.attachments.getAttachmentsByEntity(
    "client",
    "client-uuid-123"
  );
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

### Get Download URLs

**Endpoint:** `GET /v1/attachments/download-urls`

Retrieve signed download URLs for specific attachments.

<CodeGroup>
  ```bash REST API theme={null}
  GET /v1/attachments/download-urls?ids=attachment-uuid-1,attachment-uuid-2
  ```

  ```typescript Javascript theme={null}
  const urls = await corsa.attachments.getDownloadUrlsByIds(
    "attachment-uuid-1,attachment-uuid-2"
  );
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

***

## Step 5: Update & Delete Attachments

### Update an Attachment

**Endpoint:** `PUT /v1/attachments/{attachmentId}`

<CodeGroup>
  ```json REST API theme={null}
  PUT /v1/attachments/attachment-uuid-1
  Content-Type: application/json

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

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

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

### Delete an Attachment

**Endpoint:** `DELETE /v1/attachments/{attachmentId}`

<CodeGroup>
  ```bash REST API theme={null}
  DELETE /v1/attachments/attachment-uuid-1
  ```

  ```typescript Javascript theme={null}
  await corsa.attachments.deleteAttachment("attachment-uuid-1");
  ```

  ```python Python theme={null}
  from corsa_sdk.api.attachments.delete_attachment import _get_kwargs

  resp = http.request(**_get_kwargs(attachment_id="attachment-uuid-1"))
  ```
</CodeGroup>

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Ingest Alerts & Cases" icon="bell" href="/api/ingesting-alerts-and-cases">
    Push external alerts and create investigation cases.
  </Card>

  <Card title="Manage Alerts & Cases" icon="list-check" href="/api/managing-alerts-and-cases">
    Batch create, bulk assign, and update alerts and cases.
  </Card>
</CardGroup>