Salesforce

The Salesforce integration pulls CRM data from your Salesforce org — opportunities, stages, leads and owners — into Una so it can power pipeline analytics, forecasting and any custom KPIs you configure.

The integration is read-only. Una never writes back to Salesforce.

Setup is shared between two people. Your Salesforce administrator prepares Salesforce and securely sends three connection details to Una (Part 1). An Una team member then creates and configures the connection in Una (Part 2).

What it does

1. Prepare Salesforce — your Salesforce administrator creates a dedicated integration user and an External Client App, then sends Una the Instance URL, Client ID and Client Secret.
2. Connect — Una uses those details to connect to your org through the OAuth 2.0 Client Credentials flow. This is a secure server-to-server connection that never needs anyone to log in interactively.
3. Configure — you pick which Salesforce fields Una pulls and map your stages to Una model stages.
4. Sync and deploy — Una pulls the configured data into a staging area and deploys it into your model.

What Una reads

Salesforce object	Used for
Opportunity	The core records — amounts, close dates, current stage
OpportunityHistory	Stage progression as actual events
Lead / LeadStatus	Lead records and their status list
OpportunityStage	The stage list Una maps against
Owners	Attribution of records to people

Stage history, not just current state

Una reads OpportunityHistory and LeadHistory, so a deal that moved through three stages in a month is recorded as three transitions rather than a single final position. This is what makes stage-velocity and conversion analysis meaningful.

How Salesforce differs from HubSpot

Both providers normalise into the same shape in Una, so the mapping screens and the resulting model look the same. Three differences are worth knowing before you start:

	HubSpot	Salesforce
Connecting	One-click OAuth consent	An External Client App set up by your Salesforce administrator
Building a Rev IQ model for you	Yes, via a wizard	No — build the model first, then map into it
Pipelines	HubSpot's own pipeline objects	Derived from OpportunityStage and LeadStatus

Salesforce has no pipeline object of its own. Una builds the equivalent from your stage and lead-status lists, which is why the Pipelines screen looks the same for both providers.

Because Una cannot build a Rev IQ model for a Salesforce connection, create the model first. See HubSpot → Build a Rev IQ model for the shape it needs — the model requirements are identical regardless of which CRM feeds it.

Before you start

On the Salesforce side, you'll need:

• A Salesforce administrator who can create users, permission sets and External Client Apps in your org.
• A licence for the integration user. Enterprise and Unlimited editions include free Salesforce Integration licences. A standard Salesforce licence also works.
• A secure way to send credentials to Una, such as an end-to-end encrypted secret manager. See Step 6.

On the Una side, you'll need:

• An Una team member with admin access in Una, since the connection is a tenant-wide setting.
• A model to map into, or the time to create one first.

Part 1 — Prepare Salesforce

For your Salesforce administrator. This part creates a dedicated integration identity and an External Client App that Una connects through. Allow about 30 minutes, plus a short wait for Salesforce to apply the settings.

Step 1 — Create the integration user

Use a dedicated integration user rather than a person's login. If the connection runs as an employee, it breaks when they change their password or leave the company.

1. Go to Setup, enter Users in Quick Find, click Users, then New User.
2. Fill in the name and email — for example, Integration User.
3. User License: select Salesforce Integration, or a standard Salesforce licence. If you use a standard licence, also give the user a specific Role. See the note in Step 2.
4. Profile: select Salesforce API Only System Integrations, or a restricted custom integration profile.
5. Make sure Active is ticked, then save. Note the username — you'll need it in Step 4.

If you already have a suitable integration user, you can reuse it. Check it against the settings above.

Step 2 — Create the permission set

This permission set does two jobs: it pre-authorises the integration user to use the app, and it gives the user read access to the data Una needs.

1. In Quick Find, search for Permission Sets and click New.
2. Set Label to External App Access (the API Name becomes External_App_Access).
3. Leave License set to --None-- so the set can be assigned flexibly, and click Save.
4. Under Object Settings, grant Read and View All on Opportunities and Leads. This covers the objects in What Una reads: opportunity and lead history, the stage and lead-status lists, and record owners all come with access to these two objects. View All stops Salesforce sharing rules from hiding records from the integration user.
5. Click Manage Assignments → Add Assignment, select the integration user, and click Assign.

note

The object permissions only take effect once the user's licence allows them. Choose one of these two options:

• Salesforce Integration licence. Also assign the Salesforce API Integration permission set licence to the user, on the user's record under Permission Set License Assignments.
• A dedicated user with a defined role. If you'd rather not use the Salesforce Integration licence, create the integration user with a standard Salesforce licence, a restricted integration profile, and a specific role. The permission set above then grants the access Una needs.

Either way, keep the user dedicated to Una. Don't reuse a person's login.

tip

Una can pull custom fields too, chosen later on the Data tab. If you know you'll want particular custom fields, make sure the permission set grants read access to them as well (Field Permissions on each object).

Step 3 — Create the External Client App

1. In Quick Find, search for App Manager and select App Manager under Apps.
2. Click New External Client App in the upper-right corner.
3. Complete the Basic Information:
   • External Client App Name: a recognisable name, such as Una_Integration.
   • API Name: fills in automatically from the app name.
   • Contact Email: your team's admin or support distribution email.
   • Distribution State: Local, which restricts the app to this Salesforce org.
4. Scroll to API (Enable OAuth Settings) and tick Enable OAuth.
5. Configure the OAuth details:
   • Callback URL: https://login.salesforce.com/services/oauth2/callback. The Client Credentials flow never redirects, but Salesforce still requires a valid URL here.
   • OAuth Scopes: select Manage user data via APIs (api) and click the Add arrow to move it to Selected OAuth Scopes. Don't add the full scope.
   • Flow Enablement: tick Enable Client Credentials Flow.
