Example integration

A typical integration: your application already holds a taxpayer's documents and wants the finished return back automatically — no manual uploading, no copy‑pasting status. The whole exchange is a handful of API calls.

Flow

1. Create a client for the taxpayer.
2. Upload their documents (presigned, so bytes go straight to storage).
3. Submit for prep and store the returned expected_completion_at to show your user.
4. Poll the submission until it's completed.
5. Download the output documents and surface them back in your app.

End-to-end (pseudocode)

import requests

BASE = "https://api.magnetictax.com"
H = {"Authorization": f"Bearer {MAGNETIC_API_KEY}"}

# 1. Create the client
client = requests.post(f"{BASE}/v1/clients",
                       headers=H, json={"friendly_name": taxpayer_name}).json()
cid = client["id"]

# 2. Presigned upload of each document
manifest = [{"filename": d.name, "content_type": d.mime} for d in documents]
prep = requests.post(f"{BASE}/v1/clients/{cid}/documents/prepare",
                     headers=H, json={"documents": manifest}).json()
for target, doc in zip(prep["upload_targets"], documents):
    requests.post(target["upload_url"], data=target["fields"],
                  files={"file": (doc.name, doc.bytes)})              # → 204
requests.post(f"{BASE}/v1/clients/{cid}/documents/finalize",
              headers=H, json={"document_ids": [t["document_id"] for t in prep["upload_targets"]]})

# 3. Submit for prep
sub = requests.post(f"{BASE}/v1/clients/{cid}/submissions",
                    headers=H, json={"tax_software": "Drake", "tax_year": 2025}).json()
save_expected_date(sub["expected_completion_at"])     # show your user the ETA

# 4. Later: poll, then ingest outputs
s = requests.get(f"{BASE}/v1/submissions/{sub['id']}", headers=H).json()
if s["status"] == "completed":
    for out in s["output_documents"]:
        pdf = requests.get(out["download_url"]).content
        store_in_your_app(out["filename"], pdf)

That's the entire integration — a few endpoints, no bespoke file plumbing on either side. See the Quickstart for curl versions of each call.