API reference

The full, always-current reference is the interactive OpenAPI/Swagger UI:

• Swagger UI: /v1/docs
• OpenAPI spec (JSON): /v1/openapi.json — import into Postman, generate clients, etc.

Both are public — you can read the full contract (every request/response schema and enum) without a key. You only need a key to try calls: use the Authorize button in Swagger to paste your mag_… key and run endpoints live.

Endpoint summary

All paths are under /v1. These require Authorization: Bearer mag_… (a firm key) except the docs endpoints. The partner-management endpoints under /v1/partner take a partner key (magp_…) instead and are listed in the Partner API.

Partner management (magp_ key)

Partners can also manage the firms they serve and those firms' keys. These take a partner key, not a firm key, and are documented in full — with their own Swagger — on the Partner API page.

Core request/response shapes

The essentials for the happy path, inline. The Swagger UI above has the complete, always-current contract for every field and endpoint.

Create a client — POST /v1/clients

// request  (friendly_name required; taxpayer_tin optional — dashes stripped, stored as digits)
{ "friendly_name": "Jane Q. Taxpayer", "taxpayer_tin": "123-45-6789" }
// 201 response  (taxpayer_tin is null when you don't send one)
{ "id": 812, "friendly_name": "Jane Q. Taxpayer", "taxpayer_tin": 123456789, "created_at": "2026-06-23T20:00:00Z" }

Prepare presigned uploads — POST /v1/clients/{id}/documents/prepare

// request
{ "documents": [ { "filename": "W2.pdf", "content_type": "application/pdf" } ] }
// 200 response — POST each file to its target (form-data), then finalize. Failures: prefer
// `failed_document_ids`; `failed_document_indices` is deprecated (kept for failures with no id).
{ "upload_targets": [ { "document_id": 456, "upload_url": "https://s3…", "fields": { "…": "…" } } ],
  "failed_document_ids": [], "failed_document_indices": [] }

Finalize presigned uploads — POST /v1/clients/{id}/documents/finalize

// request
{ "document_ids": [456] }
// 200 response — failures come back as `failed_document_ids` (the older `failed_document_indices` is deprecated)
{ "documents": [ { "id": 456, "filename": "W2.pdf", "download_url": "https://…" } ],
  "failed_document_ids": [], "failed_document_indices": [] }

Create a submission — POST /v1/clients/{id}/submissions

// request  (proconnect_* only when tax_software is "ProConnect")
{ "tax_software": "Drake", "tax_year": 2025 }
// 201 response — status starts at "processing"; full shape below

Deleting a client

DELETE /v1/clients/{id} archives the client — and it isn't only the client that changes. Any of that client's submissions still in flight are cancelled automatically, with cancellation_code: client_deleted, and each fires a submission.updated webhook. A submission a preparer has already picked up is left alone rather than cancelled.

So if you delete a client as cleanup, expect cancellation webhooks for its open work — don't treat them as failures.

Get a submission — GET /v1/submissions/{id} → the submission object (also delivered in the webhook):

{
  "id": 789, "client_id": 812, "status": "completed",
  "tax_year": 2025, "tax_software": "Drake",
  "is_resubmission": false, "resubmission_of": null,
  "expected_completion_at": "2026-06-26T20:00:00Z", "created_at": "2026-06-23T20:00:00Z",
  "input_documents":  [ { "id": 456, "filename": "W2.pdf", "download_url": "https://…" } ],
  "output_documents": [
    { "id": 999, "filename": "…_Return.DI5", "category": "tax_return", "download_url": "https://…" },
    { "id": 998, "filename": "workpapers.pdf", "category": "workpapers", "download_url": "https://…" },
    { "id": 997, "filename": "..._notes.txt",    "category": "review_notes", "download_url": "https://…" },
    { "id": 996, "filename": "..._notes.pdf",    "category": "review_notes", "download_url": "https://…" }
  ]
}

Note review_notes appears twice — the notes ship as a .txt and normally also as a rendered .pdf. See Submissions & statuses for every field, the status values, and cancellation codes.

Conventions

• IDs are integers (the resource's own id — client, submission, document). Pass them back exactly as received, in the path or request body.
• Timestamps are ISO‑8601 UTC.
• List responses are enveloped, not bare arrays: GET /v1/clients returns { "clients": [...], "next_cursor": … } and GET /v1/submissions returns { "submissions": [...], "next_cursor": … }.
• Pagination: the list endpoints are cursor-paginated — see Pagination below.
• Errors carry a stable machine-readable code alongside message — branch on code. See Errors & codes.
• Versioning: the surface is under /v1 and is currently 1.0.5 — one version line shared with the Partner API. It stays backwards compatible — additive changes bump the patch; anything we replace is deprecated and only removed in the next minor version. Truly breaking changes would ship under a new /v prefix. What landed in each version is in the Changelog.

Pagination

The list endpoints — GET /v1/clients and GET /v1/submissions — are cursor-paginated (keyset, not offset), returning newest-first pages. Two names are involved, and they are deliberately different:

So the loop is: first request has no cursor; each response hands you a next_cursor; pass that value back as ?cursor= on the next request; stop when next_cursor comes back null. The token is opaque — don't parse, construct, or persist it across schema changes; just echo it back.

# page 1 — no cursor
curl -s "${auth[@]}" "$BASE/v1/clients?limit=100"
# → { "clients": [...], "next_cursor": "eyJpZCI6..." }

# page 2 — feed the previous next_cursor back in as ?cursor=
curl -s "${auth[@]}" "$BASE/v1/clients?limit=100&cursor=eyJpZCI6..."
# → { "clients": [...], "next_cursor": null }   # last page

Because it's keyset pagination, paging is stable under inserts/deletes (no skipped or repeated rows the way offset pagination drifts), and there is no total-count — you page until next_cursor is null.