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

# Invoice Supporting Document Upload API

> Upload one or more supporting documents against an existing invoice

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
Content-Type: multipart/form-data
```

## Request

**Content-Type:** `multipart/form-data`

### Path Parameters

| Parameter   | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| `invoiceId` | string | Yes      | Unique identifier of the invoice to attach documents to |

### Form Fields

| Field   | Type | Required | Description                                                                                                              |
| ------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `files` | file | Yes      | The file(s) to upload. Repeat the field name to upload multiple files in a single request. Max file size 50 MB per file. |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/invoice/<invoiceId>/supporting-documents \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -F "files=@/path/to/receipt.pdf"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const formData = new FormData();
  formData.append('files', fileInput.files[0]);

  const response = await fetch('https://api.pazy.io/v1.0/invoice/<invoiceId>/supporting-documents', {
    method: 'POST',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY'
    },
    body: formData
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/invoice/<invoiceId>/supporting-documents"
  headers = { "Authorization": "Api-Key YOUR_API_KEY" }

  with open("/path/to/receipt.pdf", "rb") as f:
      files = { "files": f }
      response = requests.post(url, headers=headers, files=files)

  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                  | Type    | Description                                                     |
| ---------------------- | ------- | --------------------------------------------------------------- |
| `ok`                   | boolean | Indicates whether the request was successful                    |
| `insert`               | boolean | Indicates that the documents were inserted against the invoice  |
| `context`              | object  | Container for upload metadata                                   |
| `context.fileUploaded` | number  | Number of files that were successfully uploaded in this request |

### Response Example

```json theme={null}
{
  "ok": true,
  "insert": true,
  "context": {
    "fileUploaded": 1
  }
}
```

## Error Responses

### Missing File

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Files field is required"
  }
}
```

### Invoice Not Found

**HTTP Status:** `404 Not Found`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice not found"
  }
}
```

### Access Denied

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: You can only view your own invoices or invoices where you are the vendor owner"
  }
}
```

Returned when the caller is not an admin / bookkeeper, did not create the invoice, and is not the owner of its vendor.

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### Internal Error

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}
```

## Best Practices

* Repeat the `files` field name to upload multiple documents in a single call — they are saved as separate supporting documents
* Use the [Invoice Supporting Documents API](/apis/invoice-supporting-documents) to list the documents already attached to an invoice
* Each file is capped at 50 MB; split larger files before uploading
* Supporting documents are stored separately from the original invoice file uploaded via the [Invoice Creation API](/apis/invoice-creation)