---
title: "Request presigned upload targets (DEFAULT ingestion path)"
method: POST
path: "/v1/clients/{client_id}/documents/prepare"
tags: ["Documents"]
---

# Request presigned upload targets (DEFAULT ingestion path)

`POST /v1/clients/{client_id}/documents/prepare`

## Request

- Base URL: `https://api.magnetictax.com`
- URL: `https://api.magnetictax.com/v1/clients/{client_id}/documents/prepare`
- Auth: HTTP bearer

Returns presigned S3 POST targets. Upload each file directly to S3, then call the finalize endpoint.

## Headers

- `Idempotency-Key` string

## Request body

- PrepareDocumentsRequest
  - `documents` object[], required
    - `content_md5` string, nullable: Optional base64-encoded 128-bit MD5 of the file. When set, it's pinned into the presigned upload so S3 rejects a corrupted upload (integrity check).
    - `content_type` string, nullable
    - `filename` string, required

## Response `200`

OK

- PrepareDocumentsResponse
  - `failed_document_ids` integer[]: Ids of documents that failed after their row was created. Preferred over failed_document_indices. Empty when a failure occurred before any row/id existed (a total insert failure) — those appear only in failed_document_indices.
  - `failed_document_indices` integer[]: DEPRECATED (removed in 1.1.0) — prefer failed_document_ids. Positions into the request array; retained because a failure with no created row has no id.
  - `upload_targets` object[]
    - `document_id` integer
    - `fields` object
    - `filename` string
    - `upload_url` string

## Other responses

- `400`: Bad request (e.g. invalid_content_md5)
- `404`: Not found
- `409`: Idempotency-Key conflict — reused for a different request (`idempotency_key_reuse`), or the original request is still running (`idempotency_request_in_progress`)
- `429`: Rate limited — retry after the `Retry-After` delay

---

[API](https://skmtc.dev/magnetictax/apis/magnetic-integrations-api.md) - [All operations](https://skmtc.dev/magnetictax/apis/magnetic-integrations-api/llms.txt) - [OpenAPI document](https://skmtc.dev/magnetictax/apis/magnetic-integrations-api/revisions/11854873aa89?raw)