Magnetic Integrations API

Send us documents through our API, we prepare the tax return, and you get the finished documents back.

The API is client-centric: you create a client, attach documents to it, then create a submission for prep. You track the submission until it's completed and download the output documents.

• Base URL: https://api.magnetictax.com
• Support: reach us through your Magnetic support channel (partners: your shared Slack channel) — for paused access, a submission you need stopped, or anything the docs don't answer.
• Interactive API reference (Swagger): /v1/docs · OpenAPI spec at /v1/openapi.json
• Authentication: a per-organization API key, sent as Authorization: Bearer mag_... (see Authentication)
• Every integration can test against a sandbox — a sandbox API key (self-managed firms) or a sandbox org (partners) — so submissions never reach a real preparer (see Sandbox testing).

Who uses this API

Same API, two audiences:

• A firm using its own API ("self-managed API") — a firm that wants to send its own clients to Magnetic programmatically. A firm admin creates an API key for the firm in the portal and integrates against it. That key only ever acts for that one firm. Standard pricing applies — it's the same whether you submit in the app or through the API.
• A partner — an integrator that manages multiple firms on their behalf (e.g. a software vendor). A partner is a multi-firm user with the extra ability to create/manage firm organizations and issue keys for the firms it manages. Creating firms is done in the console; listing them and managing their keys can also be done through the Partner API. See Partners.

The endpoints below are the same for both; what differs is the key: a firm's own key acts for that firm, and a partner-issued key carries partner attribution. If you manage more than one firm, become a partner.

The flow at a glance

sequenceDiagram
    autonumber
    participant App as Your application
    participant API as Magnetic API
    participant Prep as Tax prep
    App->>API: POST /v1/clients
    API-->>App: client (id: 812)
    App->>API: upload documents (presigned)
    API-->>App: documents (ids: 456, …)
    App->>API: POST /v1/clients/{id}/submissions
    API-->>App: submission (id: 789) + expected_completion_at
    API->>Prep: queue for preparation (async, ~3 days)
    Prep-->>API: output documents ready
    Note over App,API: Recommended: register a webhook, we notify you
    API-->>App: POST webhook: submission.updated (status: completed)
    opt Fallback when you can't receive webhooks
        App->>API: GET /v1/submissions/{id}
        API-->>App: status: completed + output_documents[]
    end
    App->>API: GET download_url → finished return

Processing is asynchronous (typical turnaround ~3 days). Each submission returns an expected_completion_at. Webhooks are the recommended way to track a submission's status — register a callback URL and we sign and POST a submission.updated event on every status change, so you're notified the moment a return is ready. Polling GET /v1/submissions/{id} is a supported fallback for when you can't receive webhooks.

New here? Start with the Quickstart.