A client’s binder is the container for the documents Filed has ingested for
that client. It holds the uploaded files (subdocuments), the missing-item
checklist the run produces, message counts for quick badges, and a search
surface across bookmarks, annotations, and document contents. Read it with the
binder field on a client.
The binder is reached through the me query resolved as a
WorkspaceUser, so every binder operation requires a workspaceToken (see
Authentication). All requests go to:
https://router.apps.filed.com/graphql
There is no top-level binder query. The binder belongs to a client, so you
read it through
me { ... on WorkspaceUser { workspace { clients(filters: { ids: [$clientId] }) { binder { ... } } } } }.
The workspaceToken already identifies the workspace, so you never pass a
workspace ID to read the binder.
The Binder type
The top-level binder container for one client.
type Binder {
id: ID!
clientId: ID!
subdocuments(filter: SubDocumentsFilter): [SubDocument!]!
createdAt: String!
updatedAt: String!
missingItems(filter: BinderMissingItemsFilter): [BinderMissingItem!]!
openMissingItemsCount: Int!
messageCounts: BinderMessageCounts!
search(query: String!, limit: Int = 20): BinderSearchResults!
leadsheets(taskId: ID): Leadsheets
}
The binder’s unique identifier.
The client this binder belongs to.
The files filed in the binder. Pass a SubDocumentsFilter to narrow to
unreviewed, flagged, or files under one parent document. See
List the files in a binder. When the binder was created (ISO 8601 timestamp).
When the binder was last updated (ISO 8601 timestamp).
The missing-item checklist for this binder. Pass a BinderMissingItemsFilter
to narrow by status. See List missing items. The number of missing items in the OPEN status. Use this as a quick badge
count without fetching the full missingItems list.
Search across bookmarks, annotations, marks, and document contents. See
Search the binder. The leadsheets tree for a TAX_PREP or TAX_REVIEW run. Pass the run’s
taskId to read that run’s tree; omit it to read the most recent tree.
Leadsheets are documented separately on
Leadsheets and review; this page
does not re-document them. The SubDocument type
One file in a binder. A subdocument is one logical document extracted from an
uploaded parent (for example one 1099-INT inside a larger uploaded packet).
type SubDocument {
id: ID!
clientId: ID!
parentDocumentId: String!
fileName: String!
pageRange: [Int!]!
type: String!
issuer: String!
taxYear: Int!
status: String!
category: String
order: Int!
createdAt: String!
updatedAt: String!
parentDocument: ParentDocument
canonicalPath: String
bucket: String
}
The client this subdocument belongs to.
The ID of the parent document this subdocument was extracted from.
The file name, for example 1099-INT-Acme-Broker.pdf.
The pages inside the parent document this subdocument covers, 1-indexed.
The document type the extractor classified this as, for example 1099-INT or
W-2.
The issuer or payer named on the document, for example Acme Broker.
The tax year this document covers, for example 2025.
The ingestion or review status of this subdocument, for example ingested or
reviewed.
The binder grouping category, when one has been assigned. Nullable: some
subdocuments are uncategorized until a reviewer files them.
The sort order of this subdocument within the binder.
When the subdocument was created (ISO 8601 timestamp).
When the subdocument was last updated (ISO 8601 timestamp).
The parent document this subdocument was extracted from. See
ParentDocument. The path to the canonical.json file in the per-client git repo. Populated
when a tax-prep run has picked up this subdocument; null until then.
The use-case bucket the subdocument lives in on disk, for example
source_docs, prior_year_docs, or current_year_drafts. null when the
subdocument has not yet been migrated into a bucket.
The ParentDocument type
The original uploaded document a subdocument was extracted from. Carries the
file URL and per-page render URLs.
type ParentDocument {
id: ID!
fileName: String!
contentType: String!
url: SignedPath!
subdocPages: [SubdocPage!]!
}
type SubdocPage {
pageNumber: Int!
imageUrl: SignedPath
markdownUrl: SignedPath
}
The parent document’s unique identifier.
The original uploaded file name.
The MIME type, for example application/pdf.
A signed URL for downloading the original file. SignedPath is
{ filePath: String!, url: String! }.
Per-page render URLs for the parent document: one image URL and one markdown
URL per page, both signed and time-limited.
The BinderMissingItem type
One item on the missing-document checklist the binder produces: a form the run
expected to find but did not, with a severity, a reason, and a status you can
move between OPEN, IGNORED, and RESOLVED.
type BinderMissingItem {
id: ID!
binderId: ID!
item: String!
formType: String
issuer: String
taxYear: Int
severity: ChecklistItemSeverity!
reason: String!
status: ChecklistItemStatus!
category: String
createdAt: String!
updatedAt: String!
}
enum ChecklistItemSeverity {
CRITICAL
MEDIUM
LOW
}
enum ChecklistItemStatus {
OPEN
IGNORED
RESOLVED
}
The binder this missing item belongs to.
The missing item, for example 1099-INT or W-2 from Acme.
The form type expected, when the checklist is form-specific.
The issuer the run expected to find, when relevant.
The tax year the missing item applies to.
How blocking the missing item is: CRITICAL, MEDIUM, or LOW.
Why the run flagged this as missing, for example
Expected a 1099-INT from Acme Broker but no matching document was found in the binder.
The current status: OPEN (still needs the document), IGNORED (a reviewer
dismissed it via ignoreBinderMissingItem), or
RESOLVED (the document was later found and filed). A grouping category, when one has been assigned.
When the missing-item record was created (ISO 8601 timestamp).
When the missing-item record was last updated (ISO 8601 timestamp).
The BinderMessageCounts type
Open missing-item and notes counts. Use these for quick badge rendering without
fetching the full missingItems list.
type BinderMessageCounts {
openMissing: Int!
notes: Int!
}
The number of missing items in the OPEN status (same value as
Binder.openMissingItemsCount).
The number of open annotation notes on the binder. See
Document messages for the annotation API. The BinderSearchResults type
The result of Binder.search: four buckets of hits, one per search surface
(bookmarks, annotations, marks, and document contents).
type BinderSearchResults {
bookmarks: [BookmarkSearchHit!]!
annotations: [BinderMessageSearchHit!]!
marks: [BinderMessageSearchHit!]!
contents: [BinderContentSearchHit!]!
}
Subdocuments whose file name, issuer, type, or category matched the query. See
BookmarkSearchHit. annotations
[BinderMessageSearchHit!]!
Binder messages (annotations and notes) whose body or expression matched the
query. See BinderMessageSearchHit. marks
[BinderMessageSearchHit!]!
contents
[BinderContentSearchHit!]!
Hits inside document contents, with the matching field names, values, and
bounding boxes. See BinderContentSearchHit. The BookmarkSearchHit type
type BookmarkSearchHit {
subdocument: SubDocument!
matchedField: BookmarkMatchField!
snippet: String!
}
enum BookmarkMatchField {
FILE_NAME
ISSUER
TYPE
CATEGORY
}
The subdocument whose bookmark matched. See
SubDocument. Which subdocument field matched: FILE_NAME, ISSUER, TYPE, or CATEGORY.
A snippet of the matched value, for display.
The BinderMessageSearchHit type
A search hit inside a binder message (an annotation or a mark). The underlying
message is a BinderMessage, the binder’s internal message type used by
search. Annotation and sign-off writes use the DocumentMessage type (see
Document messages); BinderMessage is the read
shape the search surface returns.
type BinderMessageSearchHit {
message: BinderMessage!
matchedField: BinderMessageMatchField!
snippet: String!
isReply: Boolean!
}
enum BinderMessageMatchField {
BODY
EXPRESSION
}
Which message field matched: BODY (the message body) or EXPRESSION (an
expression inside the message content).
A snippet of the matched text, for display.
true when the hit is a reply inside a thread, false when it is a top-level
message.
The BinderMessage type
The binder’s internal message type, returned by Binder.search. It carries the
message’s anchor (subdocument path, page number, coordinates), content, threads,
and tagged users.
type BinderMessage {
id: ID!
binderId: ID!
subDocumentPath: ID!
pageNumber: Int!
coordinates: JSON
type: String!
content: JSON!
createdBy: ID!
threads: [BinderMessageThread!]!
taggedUsers: [BinderTaggedUser!]!
isRead: Boolean!
deletedAt: String
deletedBy: ID
createdAt: String!
updatedAt: String!
}
The binder this message belongs to.
The subdocument path the message is anchored to.
The page number inside the subdocument the message is anchored to, 1-indexed.
The on-page coordinates of the message anchor, when the message is pinned to a
region. null for messages that are not pinned to a region.
The message type label, for example annotation or mark.
The message content as a JSON object.
The user who created the message.
Reply threads on the message.
Users tagged on the message.
Whether the message has been read by the current user.
When the message was deleted, if applicable. null while the message is live.
The user who deleted the message, if applicable.
When the message was created (ISO 8601 timestamp).
When the message was last updated (ISO 8601 timestamp).
The BinderContentSearchHit type
A search hit inside a subdocument’s contents: the matching field names, values,
and the page-level bounding boxes that pin them.
type BinderContentSearchHit {
subdocument: SubDocument!
snippet: String!
pages: [BinderContentPageHit!]!
}
type BinderContentPageHit {
pageNumber: Int!
fieldMatches: [BinderContentFieldMatch!]!
}
type BinderContentFieldMatch {
fieldName: String!
value: String!
bbox: BinderContentBbox
}
type BinderContentBbox {
xMin: Int!
yMin: Int!
xMax: Int!
yMax: Int!
pageNumber: Int!
}
The subdocument whose contents matched. See
SubDocument. A snippet of the matched content, for display.
The pages inside the subdocument that carried matches, with the field-level
matches on each page.
The page number, 1-indexed.
fieldMatches
[BinderContentFieldMatch!]!
The field-level matches on this page.
The name of the field that matched.
The value of the field that matched.
The bounding box that pins this match on the page. See BinderContentBbox
below. null when the match is not pinned to a region.
Left edge of the box, in page pixels.
Top edge of the box, in page pixels.
Right edge of the box, in page pixels.
Bottom edge of the box, in page pixels.
The page this box is on, 1-indexed.
List the files in a binder
Read binder.subdocuments to list the files filed in a client’s binder. This
is the most common read against the binder: it backs the binder’s Documents
screen.
query GetClientBinderSubdocuments($clientId: ID!, $filter: SubDocumentsFilter) {
me {
... on WorkspaceUser {
id
workspace {
id
clients(filters: { ids: [$clientId] }) {
id
binder {
id
subdocuments(filter: $filter) {
id
parentDocumentId
fileName
pageRange
type
issuer
taxYear
status
category
order
createdAt
bucket
canonicalPath
parentDocument {
id
fileName
contentType
url {
url
}
}
}
}
}
}
}
}
}
Arguments
input SubDocumentsFilter {
unreviewed: Boolean
flagged: Boolean
parentDocumentId: ID
}
The client whose binder you want to read. Pass it via filters.ids on
clients.
When true, return only subdocuments that have not been reviewed yet.
When true, return only subdocuments that carry a flag.
Return only subdocuments extracted from this parent document.
curl -X POST https://router.apps.filed.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
-d '{
"query": "query GetClientBinderSubdocuments($clientId: ID!, $filter: SubDocumentsFilter) { me { ... on WorkspaceUser { id workspace { id clients(filters: { ids: [$clientId] }) { id binder { id subdocuments(filter: $filter) { id parentDocumentId fileName pageRange type issuer taxYear status category order createdAt bucket canonicalPath parentDocument { id fileName contentType url { url } } } } } } } } }",
"variables": {
"clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
"filter": null
}
}'
{
"data": {
"me": {
"id": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
"workspace": {
"id": "019f0fb6-3001-7900-b7bc-0d11288504b1",
"clients": [
{
"id": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
"binder": {
"id": "018f9c2a-4b6f-7a10-b2c4-9e8d7f6a5b4d",
"subdocuments": [
{
"id": "018f9c2a-7b1e-7c3d-9a4e-2f6b1c8d0e5a",
"parentDocumentId": "018f9c2a-6a5b-7c3d-9a4e-2f6b1c8d0e49",
"fileName": "1099-INT-Acme-Broker.pdf",
"pageRange": [1],
"type": "1099-INT",
"issuer": "Acme Broker",
"taxYear": 2025,
"status": "ingested",
"category": "income",
"order": 0,
"createdAt": "2026-07-01T15:10:00.000Z",
"bucket": "source_docs",
"canonicalPath": "clients/018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c/source_docs/018f9c2a-7b1e-7c3d-9a4e-2f6b1c8d0e5a/canonical.json",
"parentDocument": {
"id": "018f9c2a-6a5b-7c3d-9a4e-2f6b1c8d0e49",
"fileName": "uploads-packet.pdf",
"contentType": "application/pdf",
"url": {
"url": "https://signed.example.com/uploads-packet.pdf?sig=..."
}
}
}
]
}
}
]
}
}
}
}
List missing items
Read binder.missingItems to list the missing-document checklist the run
produced. Filter by status to read only the open, ignored, or resolved items.
query GetClientBinderMissingItems($clientId: ID!, $filter: BinderMissingItemsFilter) {
me {
... on WorkspaceUser {
id
workspace {
clients(filters: { ids: [$clientId] }) {
id
binder {
id
openMissingItemsCount
missingItems(filter: $filter) {
id
binderId
item
formType
issuer
taxYear
severity
reason
status
category
createdAt
updatedAt
}
}
}
}
}
}
}
Arguments
input BinderMissingItemsFilter {
status: ChecklistItemStatus
}
The client whose binder you want to read. Pass it via filters.ids on
clients.
Return only missing items in this status: OPEN, IGNORED, or RESOLVED.
Omit it to list every missing item regardless of status.
curl -X POST https://router.apps.filed.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
-d '{
"query": "query GetClientBinderMissingItems($clientId: ID!, $filter: BinderMissingItemsFilter) { me { ... on WorkspaceUser { id workspace { clients(filters: { ids: [$clientId] }) { id binder { id openMissingItemsCount missingItems(filter: $filter) { id binderId item formType issuer taxYear severity reason status category createdAt updatedAt } } } } } } }",
"variables": {
"clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
"filter": { "status": "OPEN" }
}
}'
{
"data": {
"me": {
"id": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
"workspace": {
"clients": [
{
"id": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
"binder": {
"id": "018f9c2a-4b6f-7a10-b2c4-9e8d7f6a5b4d",
"openMissingItemsCount": 1,
"missingItems": [
{
"id": "018f9c2c-5d6e-7f20-9a33-7c4d5e6f7090",
"binderId": "018f9c2a-4b6f-7a10-b2c4-9e8d7f6a5b4d",
"item": "W-2 from Initech",
"formType": "W-2",
"issuer": "Initech",
"taxYear": 2025,
"severity": "CRITICAL",
"reason": "Expected a W-2 from Initech but no matching document was found in the binder.",
"status": "OPEN",
"category": "income",
"createdAt": "2026-07-01T15:30:00.000Z",
"updatedAt": "2026-07-01T15:30:00.000Z"
}
]
}
}
]
}
}
}
}
Read message counts
Read binder.messageCounts for the open missing-item count and the open notes
count. This is the cheap query for badge rendering: it does not return the full
missing-items or notes lists.
query GetBinderMessageCounts($clientId: ID!) {
me {
... on WorkspaceUser {
workspace {
clients(filters: { ids: [$clientId] }) {
id
binder {
id
messageCounts {
openMissing
notes
}
}
}
}
}
}
}
Arguments
The client whose binder counts you want. Pass it via filters.ids on
clients.
curl -X POST https://router.apps.filed.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
-d '{
"query": "query GetBinderMessageCounts($clientId: ID!) { me { ... on WorkspaceUser { workspace { clients(filters: { ids: [$clientId] }) { id binder { id messageCounts { openMissing notes } } } } } } }",
"variables": { "clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c" }
}'
{
"data": {
"me": {
"workspace": {
"clients": [
{
"id": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
"binder": {
"id": "018f9c2a-4b6f-7a10-b2c4-9e8d7f6a5b4d",
"messageCounts": {
"openMissing": 1,
"notes": 2
}
}
}
]
}
}
}
}
Search the binder
Read binder.search to search across bookmarks (subdocuments by file name,
issuer, type, or category), annotations, marks, and document contents in one
call. The query is debounced in the web app: pass at least two characters.
query BinderSearch($clientId: ID!, $query: String!, $limit: Int = 20) {
me {
... on WorkspaceUser {
id
workspace {
clients(filters: { ids: [$clientId] }) {
id
binder {
id
search(query: $query, limit: $limit) {
bookmarks {
matchedField
snippet
subdocument {
id
fileName
type
issuer
category
pageRange
}
}
annotations {
matchedField
snippet
isReply
message {
id
type
subDocumentPath
pageNumber
content
createdBy
createdAt
}
}
marks {
matchedField
snippet
isReply
message {
id
type
subDocumentPath
pageNumber
content
createdBy
createdAt
}
}
contents {
snippet
subdocument {
id
fileName
type
issuer
category
pageRange
canonicalPath
}
pages {
pageNumber
fieldMatches {
fieldName
value
bbox {
xMin
yMin
xMax
yMax
pageNumber
}
}
}
}
}
}
}
}
}
}
}
Arguments
The client whose binder you want to search. Pass it via filters.ids on
clients.
The search query. The web app debounces the input and requires at least two
characters before firing the query.
Maximum number of hits to return per bucket. Defaults to 20.
curl -X POST https://router.apps.filed.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
-d '{
"query": "query BinderSearch($clientId: ID!, $query: String!, $limit: Int = 20) { me { ... on WorkspaceUser { id workspace { clients(filters: { ids: [$clientId] }) { id binder { id search(query: $query, limit: $limit) { bookmarks { matchedField snippet subdocument { id fileName type issuer category pageRange } } annotations { matchedField snippet isReply message { id type subDocumentPath pageNumber content createdBy createdAt } } marks { matchedField snippet isReply message { id type subDocumentPath pageNumber content createdBy createdAt } } contents { snippet subdocument { id fileName type issuer category pageRange canonicalPath } pages { pageNumber fieldMatches { fieldName value bbox { xMin yMin xMax yMax pageNumber } } } } } } } } } } }",
"variables": {
"clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
"query": "Acme",
"limit": 20
}
}'
{
"data": {
"me": {
"id": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
"workspace": {
"clients": [
{
"id": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
"binder": {
"id": "018f9c2a-4b6f-7a10-b2c4-9e8d7f6a5b4d",
"search": {
"bookmarks": [
{
"matchedField": "ISSUER",
"snippet": "Acme Broker",
"subdocument": {
"id": "018f9c2a-7b1e-7c3d-9a4e-2f6b1c8d0e5a",
"fileName": "1099-INT-Acme-Broker.pdf",
"type": "1099-INT",
"issuer": "Acme Broker",
"category": "income",
"pageRange": [1]
}
}
],
"annotations": [],
"marks": [],
"contents": [
{
"snippet": "Acme Broker paid $210.00 in interest",
"subdocument": {
"id": "018f9c2a-7b1e-7c3d-9a4e-2f6b1c8d0e5a",
"fileName": "1099-INT-Acme-Broker.pdf",
"type": "1099-INT",
"issuer": "Acme Broker",
"category": "income",
"pageRange": [1],
"canonicalPath": "clients/018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c/source_docs/018f9c2a-7b1e-7c3d-9a4e-2f6b1c8d0e5a/canonical.json"
},
"pages": [
{
"pageNumber": 1,
"fieldMatches": [
{
"fieldName": "payer",
"value": "Acme Broker",
"bbox": {
"xMin": 88,
"yMin": 412,
"xMax": 220,
"yMax": 428,
"pageNumber": 1
}
}
]
}
]
}
]
}
}
}
]
}
}
}
}
Ignore a missing item
ignoreBinderMissingItem moves a missing item from OPEN to IGNORED. Use it
when a reviewer dismisses a missing item the run flagged. The mutation takes
the missing-item id and the workspaceId, and returns the updated
BinderMissingItem with its new status.
mutation IgnoreBinderMissingItem($id: ID!, $workspaceId: String!) {
ignoreBinderMissingItem(id: $id, workspaceId: $workspaceId) {
id
status
}
}
The workspace ID. Unlike the read fields, this mutation takes the workspace ID
explicitly. Use the same workspace ID the workspaceToken was issued for.
Returns: BinderMissingItem!
The ignored BinderMissingItem, with status
set to IGNORED.
curl -X POST https://router.apps.filed.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
-d '{
"query": "mutation IgnoreBinderMissingItem($id: ID!, $workspaceId: String!) { ignoreBinderMissingItem(id: $id, workspaceId: $workspaceId) { id status } }",
"variables": {
"id": "018f9c2c-5d6e-7f20-9a33-7c4d5e6f7090",
"workspaceId": "019f0fb6-3001-7900-b7bc-0d11288504b1"
}
}'
{
"data": {
"ignoreBinderMissingItem": {
"id": "018f9c2c-5d6e-7f20-9a33-7c4d5e6f7090",
"status": "IGNORED"
}
}
}
After ignoring a missing item, refetch the
List missing items query so the open count and the list
agree. The web app optimistically removes the row from the OPEN list and
decrements openMissingItemsCount in its cache, then refetches to confirm. Restore a missing item
restoreBinderMissingItem moves a missing item from IGNORED back to OPEN.
Use it when a reviewer wants to re-surface a missing item they previously
ignored.
mutation RestoreBinderMissingItem($id: ID!, $workspaceId: String!) {
restoreBinderMissingItem(id: $id, workspaceId: $workspaceId) {
id
status
}
}
The workspace ID. Use the same workspace ID the workspaceToken was issued
for.
Returns: BinderMissingItem!
The restored BinderMissingItem, with status
set to OPEN.
curl -X POST https://router.apps.filed.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
-d '{
"query": "mutation RestoreBinderMissingItem($id: ID!, $workspaceId: String!) { restoreBinderMissingItem(id: $id, workspaceId: $workspaceId) { id status } }",
"variables": {
"id": "018f9c2c-5d6e-7f20-9a33-7c4d5e6f7090",
"workspaceId": "019f0fb6-3001-7900-b7bc-0d11288504b1"
}
}'
{
"data": {
"restoreBinderMissingItem": {
"id": "018f9c2c-5d6e-7f20-9a33-7c4d5e6f7090",
"status": "OPEN"
}
}
}
After restoring a missing item, refetch the
List missing items query so the open count and the list
agree. The web app optimistically increments openMissingItemsCount in its
cache, then refetches to confirm. 
