Uploading documents

Documents are attached to a client, then picked up when you create a submission. There are two ways to upload — pick whichever fits your stack. Both accept the usual tax-doc formats (PDF, images, spreadsheets, etc.).

Option A — Presigned exchange (recommended)

You upload the bytes directly to storage; they never pass through the API, so large or many files don't tie up your request or ours. Three steps:

1. Prepare — POST /v1/clients/{id}/documents/prepare

   { "documents": [
       { "filename": "W2.pdf", "content_type": "application/pdf" },
       { "filename": "1099.pdf", "content_type": "application/pdf" }
   ] }
   

   Returns an upload_targets[] array, each with a document_id, an upload_url, and a set of fields.

2. Upload each file to its upload_url as multipart/form-data — include every key/value in fields, then the file part last. A success is HTTP 204.

3. Finalize — POST /v1/clients/{id}/documents/finalize with the document_ids you uploaded:

   { "document_ids": ["doc_456", "doc_457"] }
   

   Finalize verifies the objects landed and marks them ready. Anything that didn't upload comes back in failed_document_indices; just retry those.

If you prepare documents but never finalize them, they're ignored — they won't be attached to a submission.

Option B — Direct multipart upload

For thin clients that can't do the presigned dance, send the files straight to us in one request:

curl -s -H "Authorization: Bearer $MAGNETIC_API_KEY" \
  -F "documents=@W2.pdf" -F "documents=@1099.pdf" \
  $BASE/v1/clients/cli_123/documents

Returns the created documents and any failed_document_indices. No finalize step is needed.

Which should I use?

After uploading

Uploaded documents sit on the client until you create a submission — at which point all of the client's pending input documents are attached and processing begins. Upload everything first, then submit.