CareBenefitVerifySettings Metadata Type in SFDX

Architectural Overview#

In Salesforce Health Cloud and Life Sciences Cloud, care coordinators and patient access specialists must verify a patient’s active health insurance coverage, copays, deductibles, and prior-authorization requirements before scheduling treatments. The CareBenefitVerifySettings metadata type configures the integration wiring for Health Cloud’s automated Benefit Verification component and ANSI X12 270/271 or FHIR CoverageEligibilityRequest clearinghouse callouts.

Architecturally, CareBenefitVerifySettings decouples the UI/Flow verification request (CareBenefitVerifyRequest) from hardcoded integration endpoints by binding the verification service to a Salesforce NamedCredential, relative uriPath, and default requesting provider/organization National Provider Identifier (NPI) attributes.

SFDX Directory & File Suffix#

Key Metadata Fields#

The CareBenefitVerifySettings metadata type includes the following declarative XML fields:

Declarative XML & package.xml Examples#

SFDX Source File Example#

<?xml version="1.0" encoding="UTF-8"?>
<CareBenefitVerifySettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <defaultNpi>1234567893</defaultNpi>
    <defaultOrganizationName>Acme Regional Health System</defaultOrganizationName>
    <defaultServiceTypeCode>30</defaultServiceTypeCode>
    <generalPlanNamedCredential>Clearinghouse_Eligibility_API</generalPlanNamedCredential>
    <isDefault>true</isDefault>
    <masterLabel>National Clearinghouse Benefit Verification</masterLabel>
    <uriPath>/api/v2/coverage-eligibility/check</uriPath>
</CareBenefitVerifySettings>

Package Manifest (package.xml)#

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

Querying via SOQL & SFDX CLI#

Inspect deployed CareBenefitVerifySettings configurations in a Health Cloud org using SOQL:

SELECT Id, DeveloperName, MasterLabel, IsDefault, GeneralPlanNamedCredential,
       UriPath, DefaultNpi, DefaultOrganizationName
FROM CareBenefitVerifySettings
ORDER BY IsDefault DESC, DeveloperName ASC

Retrieve and deploy CareBenefitVerifySettings with Salesforce CLI:

# Retrieve CareBenefitVerifySettings metadata
sf project retrieve start --metadata CareBenefitVerifySettings:National_Clearinghouse_BV

# Deploy NamedCredential and CareBenefitVerifySettings together
sf project deploy start --metadata NamedCredential:Clearinghouse_Eligibility_API CareBenefitVerifySettings:National_Clearinghouse_BV

Senior Architect Best Practices & Gotchas#

• Named Credential Dependency: Deploying CareBenefitVerifySettings will fail if the NamedCredential referenced in <generalPlanNamedCredential> does not exist in the target org. Always include the NamedCredential in the same deployment package.
• Health Cloud License Prerequisite: The CareBenefitVerifySettings metadata type is only available in orgs provisioned with the Health Cloud (HealthCloudAddOn) license and permission set licenses.
• Single Default Rule: Ensure only one CareBenefitVerifySettings record has <isDefault>true</isDefault> so standard Health Cloud Benefit Verification Lightning components know which clearinghouse endpoint to invoke by default.

Frequently asked questions

What is CareBenefitVerifySettings used for in Salesforce Health Cloud?

It defines the integration endpoint settings, Named Credential references, and default provider details used when verifying patient insurance benefits with external clearinghouses or payers.

Where are CareBenefitVerifySettings files stored in SFDX source format?

They are stored in the force-app/main/default/careBenefitVerifySettings/ directory with the .careBenefitVerifySettings-meta.xml file extension.

How does CareBenefitVerifySettings handle authentication to external clearinghouses?

It references a Salesforce NamedCredential via the generalPlanNamedCredential anduriPath fields, ensuring credentials and OAuth tokens are never hardcoded in metadata.

Can I query CareBenefitVerifySettings using SOQL or Tooling API?

Yes, CareBenefitVerifySettings is exposed as a setup object queryable via SOQL and Tooling API in orgs with Health Cloud enabled.