> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.givechariot.com/v2026-04-01/api/files/upload/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.givechariot.com/_mcp/server.

# Upload a File

POST https://api.givechariot.com/v1/files
Content-Type: multipart/form-data

Upload a file with a given purpose to Chariot as `multipart/form-data`.

Reference: https://docs.givechariot.com/api/files/upload

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api.givechariot.com` (Production, default)
- `https://sandboxapi.givechariot.com` (Sandbox)

## Request

### Headers

- `Idempotency-Key` (string, optional)

### Body (multipart/form-data)

This endpoint expects a multipart form containing a file.

- `file` (file, required) — The file's bytes. At most 100 MiB.
- `purpose` (enum, required)
- `description` (string, optional) — A description of the file.

## Response

### 200

The `Idempotency-Key` had already stored this file, so the existing File is returned and nothing was uploaded again.

- `id` (string, optional) — The unique identifier for the file.
- `file_name` (string, optional) — The name of the file.
- `description` (string, optional, nullable) — The description of the file.
- `purpose` (enum, optional) — The file's purpose. Note that entries may be added to this list without notice.
  - Allowed values: `manual_upload`, `grant_letter`, `integration_download`, `inbound_mail_item`, `inbound_mail_item_thumbnail`, `inbound_email`, `inbound_email_attachment`, `bank_check_image_front`, `bank_check_image_back`, `check_attachment`, `bank_statement`, `bank_account_verification_letter`, `automation_output`, `export`, `other`
- `content_type` (string, optional) — The MIME type of the file.
- `size_bytes` (long, optional) — The size of the file in bytes.
- `created_at` (datetime, optional) — The date and time when the file was created.
- `updated_at` (datetime, optional) — The date and time when the file was last updated.

### 201

The file was stored.

- `id` (string, optional) — The unique identifier for the file.
- `file_name` (string, optional) — The name of the file.
- `description` (string, optional, nullable) — The description of the file.
- `purpose` (enum, optional) — The file's purpose. Note that entries may be added to this list without notice.
  - Allowed values: `manual_upload`, `grant_letter`, `integration_download`, `inbound_mail_item`, `inbound_mail_item_thumbnail`, `inbound_email`, `inbound_email_attachment`, `bank_check_image_front`, `bank_check_image_back`, `check_attachment`, `bank_statement`, `bank_account_verification_letter`, `automation_output`, `export`, `other`
- `content_type` (string, optional) — The MIME type of the file.
- `size_bytes` (long, optional) — The size of the file in bytes.
- `created_at` (datetime, optional) — The date and time when the file was created.
- `updated_at` (datetime, optional) — The date and time when the file was last updated.

## Errors

### 400 Bad Request Error

The request is invalid or contains invalid parameters

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 401 Unauthorized Error

Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 403 Forbidden Error

Access denied

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 409 Conflict Error

Resource Conflicts

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 500 Internal Server Error

Internal Server Error

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

## Examples

### Example 1

**Request**

```json
{
  "file": "<file: string>",
  "purpose": "manual_upload"
}
```

**Response**

```json
{
  "id": "file_01j8rs605a4gctmbm58d87mvsj",
  "file_name": "donation_receipt.pdf",
  "description": "Donation receipt for donation to the nonprofit",
  "purpose": "manual_upload",
  "content_type": "application/pdf",
  "size_bytes": 20841,
  "created_at": "2020-01-31T23:59:59Z",
  "updated_at": "2020-01-31T23:59:59Z"
}
```

### Example 2

**Request**

```json
{
  "file": "<file: string>",
  "purpose": "manual_upload"
}
```

**Response**

```json
{
  "id": "file_01j8rs605a4gctmbm58d87mvsj",
  "file_name": "donation_receipt.pdf",
  "description": "Donation receipt for donation to the nonprofit",
  "purpose": "manual_upload",
  "content_type": "application/pdf",
  "size_bytes": 20841,
  "created_at": "2020-01-31T23:59:59Z",
  "updated_at": "2020-01-31T23:59:59Z"
}
```