Quickstart

This walks the full loop: client → documents → submission → output documents. Examples use curl; any HTTP client works.

export MAGNETIC_API_KEY=mag_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export BASE=https://api.magnetictax.com   # sandbox base URL available on request
auth=(-H "Authorization: Bearer $MAGNETIC_API_KEY")

1. Create a client

A client is the taxpayer the return is for.

curl -s "${auth[@]}" -H 'Content-Type: application/json' \
  -d '{"friendly_name":"Jane Q. Taxpayer"}' \
  $BASE/v1/clients

{ "id": "cli_123", "friendly_name": "Jane Q. Taxpayer", "taxpayer_tin": null, "created_at": "2026-06-23T20:00:00Z" }

Keep the id (cli_123).

2. Upload documents

The recommended path is the presigned exchange: you upload bytes straight to storage, so large files never tie up the API. (A simpler one-shot multipart upload is also available.)

a. Ask for upload targets

curl -s "${auth[@]}" -H 'Content-Type: application/json' \
  -d '{"documents":[{"filename":"W2.pdf","content_type":"application/pdf"}]}' \
  $BASE/v1/clients/cli_123/documents/prepare

{
  "upload_targets": [
    { "document_id": "doc_456", "filename": "W2.pdf",
      "upload_url": "https://s3-us-west-2.amazonaws.com/...",
      "fields": { "key": "...", "policy": "...", "x-amz-signature": "..." } }
  ],
  "failed_document_indices": []
}

b. Upload each file to the returned URL (POST the fields plus the file, as multipart/form-data):

curl -s -X POST "<upload_url>" \
  -F key="<fields.key>" -F policy="<fields.policy>" -F x-amz-signature="<fields…>" \
  -F file=@W2.pdf
# → HTTP 204

c. Finalize to confirm the uploads:

curl -s "${auth[@]}" -H 'Content-Type: application/json' \
  -d '{"document_ids":["doc_456"]}' \
  $BASE/v1/clients/cli_123/documents/finalize

3. Create a submission

tax_software and tax_year are required. See valid tax_software values.

curl -s "${auth[@]}" -H 'Content-Type: application/json' \
  -d '{"tax_software":"Drake","tax_year":2025}' \
  $BASE/v1/clients/cli_123/submissions

{
  "id": "sub_789",
  "client_id": "cli_123",
  "status": "processing",
  "tax_software": "Drake",
  "tax_year": 2025,
  "expected_completion_at": "2026-06-26T20:00:00Z",
  "input_documents": [ { "id": "doc_456", "filename": "W2.pdf" } ],
  "output_documents": []
}

expected_completion_at is the date you can expect the finished return by.

4. Poll until completed

curl -s "${auth[@]}" $BASE/v1/submissions/sub_789

Poll periodically (e.g. a few times a day — processing takes ~3 business days). When status becomes completed, output_documents are populated with ready-to-use download_urls:

{
  "id": "sub_789",
  "status": "completed",
  "output_documents": [
    { "id": "doc_999", "filename": "Jane_Q_Taxpayer_2025_Return.pdf",
      "download_url": "https://s3-us-west-2.amazonaws.com/..." }
  ]
}

5. Download the outputs

curl -sL "<output_documents[0].download_url>" -o return.pdf

That's the full round trip. For details on each step see Uploading documents and Submissions & statuses.