MAmagnetictax
Submissions

Create a submission for prep

Creates a submission from the client's uploaded input documents. If the client already has a completed submission for the same tax year, this one is automatically treated as a resubmission (is_resubmission: true, resubmission_of set) — upload any new/corrected documents first.

post/v1/clients/{client_id}/submissions

Request

  • Base URL
    https://api.magnetictax.com
  • URL
    https://api.magnetictax.com/v1/clients/{client_id}/submissions
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring

Optional. Retry a write with the same key and you get the ORIGINAL response back instead of the work happening twice — so a request that timed out is safe to repeat. Use one key per logical operation (a UUID), and reuse it for every retry of that operation. Keys are scoped to your API key and honoured for 24 hours. A replayed response carries the Idempotent-Replayed: true header — the body is byte-identical to the original, so that is the only way to tell stored work from fresh work. Reusing a key with a different request body returns 409 idempotency_key_reuse; replaying while the first request is still running returns 409 idempotency_request_in_progress. An empty header, or one over 255 characters, is rejected with 400 invalid_idempotency_key — omit it entirely to opt out.

Request body

proconnect_client_idstring nullable

Required when tax_software is ProConnect: the numeric clientId from the ProConnect return URL.

proconnect_engagement_idstring nullable

Required when tax_software is ProConnect: the engagementId UUID from the ProConnect return URL.

tax_software'UltraTax' | 'ProConnect' | 'Drake' | 'Axcess' | 'Lacerte' required

Which tax software to prepare in. Case-sensitive; must be one of the enum values.

tax_yearinteger required

Example request

{
  "tax_software": "Drake",
  "tax_year": 2025
}

Response

Created

cancellation_code'encrypted_file' | 'unsupported_file' | 'empty_file' | 'outdated_tax_software_file' | 'tax_software_input_mismatch' | 'multiple_tax_software_files' | 'unextractable_zip' | 'mismatched_client' | 'proconnect_link_failed' | 'axcess_client_missing_ssn' | 'unsupported_return_type' | 'cancelled_by_firm' | 'client_deleted' | 'other' nullable

Stable, machine-readable cancellation reason (present only when status is 'cancelled').

cancellation_reasonstring nullable

Human-readable reason (present only when status is 'cancelled').

client_idinteger
created_atstring date-time
expected_completion_atstring date-time nullable
idinteger
is_resubmissionboolean

True when this submission inherited from a prior completed one for the same client + tax year.

is_sandboxboolean

Present and true ONLY for submissions created in a sandbox organization (never worked by a preparer, no firm emails, no internal notifications). Omitted entirely for normal submissions.

resubmission_ofinteger nullable

Id of the prior submission this one resubmits, or null.

status'received' | 'processing' | 'completed' | 'cancelled'
tax_softwarestring nullable
tax_yearinteger

Example response

{
  "client_id": 42,
  "id": 88,
  "input_documents": [
    {
      "id": 7
    }
  ],
  "output_documents": [
    {
      "id": 7
    }
  ],
  "resubmission_of": 788
}

Changes

No recorded changes to this operation across all 1 revision of this API.