Binder - Filed Engineering

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "query QueryClientBinder($clientId: ID!) { me { ... on WorkspaceUser { workspace { clients(filters: { ids: [$clientId] }) { id name binder { id clientId messageCounts { openMissing notes } subdocuments { id parentDocumentId fileName type issuer taxYear status category bucket pageRange canonicalPath parentDocument { id fileName contentType url { filePath url } subdocPages { pageNumber imageUrl { filePath url } markdownUrl { filePath url } } } } missingItemsAssessment(filter: { status: OPEN }) { status reason count items { id item formType issuer taxYear severity reason status category } } } } } } } }",
    "variables": {
      "clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c"
    }
  }'

{
  "data": {
    "me": {
      "workspace": {
        "clients": [
          {
            "id": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
            "name": "Jane Smith",
            "binder": {
              "id": "018f9c2a-4b6f-7a10-b2c4-9e8d7f6a5b4d",
              "clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
              "messageCounts": {
                "openMissing": 1,
                "notes": 2
              },
              "subdocuments": [
                {
                  "id": "018f9c2a-7b1e-7c3d-9a4e-2f6b1c8d0e5a",
                  "parentDocumentId": "018f9c2a-6a5b-7c3d-9a4e-2f6b1c8d0e49",
                  "fileName": "1099-INT-Acme-Broker.pdf",
                  "type": "1099-INT",
                  "issuer": "Acme Broker",
                  "taxYear": 2025,
                  "status": "ingested",
                  "category": "income",
                  "bucket": "source_docs",
                  "pageRange": [1],
                  "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": {
                      "filePath": "uploads/018f9c2a-6a5b-7c3d-9a4e-2f6b1c8d0e49.pdf",
                      "url": "https://signed.example.com/uploads-packet.pdf?sig=..."
                    },
                    "subdocPages": [
                      {
                        "pageNumber": 1,
                        "imageUrl": {
                          "filePath": "renders/page-1.png",
                          "url": "https://signed.example.com/page-1.png?sig=..."
                        },
                        "markdownUrl": {
                          "filePath": "renders/page-1.md",
                          "url": "https://signed.example.com/page-1.md?sig=..."
                        }
                      }
                    ]
                  }
                }
              ],
              "missingItemsAssessment": {
                "status": "AVAILABLE",
                "reason": null,
                "count": 1,
                "items": [
                  {
                    "id": "018f9c2a-8c2f-7c3d-9a4e-2f6b1c8d0e5b",
                    "item": "W-2 from Example Employer",
                    "formType": "W-2",
                    "issuer": "Example Employer",
                    "taxYear": 2025,
                    "severity": "CRITICAL",
                    "reason": "Expected a W-2 from Example Employer but no matching document was found in the binder.",
                    "status": "OPEN",
                    "category": "income"
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

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.

Query a client’s binder

Use this query when an app, agent, or MCP tool needs the binder overview for a client: filed documents, open missing items, quick counts, and signed URLs for the original uploads and page renders.

query QueryClientBinder($clientId: ID!) {
  me {
    ... on WorkspaceUser {
      workspace {
        clients(filters: { ids: [$clientId] }) {
          id
          name
          binder {
            id
            clientId
            messageCounts {
              openMissing
              notes
            }
            subdocuments {
              id
              parentDocumentId
              fileName
              type
              issuer
              taxYear
              status
              category
              bucket
              pageRange
              canonicalPath
              parentDocument {
                id
                fileName
                contentType
                url {
                  filePath
                  url
                }
                subdocPages {
                  pageNumber
                  imageUrl {
                    filePath
                    url
                  }
                  markdownUrl {
                    filePath
                    url
                  }
                }
              }
            }
            missingItemsAssessment(filter: { status: OPEN }) {
              status
              reason
              count
              items {
                id
                item
                formType
                issuer
                taxYear
                severity
                reason
                status
                category
              }
            }
          }
        }
      }
    }
  }
}

Arguments

ID!

required

The client whose binder you want to read. Pass it via filters.ids on clients.

Returns

Binder

The binder for the requested client. It contains filed documents, missing items, message counts, and search.

[SubDocument!]!

The logical documents Filed extracted or filed into the binder. Save each id: it is the documentPath used by document messages and file-level leadsheet signoff.

SignedPath!

Signed URL for the original uploaded file. Signed URLs are time-limited.

[SubdocPage!]!

Signed page image and markdown URLs for rendering or reading the parent document page by page.

BinderMissingItemsAssessment!

The status, reason, count, and filtered items for the missing-document check. Treat an empty item list as an all-clear only when status is AVAILABLE.

BinderMessageCounts!

Small counts for badges and summaries without fetching all messages.

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "query QueryClientBinder($clientId: ID!) { me { ... on WorkspaceUser { workspace { clients(filters: { ids: [$clientId] }) { id name binder { id clientId messageCounts { openMissing notes } subdocuments { id parentDocumentId fileName type issuer taxYear status category bucket pageRange canonicalPath parentDocument { id fileName contentType url { filePath url } subdocPages { pageNumber imageUrl { filePath url } markdownUrl { filePath url } } } } missingItemsAssessment(filter: { status: OPEN }) { status reason count items { id item formType issuer taxYear severity reason status category } } } } } } } }",
    "variables": {
      "clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c"
    }
  }'

{
  "data": {
    "me": {
      "workspace": {
        "clients": [
          {
            "id": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
            "name": "Jane Smith",
            "binder": {
              "id": "018f9c2a-4b6f-7a10-b2c4-9e8d7f6a5b4d",
              "clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
              "messageCounts": {
                "openMissing": 1,
                "notes": 2
              },
              "subdocuments": [
                {
                  "id": "018f9c2a-7b1e-7c3d-9a4e-2f6b1c8d0e5a",
                  "parentDocumentId": "018f9c2a-6a5b-7c3d-9a4e-2f6b1c8d0e49",
                  "fileName": "1099-INT-Acme-Broker.pdf",
                  "type": "1099-INT",
                  "issuer": "Acme Broker",
                  "taxYear": 2025,
                  "status": "ingested",
                  "category": "income",
                  "bucket": "source_docs",
                  "pageRange": [1],
                  "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": {
                      "filePath": "uploads/018f9c2a-6a5b-7c3d-9a4e-2f6b1c8d0e49.pdf",
                      "url": "https://signed.example.com/uploads-packet.pdf?sig=..."
                    },
                    "subdocPages": [
                      {
                        "pageNumber": 1,
                        "imageUrl": {
                          "filePath": "renders/page-1.png",
                          "url": "https://signed.example.com/page-1.png?sig=..."
                        },
                        "markdownUrl": {
                          "filePath": "renders/page-1.md",
                          "url": "https://signed.example.com/page-1.md?sig=..."
                        }
                      }
                    ]
                  }
                }
              ],
              "missingItemsAssessment": {
                "status": "AVAILABLE",
                "reason": null,
                "count": 1,
                "items": [
                  {
                    "id": "018f9c2a-8c2f-7c3d-9a4e-2f6b1c8d0e5b",
                    "item": "W-2 from Example Employer",
                    "formType": "W-2",
                    "issuer": "Example Employer",
                    "taxYear": 2025,
                    "severity": "CRITICAL",
                    "reason": "Expected a W-2 from Example Employer but no matching document was found in the binder.",
                    "status": "OPEN",
                    "category": "income"
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

MCP usage pattern

Start with clients(filters: { ids: [$clientId] }) and read binder.
Use binder.subdocuments for the document list and preserve each subdocument id for later annotation, signoff, or leadsheet operations.
Use parentDocument.url when the user needs the original upload, and parentDocument.subdocPages when the user needs page images or page markdown.
Use missingItemsAssessment.count and messageCounts for compact summaries before displaying full lists.
Use binder.search when the user asks about specific content, issuers, categories, annotations, marks, or values inside the documents.

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!
  missingItemsAssessment(
    filter: BinderMissingItemsFilter
  ): BinderMissingItemsAssessment!
  missingItems(filter: BinderMissingItemsFilter): [BinderMissingItem!]!
    @deprecated(reason: "Use missingItemsAssessment instead.")
  openMissingItemsCount: Int!
    @deprecated(reason: "Use missingItemsAssessment.count instead.")
  messageCounts: BinderMessageCounts!
  search(query: String!, limit: Int = 20): BinderSearchResults!
  leadsheets(taskId: ID): Leadsheets
}

ID!

The binder’s unique identifier.

ID!

The client this binder belongs to.

[SubDocument!]!

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.

String!

When the binder was created (ISO 8601 timestamp).

String!

When the binder was last updated (ISO 8601 timestamp).

BinderMissingItemsAssessment!

The state and filtered result of the missing-document check. Pass a BinderMissingItemsFilter to narrow by item status. See List missing items.

[BinderMissingItem!]!

Deprecated. Use missingItemsAssessment.items so you can distinguish an available empty result from a pending or unavailable assessment.

Int!

Deprecated. Use missingItemsAssessment.count.

BinderMessageCounts!

Open missing-item and notes counts for badge rendering. See Read message counts.

BinderSearchResults!

Search across bookmarks, annotations, marks, and document contents. See Search the binder.

Leadsheets

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
}

ID!

The subdocument’s unique identifier. This is the value you pass as documentPath when creating a document message or signing off on a file.

ID!

The client this subdocument belongs to.

String!

The ID of the parent document this subdocument was extracted from.

String!

The file name, for example 1099-INT-Acme-Broker.pdf.

[Int!]!

The pages inside the parent document this subdocument covers, 1-indexed.

String!

The document type the extractor classified this as, for example 1099-INT or W-2.

String!

The issuer or payer named on the document, for example Acme Broker.

Int!

The tax year this document covers, for example 2025.

String!

The ingestion or review status of this subdocument, for example ingested or reviewed.

String

The binder grouping category, when one has been assigned. Nullable: some subdocuments are uncategorized until a reviewer files them.

Int!

The sort order of this subdocument within the binder.

String!

When the subdocument was created (ISO 8601 timestamp).

String!

When the subdocument was last updated (ISO 8601 timestamp).

ParentDocument

The parent document this subdocument was extracted from. See ParentDocument.

String

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.

String

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
}

ID!

The parent document’s unique identifier.

String!

The original uploaded file name.

String!

The MIME type, for example application/pdf.

SignedPath!

A signed URL for downloading the original file. SignedPath is { filePath: String!, url: String! }.

[SubdocPage!]!

Per-page render URLs for the parent document: one image URL and one markdown URL per page, both signed and time-limited.

The `BinderMissingItemsAssessment` type

The result of the missing-document check for the requested item status.

type BinderMissingItemsAssessment {
  status: BinderMissingItemsAssessmentStatus!
  reason: String
  count: Int!
  items: [BinderMissingItem!]!
}

enum BinderMissingItemsAssessmentStatus {
  PENDING
  AVAILABLE
  UNAVAILABLE
}

BinderMissingItemsAssessmentStatus!

PENDING while the check has not completed, AVAILABLE when the result can be used, or UNAVAILABLE when the binder lacks enough evidence to determine missing documents.

String

An explanation for a pending or unavailable assessment. It is null when the assessment is available.

Int!

The number of items returned for the requested filter.

[BinderMissingItem!]!

The missing items matching the requested filter. For an OPEN filter this is empty while the assessment is pending or unavailable.

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
}

ID!

The missing-item record ID. Pass this to ignoreBinderMissingItem or restoreBinderMissingItem.

ID!

The binder this missing item belongs to.

String!

The missing item, for example 1099-INT or W-2 from Acme.

String

The form type expected, when the checklist is form-specific.

String

The issuer the run expected to find, when relevant.

Int

The tax year the missing item applies to.

ChecklistItemSeverity!

How blocking the missing item is: CRITICAL, MEDIUM, or LOW.

String!

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.

ChecklistItemStatus!

The current status: OPEN (still needs the document), IGNORED (a reviewer dismissed it via ignoreBinderMissingItem), or RESOLVED (the document was later found and filed).

String

A grouping category, when one has been assigned.

String!

When the missing-item record was created (ISO 8601 timestamp).

String!

When the missing-item record was last updated (ISO 8601 timestamp).

The `BinderMessageCounts` type

Open missing-item and notes counts. Use missingItemsAssessment when you also need to know whether the missing-document check is available.

type BinderMessageCounts {
  openMissing: Int!
  notes: Int!
}

Int!

The number of stored missing items in the OPEN status. Do not use this field alone to infer that the missing-document check completed successfully.

Int!

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!]!
}

[BookmarkSearchHit!]!

Subdocuments whose file name, issuer, type, or category matched the query. See BookmarkSearchHit.

[BinderMessageSearchHit!]!

Binder messages (annotations and notes) whose body or expression matched the query. See BinderMessageSearchHit.

[BinderMessageSearchHit!]!

Binder messages that are marks, whose body or expression matched the query. See BinderMessageSearchHit.

[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
}

SubDocument!

The subdocument whose bookmark matched. See SubDocument.

BookmarkMatchField!

Which subdocument field matched: FILE_NAME, ISSUER, TYPE, or CATEGORY.

String!

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
}

BinderMessage!

The binder message that matched. See BinderMessage.

BinderMessageMatchField!

Which message field matched: BODY (the message body) or EXPRESSION (an expression inside the message content).

String!

A snippet of the matched text, for display.

Boolean!

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!
}

ID!

The binder message ID.

ID!

The binder this message belongs to.

ID!

The subdocument path the message is anchored to.

Int!

The page number inside the subdocument the message is anchored to, 1-indexed.

JSON

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.

String!

The message type label, for example annotation or mark.

JSON!

The message content as a JSON object.

ID!

The user who created the message.

[BinderMessageThread!]!

Reply threads on the message.

[BinderTaggedUser!]!

Users tagged on the message.

Boolean!

Whether the message has been read by the current user.

String

When the message was deleted, if applicable. null while the message is live.

The user who deleted the message, if applicable.

String!

When the message was created (ISO 8601 timestamp).

String!

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!
}

SubDocument!

The subdocument whose contents matched. See SubDocument.

String!

A snippet of the matched content, for display.

[BinderContentPageHit!]!

The pages inside the subdocument that carried matches, with the field-level matches on each page.

Int!

The page number, 1-indexed.

[BinderContentFieldMatch!]!

The field-level matches on this page.

String!

The name of the field that matched.

String!

The value of the field that matched.

BinderContentBbox

The bounding box that pins this match on the page. See BinderContentBbox below. null when the match is not pinned to a region.

Int!

Left edge of the box, in page pixels.

Int!

Top edge of the box, in page pixels.

Int!

Right edge of the box, in page pixels.

Int!

Bottom edge of the box, in page pixels.

Int!

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
}

ID!

required

The client whose binder you want to read. Pass it via filters.ids on clients.

Boolean

When true, return only subdocuments that have not been reviewed yet.

Boolean

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=..."
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}

The subdocument id is the value you pass as documentPath when creating a document message or signing off on a file. Save it when you list the binder so you can reference it later.

List missing items

Read binder.missingItemsAssessment to get the state and filtered result of the missing-document check. Filter by item status to read only open, ignored, or resolved history.

query GetClientBinderMissingItems($clientId: ID!, $filter: BinderMissingItemsFilter) {
  me {
    ... on WorkspaceUser {
      id
      workspace {
        clients(filters: { ids: [$clientId] }) {
          id
          binder {
            id
            missingItemsAssessment(filter: $filter) {
              status
              reason
              count
              items {
                id
                binderId
                item
                formType
                issuer
                taxYear
                severity
                reason
                status
                category
                createdAt
                updatedAt
              }
            }
          }
        }
      }
    }
  }
}

Arguments

input BinderMissingItemsFilter {
  status: ChecklistItemStatus
}

ID!

required

The client whose binder you want to read. Pass it via filters.ids on clients.

ChecklistItemStatus

Return only missing items in this status: OPEN, IGNORED, or RESOLVED. Omit it to use the default OPEN status.

Returns

type BinderMissingItemsAssessment {
  status: BinderMissingItemsAssessmentStatus!
  reason: String
  count: Int!
  items: [BinderMissingItem!]!
}

BinderMissingItemsAssessmentStatus!

Whether the missing-document check is PENDING, AVAILABLE, or UNAVAILABLE.

String

Why the assessment is pending or unavailable. It is null when available.

Int!

The number of items matching the requested filter.

[BinderMissingItem!]!

The filtered missing-item rows. Open items are empty for pending or unavailable assessments.

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 missingItemsAssessment(filter: $filter) { status reason count items { 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",
              "missingItemsAssessment": {
                "status": "AVAILABLE",
                "reason": null,
                "count": 1,
                "items": [
                  {
                    "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 stored missing-item and open note counts. Use missingItemsAssessment for a missing-document badge so the UI can distinguish an available empty result from a pending or unavailable check.

query GetBinderMessageCounts($clientId: ID!) {
  me {
    ... on WorkspaceUser {
      workspace {
        clients(filters: { ids: [$clientId] }) {
          id
          binder {
            id
            messageCounts {
              openMissing
              notes
            }
          }
        }
      }
    }
  }
}

Arguments

ID!

required

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

ID!

required

The client whose binder you want to search. Pass it via filters.ids on clients.

String!

required

The search query. The web app debounces the input and requires at least two characters before firing the query.

Int

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
  }
}

Input

ID!

required

The ID of the missing item to ignore (the id from List missing items).

String!

required

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 moves the row from the OPEN assessment to the IGNORED assessment and updates both counts.

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
  }
}

Input

ID!

required

The ID of the missing item to restore (the id from List missing items).

String!

required

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 moves the row from the IGNORED assessment to the OPEN assessment when the check is available.

​Query a client’s binder

​Arguments

​Returns

​MCP usage pattern

​The Binder type

​The SubDocument type

​The ParentDocument type

​The BinderMissingItemsAssessment type

​The BinderMissingItem type

​The BinderMessageCounts type

​The BinderSearchResults type

​The BookmarkSearchHit type

​The BinderMessageSearchHit type

​The BinderMessage type

​The BinderContentSearchHit type

​List the files in a binder

​Arguments

​List missing items

​Arguments

​Returns

​Read message counts

​Arguments

​Search the binder

​Arguments

​Ignore a missing item

​Input

​Returns: BinderMissingItem!

​Restore a missing item

​Input

​Returns: BinderMissingItem!

Query a client’s binder

Arguments

Returns

MCP usage pattern

The `Binder` type

The `SubDocument` type

The `ParentDocument` type

The `BinderMissingItemsAssessment` type

The `BinderMissingItem` type

The `BinderMessageCounts` type

The `BinderSearchResults` type

The `BookmarkSearchHit` type

The `BinderMessageSearchHit` type

The `BinderMessage` type

The `BinderContentSearchHit` type

List the files in a binder

Arguments

List missing items

Arguments

Returns

Read message counts

Arguments

Search the binder

Arguments

Ignore a missing item

Input

Returns: `BinderMissingItem!`

Restore a missing item

Input

Returns: `BinderMissingItem!`