---
title: "Create a tax return"
method: POST
path: "/tax_returns"
tags: ["Tax returns"]
---

# Create a tax return

`POST /tax_returns`

## Request

- Base URL: `https://api.soraban.com`
- URL: `https://api.soraban.com/tax_returns`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/soraban/apis/soraban-private-api/docs/tax_returns/post.ts> (a function with typed inputs; its response is checked against the schema)

Requires an `sk_` key with the `write_enhanced` scope.

Creates a tax return for an entity. There are two ways to use this:

- **Without a file.** The return is created in `awaiting_upload` status and appears in Deliver ready for someone to drop the PDF in. Responds `201`.
- **With a file.** Send the PDF as a multipart `file` field. The return is created in `processing` status and the PDF is analysed in the background. Responds `202`.

Either way the response carries the return's `id` immediately, so you can store it and poll `GET /tax_returns/{id}` for status.

The return is named after the uploaded PDF once processing finishes; you cannot set the name through this endpoint.

## Request body

- object: Use JSON when creating a return without a PDF. Identify the entity with `entity_id` or `external_entity_id`.
  - `entity_id` integer
  - `external_entity_id` string
  - `tax_year` integer, required
  - `questionnaire_id` integer

## Response `201`

The return was created and is awaiting a PDF.

- TaxReturnCreation: Field names match the tax return webhooks, so a polled return and an event payload can be correlated directly.
  - `id` integer
  - `tax_return_name` string, nullable: Taken from the uploaded PDF's filename once processing finishes.
  - `tax_year` integer, nullable
  - `entity_id` integer
  - `entity_name` string, nullable
  - `external_entity_id` string, nullable
  - `entity_type` string, nullable
  - `client_name` string, nullable
  - `client_email` string, nullable
  - `assigned_to` string, nullable
  - `assigned_to_email` string, nullable
  - `questionnaire_id` integer, nullable
  - `status` 'awaiting_upload' | 'action_required' | 'error' | 'finished' | 'invoice_paid' | 'processing' | 'sending' | 'sent' | 'filed', nullable: `awaiting_upload` means the return was created through the API and is waiting for its PDF.
  - `current_status` string, nullable: The status as shown in the Deliver table, which folds in signature and payment progress.
  - `draft_status` string, nullable: Set when the return is a draft awaiting client approval.
  - `all_signed` boolean
  - `all_paid` boolean, nullable
  - `can_mark_as_filed` boolean
  - `signed_signature_count` integer
  - `total_signature_count` integer
  - `paid_payment_count` integer: Counts paid vouchers plus the invoice, if there is one.
  - `total_payment_count` integer
  - `outstanding_voucher_count` integer
  - `has_payment` boolean
  - `payment_status` string, nullable
  - `payment_amount` number, nullable: In dollars.
  - `k1_distribution_status` string, nullable
  - `reminder_disabled` boolean
  - `last_sent_at` string, date-time, nullable
  - `last_reminder_sent_at` string, date-time, nullable
  - `sent_to_documents_at` string, date-time, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `link` string, nullable: Path within the Soraban app, relative to the firm's subdomain.
  - `file_uploaded` boolean: True when a PDF was included and is now being processed.

## Other responses

- `202`: The return was created and the PDF is being processed.
- `403`: The key lacks the `write_enhanced` scope, or the record does not belong to your firm.
- `404`: No such record for this firm.
- `422`: Invalid request. Includes a missing or out-of-range `tax_year`, an entity with no assigned advisor, a questionnaire that belongs elsewhere, or a file that is not a valid PDF or is over 50 MB.
- `503`: The PDF could not be stored, or processing could not be started. Safe to retry.

## Changes

- **2026-11-03** `1c230fa547ad`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/soraban/apis/soraban-private-api/changes/tax_returns/post.md)

---

[API](https://skmtc.dev/soraban/apis/soraban-private-api.md) - [All operations](https://skmtc.dev/soraban/apis/soraban-private-api/llms.txt) - [OpenAPI document](https://skmtc.dev/soraban/apis/soraban-private-api/revisions/1c230fa547ad?raw)