Skip to content
AptiroAptirodocs
Menu: Connect Salesforce

Integrations

Connect Salesforce

On this page

Connecting Salesforce links your organisation's Salesforce to Aptiro, so Aptiro can work alongside the CRM your people already use. This page covers the connection itself: setting it up, checking it, reconnecting and disconnecting. What Aptiro then does with the connection arrives in later releases.

You connect through an app you create in your own Salesforce. There is no shared Aptiro app: the access belongs to your Salesforce alone, and you can see, change or remove it there at any time. The connection belongs to your organisation, not to one person, and only someone who can manage settings (an owner or admin) can set it up or disconnect it. You also need to be a Salesforce administrator.

Salesforce changes its screens from time to time, so a label below may be named slightly differently in your org. Where we are less sure, we say so.

Step 1: Create an External Client App in Salesforce

  1. In Salesforce, go to Setup and open App Manager (search for it in Quick Find). Select New External Client App.
  2. Give it a name such as "Aptiro", and an email address for contact. Set the distribution state to Local, because the app is used only in your own org (this may be labelled differently).
  3. Under API (Enable OAuth Settings), turn on Enable OAuth.
  4. Copy the callback URL from Settings > Integrations > Salesforce in Aptiro (there is a copy button) and paste it as the app's Callback URL. It looks like https://app.aptiro.io/api/settings/salesforce/callback.
  5. Add these OAuth scopes. Aptiro asks for nothing beyond them:
    • Manage user data via APIs (api), so Aptiro can read your records now and, in a later release, write back to them. It never gives Aptiro your password.
    • Perform requests at any time (refresh_token), so the connection keeps working without anyone signing in again.
    • Access the identity URL service (id), so Aptiro can show who connected.
  6. Turn on Require Proof Key for Code Exchange (PKCE) and leave the web server flow enabled (these may be labelled differently).
  7. Create the app. Then open its Policies and set Permitted Users to Admin approved users are pre-authorized (this may be labelled differently). Grant access to the users who will connect, by profile or by permission set, so that they can approve it.
  8. Open the app's Settings and find the Consumer Key and Consumer Secret. Salesforce may email you a verification code before it shows them. It can take a few minutes after you create the app for it to work.

Step 2: Give Aptiro your app's details

  1. In Aptiro, go to Settings > Integrations and find Salesforce.
  2. Under Step 1: Your Salesforce app, paste the Consumer Key and Consumer Secret, then select Save app details.

The key and secret are kept in a dedicated secret store, tied to your organisation. They are not in the database that holds your accounts, deals and contacts, and they are never sent back to your browser, whatever your role. That is why the fields are always empty: Aptiro shows only that they are saved.

Step 3: Connect

  1. Under Step 2: Connect, choose Production, Sandbox or My Domain. Use Sandbox to try the connection against a Salesforce sandbox first. Choose My Domain if your org blocks the standard sign-in addresses (login.salesforce.com and test.salesforce.com): enter your org's own address, for example https://acme.my.salesforce.com. It must end in .my.salesforce.com, start with https://, and carry no port or path; Aptiro accepts nothing else, and signs in only at the address saved for your organisation. To change the address, disconnect first, then connect again.
  2. Select Connect Salesforce. It stays off until step 1 is saved and, for My Domain, until the address is valid.
  3. Sign in to Salesforce and approve the access it describes.
  4. You come back to Settings. The Connection section lists Salesforce user, Org address, Sign-in (Production, Sandbox or My Domain) and Connected on.

The access Salesforce then gives Aptiro is kept in the same secret store.

If Salesforce revokes access

If someone removes Aptiro's access in Salesforce, or it expires, the panel shows Needs reconnecting and nothing is read from Salesforce until it is fixed. Select Reconnect Salesforce, sign in and approve again.

Change your app details

Once connected, the Consumer Key and Secret sit under Salesforce app, which starts closed. Open Salesforce app to see the fields. Enter a new Consumer Key and Secret and select Replace app details. The old values are never shown. Replacing them disconnects Salesforce, because access granted through one app does not carry over to another: Aptiro revokes the current access, deletes it, and you connect again.

Disconnect, or remove your app details

  • Disconnect Salesforce revokes Aptiro's access at Salesforce and deletes the stored access. Your app details stay, so you can connect again straight away. Anything already brought into Aptiro stays.
  • Remove app details also deletes the saved Consumer Key and Secret, and disconnects Salesforce if it is connected.

