leadsheets
field on the client’s binder, and record sign-offs with the
createDocumentMessage mutation (a sign-off is an activity document message
with markType: "signoff", see Document messages).
Leadsheets are reached through the me query resolved as a
WorkspaceUser, so reading them and recording sign-offs both require a
workspaceToken (see Authentication). All
requests go to:
There is no top-level
leadsheets query. Leadsheets belong to a client’s
binder, so you read them through
me { ... on WorkspaceUser { workspace { clients(filters: { ids: [$clientId] }) { binder { leadsheets(taskId: $taskId) { ... } } } } } }.
The workspaceToken already identifies the workspace.A leadsheets tree is the output of a
TAX_PREP (or TAX_REVIEW) background
task. Pass that task’s taskId to leadsheets(taskId:) to read the exact tree
that run produced. See Tasks for how to start and poll a run, and
Tax prep for the TaskTaxPrepResult shape (whose reviewItems
are the same review items surfaced here as LeadsheetSheetIssue).The Leadsheets type
The top-level leadsheets container for one client and one task run.
The leadsheets container ID.
The background task that produced this leadsheets tree. Its
type is TAX_PREP or TAX_REVIEW; its status tells you whether the tree is
still being built (RUNNING) or ready to read (COMPLETED).The binder path the leadsheets container lives at.
The per-form leadsheets. Pass
sheets(id: $id) to fetch a single leadsheet by
ID; omit the argument to list them all. See Leadsheet.Total number of unresolved issues across every sheet. Use this as a quick
“needs attention” count before paging into
sheets.The return form this run targeted, for example
"F1040". This is a String
here, not the ReturnType enum (see clients).The tax year this run targeted, for example
2025. Nullable: older runs may not
record it.The Leadsheet type
One form’s leadsheet: its fields, the issues the run flagged on it, and the
sign-offs reviewers have recorded against it.
The leadsheet ID. Pass it to
Leadsheets.sheets(id:) to fetch this sheet alone.
The ID encodes the form name and shard index (for example
leadsheets/schedule_b/0).The tax form this leadsheet covers, for example
"Schedule B" or "Form 1040".The grouping category the binder assigns this form to (for example
income or
deductions).Issue counts broken down by severity. See
IssueCountBySeverity.The issues the run flagged on this sheet. See
LeadsheetSheetIssue.Sign-off messages reviewers have recorded against this sheet. Each entry is a
DocumentMessage with markType: "signoff" (see
Sign off on a sheet or row). A sheet with no
sign-offs returns an empty array.The form’s fields, each with its rows of values, prior-year values, source
anchors, and traces. See
LeadsheetField.The LeadsheetSheetIssue type
One issue the run flagged on a sheet: a mismatch, a missing form, a value the
extractor was not confident about, and so on.
The issue’s unique identifier.
The rule that fired this issue. Stable across runs of the same rule set, so you
can use it to deduplicate or track an issue across re-runs.
How blocking the issue is:
CRITICAL, HIGH, MEDIUM, or LOW.A machine-readable grouping, for example
value_mismatch or missing_form.A short, human-readable summary of the issue.
A longer explanation. Nullable: some rules only emit a
title.The evidence the rule used, for example the binder text the value was extracted
from.
What the rule expected to find, when relevant.
What the rule actually found, when relevant.
The leadsheet field path the issue is anchored to, when the issue is tied to a
specific field.
A reference to the line on the form, when relevant.
A reference to the column on the form, when relevant.
A note about how the issue’s field was mapped to the form, when the mapping is
ambiguous.
The ID of the binder message (annotation, flag, or sign-off) linked to this
issue, when one exists.
Whether the issue has been resolved. An issue is resolved when the underlying
document message is hidden (for example a reviewer dismissed the flag, or a
sign-off covered it). Refetch the leadsheets query after a
sign-off to recompute this.
The LeadsheetField type
A single field on a form, with one row per occurrence (for example one row per
1099-INT under “Interest Income”).
The field ID.
The rows for this field. See
LeadsheetFieldRow.The LeadsheetFieldRow type
One row of a field: its value, the prior-year value, the source anchor in the
binder, the trace that explains where the value came from, and the issues and
sign-offs tied to this row.
The row ID.
The path of this field on the form, for example
interest_income.total.The value extracted for this row, for example
"428.00". Nullable when the row
exists for layout but carries no value.The value the same field held in the prior year, when prior-year data is
available.
The bounding box in the binder subdocument this value was extracted from. See
SubDocBBox.The trace explaining how this row’s value was sourced and reconciled. See
LeadsheetTrace.Document messages (flags, notes) anchored to this row. Each is a
DocumentMessage; see Document messages.Sign-off messages reviewers have recorded against this row. Each is a
DocumentMessage with markType: "signoff". See
Sign off on a sheet or row.The LeadsheetTrace type
The reasoning and source citations behind a row’s value: why the extractor chose
this value, and which binder subdocuments (and pages, and bounding boxes) it
came from.
A human-readable explanation of how the value was sourced and reconciled.
The binder sources this value was taken from. See
LeadsheetTraceSource.The LeadsheetTraceSource type
One source contributing to a trace: a subdocument, a label, an amount, and a
page-level bounding box.
The binder subdocument this source came from.
A human-readable label for the source, for example
"1099-INT from Acme Broker".The amount this source contributed, as a string, for example
"42.00".The page number inside the subdocument, when relevant.
The bounding box on the page that pins this source. See
SubDocBBox.The SubDocBBox type
A bounding box that pins a value or source to a specific region on a specific
page of a binder subdocument.
Top edge of the box, in page pixels.
Left edge of the box, in page pixels.
Bottom edge of the box, in page pixels.
Right edge of the box, in page pixels.
The page this box is on, 1-indexed.
The subdocument this box belongs to.
The IssueCountBySeverity type
Issue counts bucketed by severity, used by Leadsheet.issueCount.
Number of
CRITICAL issues.Number of
HIGH issues.Number of
MEDIUM issues.Number of
LOW issues.The DocumentMessage type
A document message is the underlying write surface for annotations, flags, and
sign-offs on binder documents and leadsheet rows. A sign-off is a DocumentMessage
with type: "activity" and markType: "signoff".
The message ID.
The workspace the message belongs to.
The binder path the message is anchored to. For a sign-off on a subdocument or
leadsheet row, this is the subdocument’s path.
annotation, activity, or missing_document. Sign-offs use activity.The kind of mark:
signoff, flag, note, and so on. The schema types this as
a free-form String; the web app treats signoff as the sign-off mark.A JSON object pinning the message to a location. For a sign-off it carries
{ page, coordinates: { x, y }, level, user_role }, where level is the
reviewer’s sign-off level and user_role is their workspace role.An optional content path.
An optional body, for notes and replies.
When the message was soft-hidden (for example when a sign-off is undone).
null
while the message is visible.The user who hid the message, when applicable.
The user who created the message.
When the message was created.
When the message was last updated.
Reply threads on the message.
Users tagged on the message.
A sign-off is a
DocumentMessage with type: "activity" and
markType: "signoff". This page documents only the two operations the review
sign-off flow uses: createDocumentMessage and
hideDocumentMessage. The wider DocumentMessage API
(annotations, flags, threads, hide/unhide on binder documents) is documented
separately.Read a client’s leadsheets
Readbinder.leadsheets(taskId:) to get the leadsheets tree a specific run
produced. Pass the taskId of the TAX_PREP or TAX_REVIEW task you want the
tree for; omit it to read the client’s most recent tree.
Arguments
The client whose leadsheets you want to read. Pass it via
filters.ids on
clients.Optional. The
TAX_PREP or TAX_REVIEW task whose tree you want. Omit it to
read the client’s most recent tree.Optional. Pass it on
Leadsheets.sheets(id:) to fetch a single leadsheet by ID
instead of listing them all.Sign off on a sheet or row
A sign-off is acreateDocumentMessage call with type: "activity" and
markType: "signoff", anchored to the subdocument path you are signing off on.
The anchorPoint carries the reviewer’s level and user_role so the UI can
render the sign-off with the right label.
Input: CreateDocumentMessageInput
The client whose binder you are signing off in.
The binder path you are signing off on. For a subdocument or leadsheet row
sign-off, this is the subdocument’s path (the same value you read as
LeadsheetFieldRow.id or LeadsheetSheetIssue is anchored to).activity for a sign-off (the only value the sign-off flow uses)."signoff" for a sign-off.A JSON object pinning the sign-off. The web app uses
{ "page": 1, "coordinates": { "x": 0, "y": 0 }, "level": <number>, "user_role": "<role>" },
where level is the reviewer’s sign-off level (for example 2 for an l2
reviewer) and user_role is their workspace role.An optional note attached to the sign-off.
The task the sign-off belongs to, when relevant.
Workspace users to tag on the sign-off.
Returns: DocumentMessage!
The created DocumentMessage. Its id is what you
pass to hideDocumentMessage to undo the sign-off.
Undo a sign-off
Undoing a sign-off is a soft-hide of the sign-offDocumentMessage. The
sign-off row stays in history (with hiddenAt set), and the leadsheets query’s
resolved / issueCount recomputation backs it out.
Input
The ID of the sign-off
DocumentMessage to undo (the id returned by
createDocumentMessage).Returns: DocumentMessage!
The hidden DocumentMessage, with hiddenAt and
hiddenBy now populated.
Exporting leadsheets
TheLeadsheetsExportFormat enum is used by the workpaper bundle generator
(generateWorkpaperBundle), not by the leadsheets query itself. When you
generate a workpaper bundle and want leadsheets included, pass
includeLeadsheets: true and pick a format.
generateWorkpaperBundle mutation and its GenerateWorkpaperBundleInput
input are documented on the Workpapers page. This page lists
LeadsheetsExportFormat only to anchor where the enum is actually consumed.