SOsoraban
Tax returns

Create a tax return

Changed on

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.

post/tax_returns

Request

Request body

entity_idinteger
external_entity_idstring
tax_yearinteger required
questionnaire_idinteger

Example request

{
  "tax_year": 2025
}

Response

The return was created and is awaiting a PDF.

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.

file_uploadedboolean

True when a PDF was included and is now being processed.

Changes