---
title: "Get a Batch Upload URL"
method: POST
path: "/v1/mailbox/upload_url"
tags: ["mailbox"]
---

# Get a Batch Upload URL

`POST /v1/mailbox/upload_url`

## Request

- Base URL: `https://sandboxapi.givechariot.com`
- URL: `https://sandboxapi.givechariot.com/v1/mailbox/upload_url`
- Auth: HTTP bearer

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.

## Request body

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

- object
  - `url` string: The presigned URL to upload the batch ZIP file to via HTTP PUT. Expires after 15 minutes.

## Other responses

- `400`: The request is invalid or contains invalid parameters
- `401`: Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.
- `403`: Access denied
- `500`: Internal Server Error

---

[API](https://skmtc.dev/chariot-giving/apis/chariot-api-5.md) - [All operations](https://skmtc.dev/chariot-giving/apis/chariot-api-5/llms.txt) - [OpenAPI document](https://skmtc.dev/chariot-giving/apis/chariot-api-5/revisions/d2a4ff2fdda5?raw)