DocumentCategory Metadata Type in SFDX

Overview#

The DocumentCategory metadata type defines a top-level grouping category used by Salesforce’s Document Checklist and Intelligent Document Reader frameworks across Financial Services Cloud, Health Cloud, Public Sector Solutions, Education Cloud, and core CRM orgs.

In complex onboarding, underwriting, or licensing workflows, users upload multiple supporting files against DocumentChecklistItem records. DocumentCategory provides the taxonomy layer above DocumentType (linked via DocumentCategoryDocumentType) so intake Flows, OmniScripts, and compliance reviewers can filter and validate required documents by category (for example, Identity Verification, Tax & Income, or Property Appraisal).

Directory and File Suffix Reference#

Key Metadata Fields#

DocumentCategory is a lightweight taxonomy metadata type extending Metadata.

Querying DocumentCategory via SOQL#

Because DocumentCategory is backed by a setup object accessible in both standard SOQL and Tooling API, you can query it directly to drive dynamic LWC intake screens or Flow screen components:

SELECT Id, DeveloperName, MasterLabel, NamespacePrefix, Description, CreatedDate
FROM DocumentCategory
ORDER BY MasterLabel ASC

Declarative XML and Package.xml Examples#

1. DocumentCategory Definition (Identity_Verification.documentCategory-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<DocumentCategory xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Government-issued photo identification and KYC verification documents required for onboarding.</description>
    <isProtected>false</isProtected>
    <masterLabel>Identity Verification</masterLabel>
</DocumentCategory>

2. Package Manifest (package.xml)#

Deploy DocumentCategory alongside DocumentType and DocumentCategoryDocumentType so the entire classification hierarchy lands in a single atomic transaction:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Identity_Verification</members>
        <members>Income_And_Tax_Proof</members>
        <name>DocumentCategory</name>
    </types>
    <version>68.0</version>
</Package>

3. SFDX CLI Commands#

# Retrieve all DocumentCategory metadata definitions from the org
sf project retrieve start --metadata "DocumentCategory:*"

# Deploy a specific DocumentCategory to the target environment
sf project deploy start --metadata DocumentCategory:Identity_Verification

Architect Best Practices and Gotchas#

• Prerequisite Org Feature (DocumentChecklistSettings): Ensure Document Checklist Items are enabled in the target org (or include DocumentChecklistSettings in your scratch org definition) before deploying DocumentCategory components.
• Consistent Naming Convention: Prefix or group DocumentCategory developer names by domain (for example, KYC_Identity_Verification, KYC_Proof_Of_Address) so administrators can easily distinguish categories across multiple business units sharing the same org.
• Deletion Constraints: You cannot delete a DocumentCategory if any DocumentCategoryDocumentType junction records still reference it. Remove the junction metadata first in destructiveChangesPre.xml before deleting the parent category.

Frequently asked questions

What is the purpose of DocumentCategory in Salesforce?

DocumentCategory groups related DocumentType records into logical compliance buckets, such as Identity Verification, Income Statements, or Regulatory Filings, for use in Document Checklist Items and Action Plan Templates.

How do you associate a DocumentType with a DocumentCategory in Metadata API?

You link a DocumentType to a DocumentCategory by deploying a DocumentCategoryDocumentType junction metadata component that references both the documentCategory and documentType developer names.

Can DocumentCategory metadata be queried via SOQL or Tooling API?

Yes. When Document Checklist features are enabled in the org, you can query the DocumentCategory standard object via SOQL or Tooling API using fields such as Id, DeveloperName, MasterLabel, and Description.

What SFDX folder and file suffix does DocumentCategory use?

DocumentCategory files are stored in the force-app/main/default/documentCategories/ directory with the .documentCategory-meta.xml file extension.