If Salesforce does not confirm the revoke (for example, it was unreachable at that moment), Aptiro still removes its own copy and tells you. In that case, also remove the app's access in Salesforce.

Syncing

Once Salesforce is connected, Aptiro reads from it every night: your accounts, contacts and opportunities. The first night brings in everything; after that it reads only what has changed.

  • Map your stages first. Until you have saved your stage mapping once (see Stage mapping), nothing is read: the panel shows Map your stages in place of Sync now, and the nightly read skips your organisation. This stops every opportunity landing in your first stage. Saving with every stage left on Automatic counts. Organisations that have already synced are not held back.

  • Salesforce wins on the fields it fills. If a mapped field differs between the two, the Salesforce value replaces the Aptiro one. Everything else is left alone: your notes, custom fields, classifications, signals and activity are never changed by a sync.

  • Deletes unlink. A record deleted in Salesforce is not deleted in Aptiro. It is unlinked from Salesforce and stays in Aptiro as an ordinary record.

  • Contacts need an account. A contact with no account in Salesforce is skipped, and counted as skipped.

  • A long sync carries on. If a sync runs out of time, or Salesforce asks Aptiro to slow down, it stops cleanly and the next night picks up where it left off. The panel says Partly synced, continues tonight.

Sync now

The Sync section of the Salesforce panel shows when the last sync ran, how it ended, and how many records were added, updated, unlinked and skipped. Select Sync now to run one straight away. Anyone who can manage settings can do this.

  • Sync now can be used once every 15 minutes. Until then the button is off and the panel says when it is next available.
  • It is also off while a sync is already running. The panel updates itself every few seconds and tells you when the sync has ended.
  • If a sync fails, the panel says why in plain words. If Salesforce has revoked access, it asks you to reconnect.

Opportunity contacts

The people listed on an opportunity in Salesforce (its contact roles) become contacts on the matching deal in Aptiro, when both the opportunity and the contact have been brought in. A contact role whose deal or contact is not in Aptiro is skipped. Aptiro only adds these links: if someone is removed from an opportunity in Salesforce, or you remove them from the deal in Aptiro, the other side is not changed.

Stage mapping

By default a Salesforce opportunity stage becomes the Aptiro stage with the same name, or, if there is none, the first stage with the same outcome (open, won or lost). Stage mapping lets you choose instead.

  1. In Settings > Integrations > Salesforce, select Edit stage mapping. Aptiro reads your current Salesforce stages each time you open it.
  2. For each Salesforce stage, choose an Aptiro stage, or leave Automatic.
  3. Select Save stage mapping.

Before the first sync, the Sync section shows Map your stages, which opens this section. Sync now appears once you have saved.

  • Infer suggests a mapping. Select Infer to fill the rows with a suggestion. It uses an AI model, sent only your Salesforce stage names, order and won or closed flags, and your Aptiro stage names, order, outcomes and probabilities: no account, contact or deal data. If the model is unavailable it matches by name and order instead, and the message tells you which was used. A won or lost stage is only ever matched to a stage with the same outcome. Infer saves nothing: review the rows, change any you disagree with, then save. It does not use AI credits, and can be used 10 times an hour.
  • A change applies from the next sync. Deals already in Aptiro move to the mapped stage the next time their opportunity changes in Salesforce, or when you use Apply to synced deals.
  • Apply to synced deals. Once Salesforce has synced, and with your changes saved, select Apply to synced deals and confirm. Aptiro re-reads each synced deal's current Salesforce stage and moves the deal to the stage your mapping gives it. Each move is recorded in the deal's stage history and clears a probability set by hand. Only the stage changes: a deal's status is left alone, and a deal whose Salesforce stage is not mapped or named like one of yours stays where it is. The message gives the counts moved, already in place and skipped. It is safe to run again, and it is not available while a sync is running.
  • Won and lost stay right. A won opportunity can only be mapped to a won stage, and a lost one to a lost stage. A mapping that disagrees with the opportunity is ignored for that opportunity, and the automatic rule is used.
  • If you delete a stage you mapped to, deals fall back to the automatic rule until you choose another.
  • Anyone who can manage settings can change the mapping.

Last updated 2026-10-28

Search the documentation