---
title: "Get folder contents"
method: GET
path: "/internal/api/clients/{client_id}/dms/folders/contents"
tags: ["CLIENT", "Client Document Management", "DMS Folders"]
---

# Get folder contents

`GET /internal/api/clients/{client_id}/dms/folders/contents`

## Request

- Base URL: `https://api.signalshq.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.signalshq.io/internal/api/clients/{client_id}/dms/folders/contents`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Get folders and documents in a specific folder or root level (folders first, then documents) with extraction and workflow status

## Path parameters

- `client_id` string, uuid, required: Client ID

## Query parameters

- `folder_id` string, nullable: Folder ID (empty/null for root level)
- `sort_by` string: Sort field (name, created_at, updated_at, type)
- `sort_order` string: Sort order (asc, desc)
- `tax_year` string[], nullable: Filter by tax year (multiple values allowed)
- `doc_year` string[], nullable: Filter by document year (multiple values allowed)
- `extraction` boolean, nullable: Filter by extraction status (true=only documents that have been processed)
- `doc_type` string[], nullable: Filter by legacy document type (e.g. W2, FORM_1099_INT)
- `document_type_id` string[], nullable: Filter by canonical document_type_id (the new source-of-truth column; matches reclassified documents correctly where the legacy doc_type would not)
- `extraction_status` string[], nullable: Filter by extraction status (e.g. COMPLETED, FAILED, IN_PROGRESS)
- `workflow_status` string[], nullable: Filter by workflow status (e.g. APPROVED, CREATED, IN_PROGRESS)
- `needs_attention` boolean, nullable: When true, return only items needing CPA action: failed/unsupported documents and multi-form bundles whose rollup is ACTION_NEEDED or ALL_FAILED (with their children).
- `folderview` boolean: Include folders in response (false=flat list of documents only)
- `query` string, nullable: Search term to filter folders and documents by name, description, or filename
- `page` integer: Page number (1-based)
- `page_size` integer: Number of items per page

## Response `200`

Successful Response

