Changelog

Every released version of the Integrations API, newest first.

One API, one version. Everything under /v1 is the Integrations API. The Partner API is a subset of it — the endpoints for managing the firms you serve and their API keys — documented separately because it has a different reader and a different credential, but shipping on the same surface under the same version number. Entries below are tagged Partner API when they concern that subset; everything else is the rest of the API.

Versioning is semantic and explained in Deprecations: additive, backwards‑compatible changes bump the patch; anything we replace is deprecated first and only removed in the next minor. The current version is 1.0.8, reported at info.version in both specs.

For what's coming rather than what's shipped, see the Roadmap.

1.0.8

• Partner API — start onboarding on your own platform, and get the user back. A firm you invite now answers your management request on a screen of its own, and PATCH /v1/partner/onboarding sets the return_url we send them to afterwards, with status (accepted, declined or revoked) and organization_id appended. Previously the only way in was the invitation email and there was no way out, so a flow that began on a partner's platform ended somewhere else. POST /v1/partner/firms and the single-firm read now also return an onboarding_url — the link to send the admin to, instead of waiting on an email you can't see. Treat it as a credential: whoever opens it creates the firm's admin account. See Onboarding from your own platform.
• A firm can now decline or end your management, and you're told either way. Two new signed events, firm.management_declined and firm.management_revoked, join firm.management_accepted on the partner webhook — see Webhooks.
• declined_at on a firm. Declining leaves the status pending (it means "not now", and you may ask again), so this timestamp is the only way to tell a firm that hasn't answered from one that said no — the difference between waiting and following up.
• A revoked firm stays in GET /v1/partner/firms. It used to vanish from every read while carrying management_status: "revoked" that nothing could return, making a revocation indistinguishable from a firm that never existed. It is now listed and readable with that status; every operation on it still fails, and its API keys stop working.

1.0.7

• Partner API — rehearse the acceptance handshake against a sandbox firm. A sandbox firm is auto-accepted, which quietly skipped the middle of real onboarding: nothing to accept, so no firm.management_accepted fired and key issuance never refused — leaving the two branches an integration most needs to handle untestable except against real firms. POST /v1/partner/firms now takes auto_accept: false (sandbox only) to create one that begins pending, and POST /v1/partner/firms/{org_id}/sandbox/accept performs the transition a firm admin performs in the app, firing the same signed event. Refused with 403 sandbox_only on a real firm — only its own admin can accept its management. See Rehearsing the acceptance step.
• New error code firm_revoked (409): a revoked partnership can't be accepted.
• GET /v1/partner/firms now names a firm you just created. The listing resolves names from a cached bulk lookup, so a brand-new firm could read back name: null for minutes — the one firm you most need to identify when reconciling a timed-out onboarding. Names the listing can't resolve are now fetched directly.

1.0.6

• Partner API — a console-issued management key can now onboard firms. partner.firms.write was added in 1.0.5, but the partner console only ever issued partner.read + partner.keys.write, so no key it produced could call the onboarding endpoints. A management key now carries all three; View only is unchanged. Nothing about the endpoints or the scopes themselves changed — see Partner API.

1.0.5

• Idempotency on document uploads now compares file contents and filenames, not just the request's size. Reusing a key with a different file returns 409 idempotency_key_reuse instead of replaying the first upload's response — previously two same-sized files could be treated as the same request. Legitimate retries still replay unchanged.

• Re-inviting someone at a different role now takes effect. Inviting an address that already has a pending invitation returns 200 and sends nothing when the role matches; when it differs, the pending invitation is withdrawn and the new one sent, so correcting a mistaken admin invite down to member actually applies.

• Sandbox firms. POST /v1/partner/firms takes sandbox: true for a throwaway firm — auto-accepted, no admin needed, no email sent, submissions never reach a preparer. Five per partner. Onboarding is now testable without creating real organizations.

• Delete a firm you onboarded. DELETE /v1/partner/firms/{org_id} removes the organization and our record of it, while the firm is still yours to remove — once it has accepted your management it's theirs (firm_already_accepted).
• Inviting an address that already has a pending invitation returns 200 and sends nothing, instead of a second email.

• GET /v1/partner/webhook no longer returns webhook_signing_secret. Setting the URL now rotates the secret and returns it once, matching how per-key signing secrets have always worked.

• Partner API — onboard firms programmatically. POST /v1/partner/firms creates a firm and invites its admin; POST /v1/partner/firms/{org_id}/invitations invites anyone else. Both need the new partner.firms.write scope. It is separate from partner.keys.write — neither implies the other — and the partner console includes it on a management key, since onboarding means creating the firm and then issuing its key.

• Both accept an Idempotency-Key, like every other write, and you should send one: they provision a real organization and send email, so a retried timeout without one can leave a duplicate. See Retrying safely.

1.0.4

• Idempotency-Key on every write. Send the header on any POST/PATCH/DELETE under /v1 and a retry with the same key returns the original response instead of doing the work twice — so a request that times out is safe to repeat. Optional: omit the header and nothing changes. Reusing a key for a different request returns 409 idempotency_key_reuse; replaying while the original is still running returns 409 idempotency_request_in_progress; an empty key, or one over 255 characters, returns 400 invalid_idempotency_key (omitting the header entirely is how you opt out). A replayed response carries Idempotent-Replayed: true, since the body is byte-identical to the original. All three are in Errors & rate limits, and endpoints that already returned 409 can now return it for these reasons too. See Retrying safely.

1.0.3

• Partner API — new. A subset of the API at /v1/partner, for managing firms and their keys programmatically instead of through the console. It has its own docs and Swagger and its own credential: a partner key (magp_…), which manages firms and keys and can never read or write a firm's client data. You can list the firms you manage; issue, rename, re-point and revoke a firm's API keys; and read or set your partner-level onboarding webhook.

1.0.2

• Cursor pagination on the list endpoints — limit and cursor go in, next_cursor comes back, null on the last page. See Pagination.
• Stable error codes. Every error carries a machine-readable code alongside message, so you branch on the code instead of matching message text. Full list in Errors & rate limits.
• Per-key webhook signing secrets. A key's signing secret is issued with its webhook URL and rotated whenever that URL changes; the new secret is shown once. See Webhooks.
• Webhook delivery history per API key — which events fired, where, and whether they landed. Firms see their own in the portal (Preferences → Self-managed API); partners see each key's on its detail page in the partner console.
• content_md5 on document prepare, so a corrupted upload is rejected by S3 rather than accepted. See Uploading documents.
• failed_document_ids on prepare and the direct multipart upload, reporting failures by document id instead of by position. failed_document_indices is deprecated and removed in 1.1.0.
• SubmissionSummary — list responses return a reduced submission (no document arrays); fetch a single submission for the full object.
• Sandbox returns the tax software's native return file (e.g. a Drake .DI5), so a sandbox download exercises the same handling as a real one. See Sandbox testing.
• ProSeries removed from the accepted tax_software values.

1.0.1

• failed_document_ids on finalize, replacing the positional failed_document_indices (deprecated, removed in 1.1.0).

1.0.0

Initial /v1 release:

• Clients — create, list, read, update, delete.
• Document upload, both the presigned flow and direct multipart.
• Submissions and statuses, including cancellation.
• The sandbox, for exercising the full loop without a real preparer.
• submission.updated webhooks.
• The partner platform — console-managed at this point; the Partner API subset arrived in 1.0.3.