SOsoraban
Tax returns

List tax returns for an entity

Changed on

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

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

get/tax_returns

Request

Query parameters

entity_idinteger

The entity's Soraban id. Required unless external_entity_id is given.

external_entity_idstring

Your own identifier for the entity. Required unless entity_id is given.

tax_yearinteger
Example:2025

Only returns for this tax year.

Response

The entity's tax returns.

idinteger
tax_return_namestring nullable

Taken from the uploaded PDF's filename once processing finishes.

tax_yearinteger nullable
entity_idinteger
entity_namestring nullable
external_entity_idstring nullable
entity_typestring nullable
client_namestring nullable
client_emailstring nullable
assigned_tostring nullable
assigned_to_emailstring nullable
questionnaire_idinteger 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_statusstring nullable

The status as shown in the Deliver table, which folds in signature and payment progress.

draft_statusstring nullable

Set when the return is a draft awaiting client approval.

all_signedboolean
all_paidboolean nullable
can_mark_as_filedboolean
signed_signature_countinteger
total_signature_countinteger
paid_payment_countinteger

Counts paid vouchers plus the invoice, if there is one.

total_payment_countinteger
outstanding_voucher_countinteger
has_paymentboolean
payment_statusstring nullable
payment_amountnumber nullable

In dollars.

k1_distribution_statusstring nullable
reminder_disabledboolean
last_sent_atstring date-time nullable
last_reminder_sent_atstring date-time nullable
sent_to_documents_atstring date-time nullable
created_atstring date-time
updated_atstring date-time
linkstring nullable

Path within the Soraban app, relative to the firm's subdomain.

Changes