---
title: "Create a submission for prep"
method: POST
path: "/v1/clients/{client_id}/submissions"
tags: ["Submissions"]
---

# Create a submission for prep

`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

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.

## Headers

- `Idempotency-Key` string

## Request body

- CreateSubmissionRequest
  - `proconnect_client_id` string, nullable: Required when tax_software is ProConnect: the numeric clientId from the ProConnect return URL.
  - `proconnect_engagement_id` string, 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_year` integer, required

## Response `201`

Created

- Submission
  - `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_reason` string, nullable: Human-readable reason (present only when status is 'cancelled').
  - `client_id` integer
  - `created_at` string, date-time
  - `expected_completion_at` string, date-time, nullable
  - `id` integer
  - `input_documents` Document[]
    - `category` 'tax_return' | 'workpapers' | 'review_notes', nullable: For output documents only: 'tax_return' (the tax-software return file, e.g. a Drake .DI5 / UltraTax .csd), 'workpapers' (the workpapers PDF), or 'review_notes' (the reviewer's notes, delivered as a .txt and a rendered PDF). Absent on input documents and internal-only outputs.
    - `download_url` string, nullable
    - `filename` string
    - `id` integer
    - `state` 'uploading' | 'uploaded' | 'submitted': Lifecycle state of the document: 'uploading' (presigned, not yet confirmed), 'uploaded' (available for the next submission), or 'submitted' (attached to a submission).
  - `is_resubmission` boolean: True when this submission inherited from a prior completed one for the same client + tax year.
  - `is_sandbox` boolean: 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.
  - `output_documents` Document[]
    - `category` 'tax_return' | 'workpapers' | 'review_notes', nullable: For output documents only: 'tax_return' (the tax-software return file, e.g. a Drake .DI5 / UltraTax .csd), 'workpapers' (the workpapers PDF), or 'review_notes' (the reviewer's notes, delivered as a .txt and a rendered PDF). Absent on input documents and internal-only outputs.
    - `download_url` string, nullable
    - `filename` string
    - `id` integer
    - `state` 'uploading' | 'uploaded' | 'submitted': Lifecycle state of the document: 'uploading' (presigned, not yet confirmed), 'uploaded' (available for the next submission), or 'submitted' (attached to a submission).
  - `resubmission_of` integer, nullable: Id of the prior submission this one resubmits, or null.
  - `status` 'received' | 'processing' | 'completed' | 'cancelled'
  - `tax_software` string, nullable
  - `tax_year` integer

## Other responses

- `400`: Bad request
- `404`: Not found
- `409`: `active_submission_exists` or `documents_still_uploading`. Also returned for an Idempotency-Key conflict — reused for a different request (`idempotency_key_reuse`), or the original request is still running (`idempotency_request_in_progress`)
- `429`: Rate limited — retry after the `Retry-After` delay

---

[API](https://skmtc.dev/magnetictax/apis/magnetic-integrations-api.md) - [All operations](https://skmtc.dev/magnetictax/apis/magnetic-integrations-api/llms.txt) - [OpenAPI document](https://skmtc.dev/magnetictax/apis/magnetic-integrations-api/revisions/11854873aa89?raw)