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

# DOCUMENTATION_REQUIRED

> A payout cannot proceed without a valid supporting document uploaded with purpose transaction_support

## What happened

You submitted a payout whose `purpose` requires supporting documentation, but the `documents` array carried no valid supporting document. Every purpose except `intercompany` and `prefunding` requires at least one document that was uploaded via `POST /v2/documents` with `purpose=transaction_support` (a `prefunding` payout requires one only when a documentation policy applies to its amount). This returns HTTP 422 with error code `DOCUMENTATION_REQUIRED`.

```json theme={null}
{
  "type": "DOCUMENTATION_REQUIRED",
  "title": "Documentation Required",
  "status": 422,
  "detail": "This payout purpose requires a supporting document and none was attached.",
  "resolution": "Upload a document via POST /v2/documents with purpose=transaction_support, attach its id in `documents`, and resubmit with a new idempotency key. `acceptedDocumentTypes` lists the kinds of evidence that satisfy review — any supported upload type is accepted at submission.",
  "docs": "/errors#documentation-required",
  "instance": "/v2/payouts",
  "correlationId": "corr_xyz789",
  "timestamp": "2026-01-15T09:30:00.000Z"
}
```

## Common causes

* **Missing `documents`** -- `purpose` is present but `documents` is empty or absent
* **Wrong document purpose** -- the document exists but was uploaded with a purpose other than `transaction_support`

This check does not apply to `purpose: intercompany` payouts (a separate recipient whitelisting gate applies) and, by default, not to `purpose: prefunding` payouts. A missing or invalid `purpose` value returns HTTP 400 `VALIDATION_ERROR`, not this error.

## Recovery

**1. Upload a supporting document with purpose transaction\_support**

Documents are uploaded as multipart/form-data. The `file` field must be a valid PDF (binary, with `%PDF-` magic bytes):

```bash theme={null}
curl -X POST https://api.conduit.financial/v2/documents \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@invoice.pdf;type=application/pdf" \
  -F "purpose=transaction_support"
```

Save the returned `id` (format `doc_*`).

**2. Resubmit the payout with `purpose` and `documents`**

```bash theme={null}
curl -X POST https://api.conduit.financial/v2/payouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: NEW_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "virtualAccountId": "vac_abc123",
    "assetAmount": {"code": "USD", "amount": "1000.00"},
    "purpose": "treasury_management",
    "documents": ["doc_abc123"],
    "destination": {
      "recipient": {
        "rail": "us",
        "type": "business",
        "legalName": "Acme Corp",
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "accountType": "checking"
      }
    }
  }'
```

<Note>
  Use a **new** `Idempotency-Key` for the corrected resubmission — attaching the document changes the request body, and the original key is bound to the no-document attempt, so reusing it returns `409 IDEMPOTENCY_KEY_CONFLICT`. Keep that new key for any further retries of the corrected payout, so a lost response replays the one accepted payout instead of creating a second one.
</Note>

## Prevention

* **Always upload documents with `purpose=transaction_support`** before referencing them in a payout
* **Include the returned `doc_*` id in the payout `documents` array** when submitting a payout whose purpose requires documentation
* **For intercompany transfers**, use `purpose: intercompany` and pre-register the recipient via `POST /v2/customers/:id/whitelist-recipients` instead

## Related endpoints

* [POST /v2/documents](/api-reference/documents/upload-a-document) -- upload a supporting document
* [POST /v2/payouts](/api-reference/payouts/create-a-payout) -- create a payout