6. Click Create (or Save).

Step 4 — Set the app policies and pre-authorise the user

Don't skip this step. Without it, Salesforce rejects every token request with this error:

{"error":"invalid_grant","error_description":"no client credentials user enabled"}

1. In Quick Find, search for External Client App Manager and select it.
2. Click your app's name to open its detail page.
3. Open the Policies tab and click Edit.
4. In the OAuth Policies section (in some orgs, OAuth Flows and External Client App Enhancements):
   • Make sure Enable Client Credentials Flow is ticked.
   • In Run As (Username), search for and select the integration user from Step 1.
5. In the App Policies section (in some orgs, Plugin Policies):
   • Set Permitted Users to Admin approved users are pre-authorized.
   • Under Select Permission Sets, move External App Access from Available into Selected Permission Sets.
6. Click Save at the bottom of the page.

Pre-authorise through the permission set, not through a profile. Pre-authorising a profile would let every user with that profile use the app. A permission set limits it to the integration user alone.

Step 5 — Test the connection

warning

Salesforce takes 2 to 10 minutes to apply new OAuth settings and security policies across its servers. A test run straight after Step 4 can fail even when everything is configured correctly. Wait a few minutes before testing.

Before you send anything to Una, confirm that the app issues tokens. Fill in your Instance URL, Consumer Key and Consumer Secret (see Step 6 for where to find them) and run:

curl -X POST "https://yourcompany.my.salesforce.com/services/oauth2/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CONSUMER_KEY" \
  -d "client_secret=YOUR_CONSUMER_SECRET"

A working setup returns 200 OK with an access_token in the response. If you get invalid_grant instead, see Troubleshooting.

Step 6 — Collect and share the connection details

Una needs three details: the Instance URL, the Client ID and the Client Secret.

Client ID and Client Secret

1. In External Client App Manager, open your app and select the Settings tab.
2. Expand OAuth Settings and click Consumer Key and Secret.
3. Complete the identity verification prompt, using the code sent to your email or authenticator app.
4. Copy the Consumer Key — this is the Client ID.
5. Copy the Consumer Secret — this is the Client Secret.

Instance URL

Copy the base address from your browser's address bar while you're logged in to Salesforce, up to and including .salesforce.com — for example, https://yourcompany.my.salesforce.com. Alternatively, search for My Domain in Quick Find and copy the Current My Domain URL.

Send the details to Una securely

Send all three details to your Una contact using an end-to-end encrypted secret manager, such as Bitwarden Send, 1Password sharing or a temporary password link.

warning

Treat the Client Secret like a password. Anyone with it, the Client ID and your Instance URL can read your Salesforce data as the integration user. If you have to use email, send only the Instance URL and Client ID by email, and send the Client Secret through a separate channel such as SMS, Teams or Slack.

Part 2 — Set up the integration in Una

For the Una team member. Once you've received the three connection details:

Step 7 — Create the connection

1. In Una, go to Settings → Integrations → CRM.
2. Click New Integration, name it (for example Salesforce — EMEA), and pick Salesforce as the provider.
3. Enter the Instance URL, Client ID and Client Secret from the client's Salesforce administrator.

Step 8 — Choose the data and map stages

1. On the Data tab, choose the fields Una should pull.
2. On the Pipelines tab, map your Salesforce stages onto your model's stages.

Step 9 — Deploy and load

Deploy and run the first load. Large orgs sync in batches automatically, so a first full load takes longer than later runs.

Keeping data current

To refresh on a schedule, add the Salesforce Sync activity to a workflow — see Workflow activities → Salesforce Sync.

Security best practices

Practice	Recommendation	Why it matters
API-only integration user	Use a dedicated user with the Salesforce Integration licence and the API-only profile.	No one can log in to the Salesforce UI with the integration account, and the connection doesn't break when someone changes their own password.
Least-privilege scopes	Grant only the api scope. Don't assign the full scope.	Limits what can be exposed if the client credentials are ever leaked.
Pre-authorise by permission set	Pre-authorise through a dedicated permission set rather than a profile.	Pre-authorising a profile admits every user with that profile. A permission set admits only the integration user.
Test before handing over	Run the cURL test in Step 5.	Confirms the token endpoint returns 200 OK with an access_token before Una tries to connect.

Troubleshooting

The token request fails with invalid_grant / no client credentials user enabled. Either the Client Credentials flow isn't enabled in the app's policies, or no Run As user is set. Repeat Step 4.

The token request fails straight after setup. Salesforce can take 2 to 10 minutes to apply new OAuth settings. Wait, then test again.

The sync completed but my model has no data. Loading data into the staging area and populating the model are separate steps. Go to Scenarios → Reload Actuals to populate the model.

A stage is missing from the mapping screen. The stage list comes from OpportunityStage. If a stage was added in Salesforce after your last sync, refresh pipelines before mapping.

Opportunities, leads, stage history or owners are missing entirely. The integration user can't read the underlying objects. Check that the External App Access permission set grants Read and View All on Opportunities and Leads, and that the user's licence allows those permissions. Opportunity and lead history, the stage and lead-status lists, and record owners all depend on access to these two objects. See Step 2.

A custom field is missing or always empty in Una. The integration user can't see that field. In the External App Access permission set, open Object Settings for the field's object and grant Read on the field under Field Permissions. Then run the sync again.

Some records are missing. Check that the integration user has read access to the object and to the specific records. Salesforce sharing rules can hide records from an integration user that an administrator can see. Granting View All in the permission set (Step 2) avoids this.