> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanintelligence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce

> Connect account, opportunity, and rep-level revenue data to measure pipeline, accounts per rep, and revenue by region.

Salesforce's API lets us pull account, opportunity, and rep-level revenue data to power reporting on accounts per rep, pipeline, and revenue by region. Setup happens entirely in your own Salesforce org — you create a dedicated integration user, a permission set that scopes exactly what we can read, and an app that authenticates as that user. No data leaves your org until you share credentials with us at the end. You'll need System Administrator access (or "Customize Application" + "Manage Connected Apps" permissions) to complete this setup.

### Create an integration user

This is a dedicated, non-human user that our API calls will run as — it should not belong to a real person.

* In Setup, create a new user with the **Salesforce Integration** user license.
* **Profile:** **Minimum Access – API Only Integrations** (or an equivalent minimal, API-only profile).
* **Name:** `Human Intelligence Integration`

### Create a permission set for data access

This is what actually bounds what we can read — the OAuth scope in step 3 only controls what the app's grant type is allowed to request, not which objects or fields are visible.

* Create a new permission set using the **Salesforce API Integration** permission set license with **Read-only** access, and assign it to the integration user from step 1.
* Under **System Permissions** enable **View Roles and Role Hierarchy** for sales hierarchy / manager-rollup data, and **View All Users** so we see every user regardless of your org's role hierarchy or user-visibility settings.
* Grant **Read** on the objects below (skip any row your org doesn't use), and for each object also check **Read Access** in **Field Permissions** for every field you want us to pull. Leave **Edit Access** unchecked and skip **View All Fields**.

| Object                   | Why we need it                                                                  | Applies if...                          |
| ------------------------ | ------------------------------------------------------------------------------- | -------------------------------------- |
| Account Teams            | Accounts worked per AE / CSM / SE, beyond the single owner.                     | Account Teams is enabled               |
| Accounts                 | Account size, revenue, region — the base unit for "accounts per rep."           | Always                                 |
| Assets                   | Installed products per customer — renewal, expansion, and whitespace analysis.  | You track installed products/assets    |
| Campaigns                | Marketing/sales campaigns, for pipeline source attribution.                     | Always                                 |
| Cases                    | Support load per account — capacity and churn signal.                           | You use Salesforce for support/service |
| Contacts                 | Buyer-side stakeholders linked to accounts and opportunities.                   | Always                                 |
| Contracts                | Renewals, term length, contracted ARR.                                          | You use the Contracts feature          |
| Email Messages           | Logged emails per rep and per deal — outbound activity metrics.                 | You log emails to Salesforce           |
| Events                   | Meetings per rep and per deal, including attendees.                             | Always                                 |
| Leads                    | Top-of-funnel pipeline before conversion to an opportunity.                     | Always                                 |
| Opportunities            | Pipeline, revenue growth, new vs. expansion vs. renewal.                        | Always                                 |
| Opportunity Contact Role | Which contacts are involved in a deal, and their role.                          | Always                                 |
| Opportunity Product      | Revenue by product / product mix.                                               | You track products on opportunities    |
| Orders                   | Order-level renewal and revenue detail.                                         | You use the Orders feature             |
| Price Book Entries       | Per-price-book pricing, referenced by Opportunity Product.                      | You track products on opportunities    |
| Price Books              | Price book context for products.                                                | You track products on opportunities    |
| Products                 | Product names, referenced by Opportunity Product.                               | You track products on opportunities    |
| Quote                    | Formal sales quotes/proposals, for quote-to-close cycle time.                   | Quotes is enabled                      |
| Quote Line Item          | Per-product line items on a quote.                                              | Quotes is enabled                      |
| Tasks                    | Logged calls, emails, and to-dos per rep and per deal — activity/touch metrics. | Always                                 |

<Info>
  **Custom fields:** if your org tracks concepts like ARR/MRR, customer segment, health score, CSM assignment, renewal date, or churn risk as custom fields on Account or Opportunity, grant **field-level security: Read** on those specific fields too. Field names vary by org — when you share credentials in step 5, also send us the API names (e.g. `ARR__c`) of any custom fields you'd like included, so we can map them correctly.
</Info>

### Create an External Client App

* In Setup, open **App Manager** (Quick Find box, or Platform Tools → Apps in the left nav), then click **New External Client App**.
* **Name:** `Human Intelligence Data Sync`
* **API Name:** defaults to the name above with underscores in place of spaces, which already satisfies Salesforce's rules, so you can leave it as-is. It must use only letters, numbers, and underscores; be unique; start with a letter; and can't have spaces, a trailing underscore, or two consecutive underscores.
* **Contact Email:** an address Salesforce can use to reach you or your team about this app. It's used only by Salesforce, not shared with admins who install the app, so any address your team monitors works.
* **Distribution State:** Local — this app is for your own org, not for packaging and distribution (e.g. on AppExchange).
* In the OAuth Settings area, select **Enable OAuth** to expand the OAuth fields.
* **Callback URL:** this field is required by Salesforce even though the client credentials flow is server-to-server and never redirects a browser here. Enter any HTTPS URL you control, e.g. `https://login.salesforce.com/services/oauth2/callback` — it just needs to satisfy validation and is never actually called.
* Select the OAuth scope below.

| OAuth Scope                       | Why we need it                                                                                                                                                                                                                                          |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Manage user data via APIs `(api)` | *Required.* The only scope needed — grants REST/SOQL API access. The client credentials flow doesn't use refresh tokens, so `refresh_token`/`offline_access` aren't needed. Don't select `full` or `web` — broader than what this integration requires. |

Click **Create** to save the app before continuing — the policy settings in step 4 aren't available until the app exists.

### Enable the client credentials flow

* Open the app in **External Client App Manager** and go to its **Policies** tab.
* Under **OAuth Policies → Plugin Policies**, set **Permitted Users** to **Admin approved users are pre-authorized** first — the profile/permission set pickers below stay disabled until this is set.
* Under **App Policies → Select Permission Sets**, move the permission set from step 2 to **Selected Permission Sets**. You can't add the integration user directly here — this list only takes permission sets, and any user holding it becomes authorized to use the app.
* Under **OAuth Policies → OAuth Flows and External Client App Enhancements**, check **Enable Client Credentials Flow** — this reveals a **Run As (Username)** field. Set it to the integration user's **Username** from step 1 — not your own login email. Every API call this app makes will act with that user's exact data access, so double-check it's pointed at the integration user, not an admin account.

### Enter your credentials

Salesforce can take a few minutes to propagate a new app — if you see an "invalid client id" error right after saving, wait a bit and retry before assuming something's misconfigured.

Open the app in App Manager, go to its **Settings** tab, open **OAuth Settings**, then click **Consumer Key and Secret** to reveal them.

* Click **Connect** above to open the connection form.
* Enter your **Consumer Key** as the Client ID and your **Consumer Secret** as the Client Secret.
* Enter your org's Salesforce domain (e.g. `yourcompany.my.salesforce.com`, found under Setup → Company Settings → My Domain) as the Company Domain.
* Click **Connect** to save.

The connection form doesn't have a field for custom field API names — if you granted access to any in step 2 (e.g. your org's ARR or Segment field), send those to us separately.

<Warning>
  **Important:** you can view the Consumer Key and Secret again anytime from **Settings → OAuth Settings**. If you ever need to rotate the secret, you can regenerate it from the same place — just let us know so we can update it on our end too.
</Warning>