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

# Get a Batch Upload URL

POST https://api.givechariot.com/v1/mailbox/upload_url
Content-Type: application/json

Returns a presigned URL for uploading a mailbox batch.

A batch is a ZIP file containing TIFF images and a CSV index file.
The CSV must conform to the [Batch Format](/v2026-01-15/guides/lockbox-providers/batch-format) specification.

The `location_id` must match the format `po_<number>` (e.g., `po_543`).
The returned URL is a presigned S3 URL valid for 15 minutes. Upload the batch ZIP file using an HTTP PUT request to this URL.

See the [Mail Uploads guide](/v2026-01-15/guides/lockbox-providers/mail-uploads) for details on the upload and rescan process.

Reference: https://docs.givechariot.com/api/mailbox/get-upload-url

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

### Body (application/json)

This endpoint expects an object.

- `location_id` (string, required) — The identifier of the PO box or lockbox location. Must match the format `po_<number>`.

## Response

### 200

Successfully generated a presigned upload URL.

- `url` (string, optional) — The presigned URL to upload the batch ZIP file to via HTTP PUT. Expires after 15 minutes.

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

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

**Request**

```json
{
  "location_id": "po_543"
}
```

**Response**

```json
{
  "url": "https://storage.example.com/upload?token=abc123"
}
```