---
title: "Upload bytes to a prepared single-use handoff"
method: POST
path: "/api/document-handoffs/{ticket}"
---

# Upload bytes to a prepared single-use handoff

`POST /api/document-handoffs/{ticket}`

## Request

- Base URL: `https://postedly.com`
- URL: `https://postedly.com/api/document-handoffs/{ticket}`
- Auth: none required

Use the exact uploadEndpoint returned by postedly_prepare_document. The ticket authorizes one successful file upload for its connected owner and fixed service; no separate bearer token or guest session is needed. Only file is supplied. Prefer authenticated POST /api/documents when the agent already has file bytes and authenticated HTTP access. This route enables runtime upload with a prepared ticket; the returned browser uploadUrl is a fallback when the agent cannot access the bytes. No arbitrary URL import.

## Response `201`

Handoff complete with its private document metadata and SHA-256.

- object
  - `documentRequestId` string, uuid, required
  - `service` string, required: Original target service. An existing upload request can retain a service no longer offered; no new upload is accepted for a withdrawn service.
  - `filename` string, nullable
  - `status` 'complete', required
  - `expiresAt` string, date-time, required
  - `document` Document, required
    - `id` string, uuid, required: Use this value as documentId in a quote; the person does not need to copy it.
    - `name` string, required
    - `pages` integer, required: Inspected page count; images count as one. Upload PDFs allow up to 50 pages; service-specific quote limits can be lower.
    - `bytes` integer, required
    - `sha256` string, required: Server-computed SHA-256 of the stored raw file bytes.
    - `contentType` 'application/pdf' | 'image/jpeg' | 'image/png', required: Detected media type, not a trusted client declaration.
    - `previewUrl` string, uri-reference, required: Private preview. Standard document URLs require the same owner’s bearer token; capability-scoped handoff URLs require their unexpired ticket. Resolve relative URLs against this API origin. Never make the file public to show a preview.

## Other responses

- `400`: Invalid service, missing file, invalid SHA-256, hash mismatch, invalid or encrypted PDF, unsupported format, or document limits exceeded. No document is saved when validation fails.
- `404`: Invalid ticket
- `409`: Handoff already used or another upload claimed it
- `410`: Expired ticket
- `413`: Request body exceeds the bounded upload envelope
- `429`: Upload rate limit exceeded
- `503`: The original upload service is no longer offered

---

[API](https://skmtc.dev/postedly/apis/postedly-send-api.md) · [All operations](https://skmtc.dev/postedly/apis/postedly-send-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postedly/apis/postedly-send-api/revisions/c7c71c05f64b?raw)