---
title: "List tax returns for an entity"
method: GET
path: "/tax_returns"
tags: ["Tax returns"]
---

# List tax returns for an entity

`GET /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/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the entity's tax returns, newest first. Not paginated.

Requires an `sk_` key; a legacy firm secret key returns `401` here.

## Query parameters

- `entity_id` integer
- `external_entity_id` string
- `tax_year` integer

## Response `200`

The entity's tax returns.

- TaxReturn[]
  - `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.

## Other responses

- `401`: This endpoint only accepts an `sk_` API key. A legacy firm secret key is rejected here.
- `403`: Missing or invalid API key, or the record does not belong to your firm.
- `404`: No such record for this firm.
- `422`: The request was understood but rejected. See `error` for the reason.

## Changes

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

[Operation history](https://skmtc.dev/soraban/apis/soraban-private-api/changes/tax_returns/get.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)