- FolderContentsResponse
  - `current_folder` CurrentFolderInfo, required
    - `id` string, uuid, nullable, required
    - `name` string, required
    - `path` string, required
    - `description` string, nullable, required
    - `breadcrumb` BreadcrumbItem[], required
      - `id` string, uuid, nullable, required
      - `name` string, required
    - `total_size` integer
    - `created_at` string, date-time, required
  - `items` union[], required
    - union
      - FolderItem: Unified folder item for the items array
        - `id` string, uuid, required
        - `type` string: Item type identifier
        - `name` string, required
        - `description` string, nullable, required
        - `path` string, required
        - `tags` object[]
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
        - `is_shared` boolean: True when this folder has an active direct share with the client. Use share_id to call DELETE /dms/shares/{share_id} to unshare.
        - `share_id` string, uuid, nullable: Active share ID when is_shared=True. Used for the Unshare action.
        - `is_shared_via_folder` boolean: True when this folder's nearest shared ancestor gives the client access. The client can browse into this folder via that share. Use folder_share_id to identify (and optionally unshare) the ancestor share.
        - `folder_share_id` string, uuid, nullable: Share ID of the nearest shared ancestor folder when is_shared_via_folder=True.
      - DocumentItem: Unified document item for folder contents with version information. Always returns the latest version when listed in folder contents. Version fields allow UI to display which version is shown.
        - `id` string, uuid, required
        - `type` string: Item type identifier
        - `name` string, required
        - `document_type` 'W2' | 'W2_AS' | 'W2_CM' | 'W2_GU' | 'W2_VI' | 'FORM_W2G' | 'FORM_W3' | 'FORM_1040' | 'FORM_1040_SCHEDULE_A' | 'FORM_1040_SCHEDULE_B' | 'FORM_1040_SCHEDULE_E' | 'FORM_1040_SCHEDULE_F' | 'FORM_1040_SENIOR' | 'FORM_1098' | 'FORM_1098_C' | 'FORM_1098_E' | 'FORM_1098_T' | 'FORM_1099_INT' | 'FORM_1099_A' | 'FORM_1099_B' | 'FORM_1099_CAP' | 'FORM_1099_CONSOLIDATED_STATEMENT' | 'FORM_1099_DIV' | 'FORM_1099_R' | 'FORM_1099_G' | 'FORM_1099_MISC' | 'FORM_1099_NEC' | 'FORM_1099_C' | 'FORM_1099_K' | 'FORM_1099_LTC' | 'FORM_1099_OID' | 'FORM_1099_PATR' | 'FORM_1099_QA' | 'FORM_1099_SA' | 'FORM_1099_Q' | 'FORM_1099_DA' | 'FORM_RRB_1099' | 'FORM_RRB_1099R' | 'FORM_1099_S' | 'FORM_1042_S' | 'FORM_8805' | 'FORM_8288_A' | 'FORM_1095_A' | 'FORM_1095_C' | 'FORM_SSA_1099' | 'FORM_2439' | 'FORM_3921' | 'FORM_3922' | 'FORM_5498' | 'FORM_5498_SA' | 'SCHEDULE_K1_GENERIC' | 'SCH_K1_1041' | 'SCH_K1_1065' | 'SCH_K1_1120S' | 'FORM_1041_SCHEDULE_K1' | 'FORM_1065_SCHEDULE_K1' | 'FORM_1120S_SCHEDULE_K1' | 'INVOICE' | 'RECEIPT' | 'TAX_FORM' | 'PROFIT_AND_LOSS_STATEMENT' | 'PROFIT_AND_LOSS_STATEMENT_BUSINESS' | 'PROFIT_AND_LOSS_STATEMENT_FARM' | 'PROFIT_AND_LOSS_STATEMENT_RENTAL' | 'INCOME_STATEMENT' | 'GENERAL_LEDGER' | 'TRIAL_BALANCE' | 'BALANCE_SHEET' | 'SCHEDULE_C_INPUT' | 'PREVIOUS_YEAR_RETURN' | 'BROKERAGE_STATEMENT' | 'ASSETS_PURCHASED_BUSINESS' | 'ASSETS_SOLD_BUSINESS' | 'ASSETS_PURCHASED_RENTAL' | 'ASSETS_SOLD_RENTAL' | 'ASSETS_PURCHASED_FARM' | 'ASSETS_SOLD_FARM' | 'MEDICAL_EXPENSES' | 'CHARITABLE_CONTRIBUTIONS_CASH' | 'CHARITABLE_CONTRIBUTIONS_NON_CASH' | 'PERSONAL_PROPERTY_TAXES' | 'SALES_AND_USE_TAXES' | 'VEHICLE_EXPENSES' | 'DAY_CARE_EXPENSES' | 'MAJOR_PURCHASES' | 'PROPERTY_TAX_STATEMENT' | 'ESTIMATED_TAX_PAYMENT_RECEIPTS' | 'CLOSING_STATEMENT_REAL_ESTATE' | 'PREVIOUS_YEAR_TAX_RETURNS' | 'TAX_RETURN' | 'TAX_ORGANIZER' | 'TAX_PLANNING' | 'REPAIRS_AND_IMPROVEMENTS_RENTAL' | 'PAYROLL_TAX_REPORT' | 'CLIENT_INTAKE_FORM' | 'GOVERNMENT_ISSUED_IDENTIFICATION' | 'IRS_NOTICE_OR_LETTER' | 'DEPENDENT_DOCUMENTATION' | 'FOREIGN_FINANCIAL_ACCOUNTS' | 'FOREIGN_INCOME_DOCUMENTATION' | '529_PLAN_STATEMENT' | '83B_ELECTION_STATEMENT' | 'SALES_BY_STATE_REPORT' | 'STATES_FILING_SALES_TAX_RETURNS' | 'VEHICLE_SELLER_REPORT' | 'HEALTH_INSURANCE_PREMIUM_STATEMENT' | 'BIRTH_CERTIFICATE' | 'DRIVERS_LICENSE' | 'DIRECT_DEPOSIT' | 'REGISTRATION_RENEWAL_NOTICE' | 'ENGAGEMENT_LETTER' | 'SERVICE_AGREEMENT' | 'CLIENT_NOTE' | 'BUNDLED_DOCUMENT' | 'OTHER_DOCUMENTS' | 'UNCATEGORIZED' | 'VESTING_STATEMENT' | 'EXERCISE_CONFIRMATION' | 'CLERGY_INFORMATION' | 'OTHER'
        - `derived_document_type` string, nullable: DEPRECATED legacy display name — superseded by document_type_display_name. Read nowhere on the consumer dashboard; dropped with the legacy columns in Phase 3.
        - `document_type_id` string, uuid, nullable: Canonical document type id (FK to supported_document_types). The stable identifier the client should use for logic (e.g. pre-selecting the current type); pair with document_type_display_name for display.
        - `document_type_identifier` string, nullable: Canonical document_identifier of the document's type (e.g. 'SCH_K1_1065', 'FORM_1099_CONSOLIDATED'). The stable routing key for selecting a specialized review screen — route on THIS, not on document_classification.
        - `document_type_display_name` string, nullable: Single canonical 'what type is this document' display name, resolved by the backend with precedence document_type_id > derived_document_type > document_classification. Clients should read THIS field for the document type — no column-picking on the client.
        - `party_role` 'TAXPAYER' | 'SPOUSE' | 'JOINT' | 'DEPENDENT' | 'NOT_ON_RETURN': Whose document this is, on a joint return. ``DEPENDENT`` and ``NOT_ON_RETURN`` are RESERVED, not live — the DB constraint ``ck_dms_party_v1_scope`` blocks them. Both need the engine to EXCLUDE a document from the value lists rather than merely label it, and exclusion changes the correct answer at every document read, not just the few that already do owner attribution. Shipping half of that is an internally inconsistent 1040.
        - `party_confirmed` boolean, nullable: False = auto-set from a corroborated TIN match but not yet agreed by a human; the UI renders it with the AI-provenance mark and the sign-off assertion counts it. The tax engine uses the value either way. A bool rather than the DB timestamp: the client only needs 'has a human agreed?', and sending the instant invites it to render one.
        - `party_display` PartyDisplay: How to render a document's owner. Built server-side, never derived in the browser. ``full`` always carries the name AND the role ("Priya Raghunathan · Spouse") so it is safe as a tooltip and an accessible name — a wrong guess at ``short`` can then only degrade display, never meaning.
          - `initial` string, required
          - `short` string, required
          - `full` string, required
          - `role_label` string, required
        - `party_allowed_roles` DocumentPartyRoleEnum[], nullable: The roles this document's TYPE permits, already filtered to what v1 can store. The picker renders exactly this list — never a hardcoded one — because ownership is a fact about the form: a W-2 has one employee, an IRA has exactly one owner (IRC 408(a)), a bank account may be joint. Empty = the question does not apply.
        - `party_suggestion_basis` 'TIN_EXACT' | 'TIN_LAST4' | 'NAME_ONLY' | 'AMBIGUOUS' | 'NO_MATCH': Evidence behind a party suggestion — gates whether it may auto-set. Azure DI extracts TINs VERBATIM including masking, so a full-digit comparison is only possible when both sides are complete; below that, last-4 is all there is. Four masked digits alone is a 1-in-10^4 coincidence with CORRELATED family serials and no checksum, so ``TIN_LAST4`` auto-sets only with a corroborating name.
        - `party_role_suggested` 'TAXPAYER' | 'SPOUSE' | 'JOINT' | 'DEPENDENT' | 'NOT_ON_RETURN': Whose document this is, on a joint return. ``DEPENDENT`` and ``NOT_ON_RETURN`` are RESERVED, not live — the DB constraint ``ck_dms_party_v1_scope`` blocks them. Both need the engine to EXCLUDE a document from the value lists rather than merely label it, and exclusion changes the correct answer at every document read, not just the few that already do owner attribution. Shipping half of that is an internally inconsistent 1040.
        - `split_state` string, nullable: NONE | AWAITING_SPLIT | BUNDLE | CHILD.
        - `parent_document_id` string, uuid, nullable: For a CHILD, the BUNDLE it belongs to (for nested display).
        - `bundle_status` string, nullable: BUNDLE only: SPLITTING | EXTRACTING | ACTION_NEEDED | ALL_FAILED | READY | COMPLETED. Derived rollup of the bundle's children — the canonical bundle status. None for non-bundles.
        - `bundle_summary` BundleSummary: Coverage ledger for a multi-form BUNDLE — the rollup of its children's statuses. Rendered by the FE as a chip (✓ ready · ⚠ failed · — ignored). Present only on BUNDLE rows.
          - `total` integer, required: Number of child forms in the bundle.
          - `in_progress` integer, required: Children still extracting (or not yet started).
          - `ready` integer, required: Children successfully extracted (ready for review).
          - `failed` integer, required: Children that failed or are unsupported (need CPA action).
          - `ignored` integer, required: Children dismissed by a human as non-tax forms (SKIPPED).
        - `document_classification` string, nullable: DEPRECATED legacy LLM classification varchar. Do NOT use for type display or review routing — use document_type_display_name / document_type_identifier. Retained only as a transition fallback + 1099C/K1 panel data; dropped in Phase 3.
        - `document_classification_display_name` string, nullable: DEPRECATED — superseded by document_type_display_name (which resolves with precedence). Not consumed by the consumer dashboard; removed in Phase 2/3.
        - `instance_name` string, nullable: Instance label for this classification (e.g., employer or institution).
        - `file_size` integer, required
        - `version` integer, required: Version number of this document (1, 2, 3, etc.)
        - `is_latest` boolean, required: Whether this is the latest version (always True in folder contents)
        - `folder_id` string, uuid, nullable, required
        - `folder_path` string, nullable, required
        - `tags` object[]
        - `uploaded_at` string, date-time, required
        - `download_count` integer, required
        - `tax_year` string, nullable: Tax year for the document
        - `doc_year` string, nullable: Document year for the document
        - `extraction_request_status` string, nullable: Extraction request status (computed from extraction jobs). Always None for BUNDLE rows — a bundle has no extraction of its own; read bundle_status instead.
        - `extraction_requested_at` string, date-time, nullable: When extraction was requested (computed from extraction jobs)
        - `extraction_completed_at` string, date-time, nullable: When extraction was completed (computed from extraction jobs)
        - `is_extraction_allowed` boolean: Whether the FE may offer (re-)extraction for this document. True when the document has never been extracted (extraction_request_status is null). Once it has been extracted at least once, true only when the document has a canonical document_type_identifier AND that document type is extraction-enabled (is_active, same semantics as /document/types); false otherwise. Computed by the backend (shared.dms.extraction_eligibility.is_extraction_allowed).
        - `extraction_status` string, nullable: Current status of document extraction (COMPLETED, FAILED, IN_PROGRESS, etc.)
        - `workflow_status` string, nullable: Current status of document workflow (CREATED, IN_PROGRESS, APPROVED, REJECTED, etc.)
        - `extraction_version` 'v1' | 'v2': Which extraction generation a specific document is on. Per-DOCUMENT (vs the per-doctype ``new_extraction_flow_enabled`` flag): the doctype flag says which generation a type uses going forward, but a document already extracted under the old generation stays on it until re-extracted. The frontend uses this to pick the v1/v2 review UI for each document. * ``V2`` — extracted via the v2 flow (data in the new typed store). * ``V1`` — extracted via the legacy flow (data in the legacy store).
        - `is_shared` boolean: True when this document has an active direct share with the client. Use share_id to call DELETE /dms/shares/{share_id} to unshare. Always False when is_shared_via_folder is True.
        - `share_id` string, uuid, nullable: Active direct share ID when is_shared=True.
        - `is_shared_via_folder` boolean: True when this document is inside a directly-shared folder. The client can access it via the folder share. Cannot be independently unshared — move the document or unshare the folder.
        - `folder_share_id` string, uuid, nullable: Share ID of the parent folder when is_shared_via_folder=True. Call DELETE /dms/shares/{folder_share_id} to unshare the entire folder.
        - `open_flag_count` integer: Number of OPEN, visible cross-document/content flags on this document.
        - `top_flag_type` string, nullable: Highest-priority OPEN flag_type — for routing/logic.
        - `top_flag_severity` string, nullable: Severity of the top flag (ERROR | WARNING | INFO) — badge colour.
        - `top_flag_label` string, nullable: Display-ready badge label (backend-owned presentation).
        - `flags` DocumentFlagSummary[]: Every OPEN, visible flag on this document (most-severe first). A document can carry several flags that are each resolved independently — the UI renders one badge per flag.
          - `id` string, uuid, required
          - `flag_type` string, required
          - `family` string, nullable
          - `severity` string, nullable
          - `label` string, required: Display-ready badge label (backend-owned presentation).
  - `summary` FolderSummary, required: Summary information for folder contents
    - `total_items` integer, required
    - `total_folders` integer, required
    - `total_documents` integer, required
    - `total_size` integer, required
  - `pagination` AppSchemasCommonPaginationPaginationMeta, required
    - `page` integer, required: Current page number
    - `page_size` integer, required: Number of items per page
    - `total_count` integer, required: Total number of items
    - `total_pages` integer, required: Total number of pages
    - `total` integer, required: Alias for total_count for backward compatibility

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/signalshq/apis/signals-api.md) - [All operations](https://skmtc.dev/signalshq/apis/signals-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signalshq/apis/signals-api/revisions/2c22af3b5576?raw)