Salesforce Implementation Guide

Set up the Salesforce back-end connection and the embedded ZAP using External Client Apps.

Environment Considerations

URLs containing "sandbox" (e.g., https://zap.sandbox.zushealth.com) should be updated for production (e.g., https://zap.zushealth.com).

A Note on Connected Apps

Earlier versions of this guide used Connected Apps. Salesforce's Spring '26 release disabled the creation of new Connected Apps by default (existing Connected Apps continue to work), so this guide now uses External Client Apps, their successor. If you previously set up the Zus integration with Connected Apps, no migration is required at this time.

Note: Salesforce's built-in "Migrate to External Client App" tool does not support Canvas-enabled apps, so the embedded ZAP app below is created from scratch rather than migrated.

Prerequisite: if you don't see a "New External Client App" option in App Manager, your org has not opted in to external client apps yet. From Setup, go to "External Client App Settings" and select "Opt in to External Client Apps".

Setting up the Back-end Connection

  1. From the Salesforce Setup screen, go to App Manager and click "New External Client App".

  2. In the New External Client App screen:

    • Use whatever you like for the app name and API name
    • Use [email protected] for the contact email
    • Leave the Distribution State as "Local"
    • Check "Enable OAuth"
    • Use https://zushealth.com for the Callback URL (this doesn't make any difference)
    • Select "Manage user data via APIs (api)" for the Selected OAuth Scopes
    • Under Flow Enablement, check "Enable Client Credentials Flow"
  3. After clicking Save you'll be on the Detail screen for the external client app. Edit its policies:

    • Under OAuth Policies, check "Enable Client Credentials Flow" again
    • Select a service account to Run As. The integration's API access uses this user's permissions, so we recommend a dedicated integration user granted only the permissions the integration needs (API access and access to the Person Account or Contact records being synced) rather than a full admin.
  4. From the app's Settings, under OAuth Settings:

    • Click "Consumer Key and Secret" (this will trigger a user verification process)
    • Copy the consumer key and secret and securely share with Zus using a secret sharing utility
  5. Confirming Success:

    • Once Zus has configured the consumer key and secret, verify by making this request:
    POST https://ehr-hooks.sandbox.zusapi.com/backfill-request
    {
        "data": {
            "type": "backfill-request",
            "attributes": {
                "ignoreRateLimit": true
            },
            "relationships": {
                "builder": {
                    "data": {
                        "type": "auth/builder",
                        "id": "{your-builder-id}"
                    }
                },
                "resources": {
                    "data": [
                         {
                             "type": "fhir/Patient",
                             "identifierSystemURL": "https://salesforce.com/account-id",
                             "identifierValue": "{a-patient-account-id}"
                         }
                    ]
                }
            }
        }
    }

Setting up the Embedded ZAP

Note: it is important to follow every step in this section. If you receive an error message when launching the ZAP then it is likely that something was not configured correctly, often in the OAuth policies.

Note: Canvas support for external client apps was added in the Spring '26 Salesforce release. If the Canvas settings described below are not available, confirm your org is on Spring '26 or later.

  1. From the Salesforce App Manager, click "New External Client App". In the New External Client App screen:

    • Name the app "ZusEmbeddedZAP", use the same settings as above otherwise
    • Check "Enable OAuth"
    • Use https://zap.sandbox.zushealth.com/salesforce/v1?clientId=XXX for the callback URL (XXX will be replaced with your consumer key later)
    • Select "Manage user data via APIs (api)" for the Selected OAuth Scopes
    • Check only "Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows"
  2. Under the app's Canvas settings:

    • Enable Canvas
    • Use the same URL as above for the Canvas App URL
    • Select "OAuth Webflow (GET)" for the Access Method
    • Select "Visualforce Page" for the Locations
    • Click Save, which will take you to the Detail screen for the external client app
  3. From the Detail screen, edit the app's policies:

    • Under OAuth Policies, select "Admin approved users are pre-authorized" for Permitted Users
  4. Under App Policies (right above OAuth Policies), assign Profiles and Permission Sets as appropriate for users to access Zus. This is dependent on the customer's Salesforce configuration.

  5. From the app's Settings, under OAuth Settings:

    • Click "Consumer Key and Secret" to get the consumer key and secret
    • Update the 2 URLs (callback URL and Canvas App URL) to include your consumer key as the clientId parameter - this must be the consumer key generated while following the instructions for setting up the embedded ZAP
  6. Configure Salesforce security settings:

    • Add https://zap.sandbox.zushealth.com to the CORS Allowed Origins List and check "Enable CORS for OAuth endpoints"
    • Add https://zap.sandbox.zushealth.com to the Trusted URLs list and check "frame-src" under CSP Directives
    • Add https://zap.sandbox.zushealth.com to the Remote Site Settings list
  7. Create a new Visualforce Page:

    • Use "ZusEmbeddedZAP" for the label and name - this is going to match the name set above
    • Check "Available for Lightning Experience, etc."
    • Use the following Visualforce Markup:
    <apex:page standardController="Account">
       <apex:canvasApp scrolling="yes" applicationName="ZusEmbeddedZAP" width="100%" height="600px"/>
    </apex:page>
  8. From a Record Page:

    • Select "Edit Page" to enter the Lightning App Builder
    • Add a Visualforce Page component where you want the embedded ZAP
    • Select "ZusEmbeddedZAP" for the Visualforce Page Name
  9. Confirming Success:

    • Go to the record page you just edited and the embedded ZAP should be visible for the patient

Related pages


Did this page help you?