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

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Overview

> Keep supporting documents with outgoing transactions

Attach invoices, receipts, and supporting documents to your business’s outgoing transactions, including payments, ACH, wires, and transfers between wallets. Files are private to your business; the recipient cannot access them.

> [!NOTE]
>
> Attachments are in early access and subject to change. Contact
> [hi@natural.com](mailto:hi@natural.com) for access.

## Add a document

Send `POST /attachments` as multipart form data with the outgoing `transactionId` (`txn_*`) from your transaction history and the `file`. Include an `Idempotency-Key` header.

```bash theme={null}
curl -X POST https://api.natural.com/attachments \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F transactionId=txn_019cd1798d838f575681880edfaa4c6f \
  -F file=@invoice.pdf
```

The file is validated and stored in the same request. The response is the attachment, with its ID (`pat_*`). A file that is not a valid PDF, PNG, or JPEG is rejected with a 400.

## View and remove documents

List documents with `GET /attachments?transactionId=txn_…`. `GET /attachments/{attachmentId}/download` returns the file itself, with its content type and filename.

DELETE `/attachments/{attachmentId}` removes the attachment. Later downloads return not found.

## Export document references

Use `GET /attachments/export?transactionId=txn_…` to get `data.filename`, `data.csvContent`, and `data.generatedAt`. Save `csvContent` as the named CSV file.

The CSV includes document metadata and stable API paths for retrieving each attachment. These paths require authorization; they are not public download links.

## Access

Attachments belong to the business’s outgoing `txn_*` and its recorded wallet, regardless of payment rail. Existing read and write permissions apply within that party and wallet scope; read-only callers cannot upload or remove documents. Unpaid Requests are not supported.

## Limits

| Limit | Value |
| - | - |
| File formats | PDF, PNG, JPEG |
| Maximum file size | 20 MB (20,000,000 bytes) |
| Attachments per transaction | 100 active attachments |

Attached files cannot be replaced. To use a different file, create a new attachment. Validation checks file size and format; it does not scan for malware.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.