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

# Add Supporting Documents

> Add additional supporting documents to an existing payout.

## Overview

Adds supporting documents to an existing payout. Use this when you [initiated without a document](/api-reference/endpoint/initiate) or need to add more files later.

<Note>
  Most payouts need at least one supporting document before they can be processed. Withdrawals to your business account or a UBO's account are the exception.
</Note>

<Note>
  Each URL in `documents` must be a **`documentUrl`** from [POST /documents/upload-url](/api-reference/endpoint/upload-document-url) after you **PUT** the file to S3. Do not send file bytes to this PATCH endpoint. See [Uploading Supporting Documents](/guides/uploading-supporting-documents).

  If we have requested additional documents (`ADDITIONAL_INFO_REQUIRED`) and you need to send **more than one file**, merge them into **one PDF** before uploading to S3, then pass that `documentUrl` in this PATCH request.
</Note>

**Requirements:**

* Payout must exist and belong to your business
* Payout status must NOT be `SUCCESSFUL`, `FAILED`, or `REJECTED`
* Maximum 5 documents total per payout
* All document URLs must be HTTPS
* Accepted file formats: **PDF**, **JPEG/JPG**, and **PNG** only

**Behavior:**

* Documents are stored with UUID identifiers
* Duplicate URLs are automatically filtered out
* Returns all documents (existing + newly added)

## Request

```http theme={null}
PATCH /v1/payout-api/payouts/{id}/documents HTTP/1.1
Host: gateway.staging.useyala.com
Content-Type: application/json
x-api-key: <YOUR_API_KEY>
```

### Path Parameters

| Parameter | Type          | Required | Description       |
| --------- | ------------- | -------- | ----------------- |
| `id`      | string (UUID) | Yes      | Payout identifier |

### Headers

| Header      | Required | Description  |
| ----------- | -------- | ------------ |
| `x-api-key` | Yes      | Your API key |

### Request Body

```json theme={null}
{
  "documents": [
    "https://yala-payout-api-docs-staging.s3.us-east-1.amazonaws.com/staging/payout-api/<businessId>/<documentId>/invoice.pdf"
  ]
}
```

### Request Fields

| Field       | Type                    | Required | Description                                                                                                                     |
| ----------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `documents` | array of strings (URLs) | Yes      | Array of supporting document URLs (HTTPS required). Accepted formats: PDF, JPEG/JPG, PNG. Maximum 5 documents total per payout. |

## Response

```json theme={null}
{
  "payoutId": "123e4567-e89b-12d3-a456-426614174000",
  "totalDocuments": 3,
  "documents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png",
      "uploadedAt": "2024-01-21T12:00:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "url": "https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png",
      "uploadedAt": "2024-01-21T12:05:00Z"
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "url": "https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png",
      "uploadedAt": "2024-01-21T12:10:00Z"
    }
  ]
}
```

### Response Fields

| Field                    | Type              | Description                              |
| ------------------------ | ----------------- | ---------------------------------------- |
| `payoutId`               | string (UUID)     | Payout identifier                        |
| `totalDocuments`         | number            | Total number of documents after adding   |
| `documents`              | array             | All supporting documents for this payout |
| `documents[].id`         | string (UUID)     | Document UUID identifier                 |
| `documents[].url`        | string (URL)      | Document URL                             |
| `documents[].uploadedAt` | string (ISO 8601) | Upload timestamp                         |

## Error Responses

### 400 Bad Request - Invalid Payout Status

```json theme={null}
{
  "statusCode": 400,
  "message": "Cannot add documents to payout with status: SUCCESSFUL",
  "error": "INVALID_PAYOUT_STATUS"
}
```

**Solution:** Documents can only be added when payout status is `PENDING`, `ADDITIONAL_INFO_REQUIRED`, or `PROCESSING`. Once a payout is `SUCCESSFUL`, `FAILED`, or `REJECTED`, documents cannot be added.

### 400 Bad Request - Maximum Documents Exceeded

```json theme={null}
{
  "statusCode": 400,
  "message": "Maximum 5 documents allowed. Current: 4, Adding: 2",
  "error": "MAX_DOCUMENTS_EXCEEDED"
}
```

**Solution:** Remove some existing documents or add fewer documents. Maximum 5 documents total per payout.

### 400 Bad Request - Invalid URL Format

```json theme={null}
{
  "statusCode": 400,
  "message": "documents[0] must be a URL address",
  "error": "VALIDATION_ERROR"
}
```

**Solution:** Ensure all document URLs are valid HTTPS URLs (e.g., `https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png`).

### 404 Not Found

```json theme={null}
{
  "statusCode": 404,
  "message": "Payout not found or not associated with your business",
  "error": "PAYOUT_NOT_FOUND"
}
```

**Solution:** Verify the payout ID is correct and belongs to your business.

### 401 Unauthorized

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

## Usage Example

```javascript theme={null}
// Add supporting documents to an existing payout
const response = await fetch(
  'https://gateway.staging.useyala.com/v1/payout-api/payouts/{payoutId}/documents',
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({
      documents: [
        'https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png',
      ],
    }),
  }
);

const result = await response.json();
console.log(`Total documents: ${result.totalDocuments}`);
console.log(`Document IDs: ${result.documents.map(d => d.id).join(', ')}`);
```

## Notes

* **Status Restrictions:** Documents can only be added when payout status is `PENDING`, `ADDITIONAL_INFO_REQUIRED`, or `PROCESSING` (not `SUCCESSFUL`, `FAILED`, or `REJECTED`)
* **Maximum Documents:** 5 documents total per payout
* **Duplicate Filtering:** Duplicate URLs are automatically filtered out
* **UUID Identifiers:** Each document is assigned a UUID for tracking
* **HTTPS Required:** All document URLs must use HTTPS protocol
* **Accepted Formats:** Only PDF (`.pdf`), JPEG (`.jpeg`, `.jpg`), and PNG (`.png`) files are accepted