> ## 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 Documents API

> Retrieve the list of supporting documents attached to a specific invoice

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
```

## Request

**Content-Type:** `application/json`

### Path Parameters

| Parameter   | Type   | Required | Description                                                                   |
| ----------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `invoiceId` | string | Yes      | Unique identifier of the invoice whose supporting documents are to be fetched |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.pazy.io/v1.0/invoice/<invoiceId>/supporting-documents \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/invoice/<invoiceId>/supporting-documents', {
    method: 'GET',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY'
    }
  });

  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" }

  response = requests.get(url, headers=headers)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                          | Type    | Description                                                                                         |
| ------------------------------ | ------- | --------------------------------------------------------------------------------------------------- |
| `ok`                           | boolean | Indicates whether the request was successful                                                        |
| `data`                         | object  | Contains the supporting documents response data                                                     |
| `data.documents`               | array   | List of supporting documents attached to the invoice                                                |
| `data.documents[].id`          | string  | Unique identifier for the document                                                                  |
| `data.documents[].name`        | string  | Original file name                                                                                  |
| `data.documents[].size`        | number  | File size in bytes                                                                                  |
| `data.documents[].createdOn`   | string  | Date the document was attached (ISO 8601 format)                                                    |
| `data.documents[].extension`   | string  | Uppercased file extension (e.g., `PDF`, `PNG`, `JPG`)                                               |
| `data.documents[].downloadUrl` | string  | Pre-signed URL to download the document (consume with the [Download File API](/apis/download-file)) |
| `data.documents[].user`        | object  | Information about the user who uploaded the document                                                |
| `data.documents[].user.id`     | string  | Unique identifier for the user                                                                      |
| `data.documents[].user.name`   | string  | Name of the user                                                                                    |
| `data.context`                 | object  | Container for metadata                                                                              |
| `data.context.count`           | number  | Total number of documents returned                                                                  |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "documents": [
      {
        "id": "<documentId>",
        "name": "purchase_proof.jpeg",
        "size": 1739231,
        "createdOn": "2026-05-16T11:34:11.672Z",
        "extension": "JPG",
        "downloadUrl": "https://api.pazy.io/v1.0/download/invoice-attachment?fileKey=<fileKey>.jpg",
        "user": {
          "id": "<userId>",
          "name": "John Doe"
        }
      },
      {
        "id": "<documentId>",
        "name": "delivery_receipt.png",
        "size": 65250,
        "createdOn": "2026-05-16T13:36:00.812Z",
        "extension": "PNG",
        "downloadUrl": "https://api.pazy.io/v1.0/download/invoice-attachment?fileKey=<fileKey>.png",
        "user": {
          "id": "<userId>",
          "name": "Jane Smith"
        }
      }
    ],
    "context": {
      "count": 2
    }
  }
}
```

### Empty Results

When the invoice has no supporting documents attached, an empty array is returned:

```json theme={null}
{
  "ok": true,
  "data": {
    "documents": [],
    "context": { "count": 0 }
  }
}
```

## Error Responses

### Missing Invoice ID

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Invoice ID 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

* The `downloadUrl` points at the [Download File API](/apis/download-file) — call it with the same `Authorization` header to retrieve the file bytes
* Use the [Invoice Supporting Document Upload API](/apis/invoice-supporting-document-upload) to add more files against the same invoice
* The `extension` field is uppercased and falls back to `UNK` if the underlying MIME type is missing