> ## 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.

# Vendor Document Upload API

> Upload one or more documents (PDF, image) against a vendor

## 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                                            |
| ---------- | ------ | -------- | ------------------------------------------------------ |
| `vendorId` | string | Yes      | Unique identifier of the vendor 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/vendor/<vendorId>/documents \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -F "files=@/path/to/document.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/vendor/<vendorId>/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/vendor/<vendorId>/documents"
  headers = { "Authorization": "Api-Key YOUR_API_KEY" }

  with open("/path/to/document.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 vendor   |
| `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"
  }
}
```

### Vendor Not Found

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

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

### Access Denied

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: You can only view vendors you own"
  }
}
```

Returned when the caller is neither an admin / bookkeeper nor the vendor's owner.

### 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 vendor documents
* Use the [Vendor Documents API](/apis/vendor-documents) to list the documents already attached to a vendor before deciding what to upload
* Each file is capped at 50 MB; split larger files before uploading