Skip to content

Commit 335595a

Browse files
atporteratporter
authored
Merge pull request #204 from scarf-sh/daniwinxrose-3
Create Hubspot Integration subpage
2 parents d957f90 + 2970b13 commit 335595a

File tree

1 file changed

+167
-0
lines changed

1 file changed

+167
-0
lines changed

‎docs/hubspot.md

+167
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Hubspot
2+
3+
## HubSpot Requirements
4+
5+
- A Scarf account with an Organization set-up and an active Premium Subscription.
6+
- A HubSpot instance.
7+
8+
## Required Permissions
9+
10+
- **Scarf:**
11+
- Owner or Admin Permissions
12+
- **HubSpot:**
13+
- Account with Super Admin permissions
14+
15+
16+
## Implementation Process
17+
18+
### Creation of a Scarf Application in HubSpot
19+
20+
The Scarf integration to HubSpot is a [Private App](https://developers.hubspot.com/docs/guides/apps/private-apps/overview).
21+
22+
1. Login to HubSpot as a user with App Marketplace and Developer tools permissions
23+
24+
2. Navigate to your `Settings` by clicking the gear icon on the top right.
25+
26+
3. In the left sidebar, click on `Integrations` -> then click `Private apps` -> and select `Create a private app`.
27+
28+
<p align="center">
29+
<img src="https://static-assets.scarf.sh/docs/Hubspot/1%20-%20hubspot%20-%20private%20apps.png" alt="Hubspot Private Apps">
30+
</p>
31+
32+
4. Provide a name for your application such as “Scarf Connection”, optionally enter a Description such as “Scarf Connection to import usage analytics”.
33+
34+
<p align="center">
35+
<img src="https://static-assets.scarf.sh/docs/Hubspot/2%20-%20hubspot%20-%20info.png" alt="Hubspot Info">
36+
</p>
37+
38+
5. Navigate to the `Scopes` tab and configure the desired scopes for the integration.
39+
40+
<p align="center">
41+
<img src="https://static-assets.scarf.sh/docs/Hubspot/3%20-%20hubspot%20-%20scopes.jpg" alt="Hubspot Scopes">
42+
</p>
43+
44+
| Scope Area | Scope Name | Required | Explanation |
45+
|------------|--------------------------------|----------|--------------------------------------------------|
46+
| CRM | `crm.objects.companies.read` | Yes | Required for Scarf to read company objects |
47+
| CRM | `crm.objects.companies.write` | No | Required for Scarf to Create or Update Companies |
48+
| CRM | `crm.objects.contacts.read` | Yes | Required for Scarf to read company objects |
49+
| CRM | `crm.objects.owners.read` | Yes | Required for Scarf to read company objects |
50+
| Other | `sales-email-read` | Yes | Required for Scarf to read company objects |
51+
52+
6. Click the `Create App` button in the top right.
53+
54+
7. Copy the API token presented and make note of it for the Connection and Authentication step below.
55+
56+
<p align="center">
57+
<img src="https://static-assets.scarf.sh/docs/Hubspot/4%20-%20hubspot%20-%20tokens.jpg" alt="Hubspot Tokens">
58+
</p>
59+
60+
61+
### Connection and Authentication
62+
63+
1. Login to Scarf as a user with Owner or Admin permissions.
64+
65+
2. Navigate to `Organization Settings` -> `Integrations`.
66+
67+
<p align="center">
68+
<img src="https://static-assets.scarf.sh/docs/1%20-%20hubspot%20-%20salesforce%20-%20integrations%20button.png" alt="Hubspot Salesforce Integrations Button">
69+
</p>
70+
71+
3. Select `Connect CRM Instance`, confirm you want to sync companies and click `Finish linking CRM`.
72+
73+
<p align="center">
74+
<img src="https://static-assets.scarf.sh/docs/2%20-%20hubspot%20-%20salesforce%20-%20connect%20button.png" alt="Hubspot Salesforce Connect Button">
75+
</p>
76+
77+
4. Click `HubSpot` from the `Select integration` menu.
78+
<p align="center">
79+
<img src="https://static-assets.scarf.sh/docs/Hubspot/7%20-%20husbpot%20-%20select.png" alt="Hubspot Select">
80+
</p>
81+
82+
5. Review the presented data permissions, and click `Next`.
83+
84+
<p align="center">
85+
<img src="https://static-assets.scarf.sh/docs/Hubspot/8%20-%20hubspot%20-%20data%20permissions.png" alt="Hubspot Data Permissions">
86+
</p>
87+
88+
6. When prompted enter your HubSpot Company ID, and click `Next`.
89+
90+
<p align="center">
91+
<img src="https://static-assets.scarf.sh/docs/Hubspot/9%20-%20hubspot%20-%20ID.png" alt="Hubspot ID">
92+
</p>
93+
94+
8. You will now be prompted to enter the API Key generated in the Scarf Application stage, if required this can be retrieved from the `Private App Settings` page.
95+
96+
<p align="center">
97+
<img src="https://static-assets.scarf.sh/docs/Hubspot/10%20-%20hubspot%20-%20API.png" alt="Hubspot API">
98+
</p>
99+
100+
9. Click `Next` and Scarf is now connected to your HubSpot instance.
101+
102+
103+
### Scarf Field Configuration
104+
105+
The HubSpot connection allows you to pair Scarf Surfaced Companies with Account records in HubSpot, and optionally to create new Account records when Company Matches are surfaced. In addition to account records, Scarf will attempt to publish metrics to the HubSpot Account record if a matching Field is found on the account. If no matching Fields are found on an Account Object, Scarf will not update the record. The Fields Scarf will attempt to publish are enumerated here:
106+
107+
| Property Label (suggested) | Internal Name (**required**) | Object Type | Description |
108+
|----------------------------|------------------------------------------------|-------------|---------------------------------------------------------------------|
109+
| Scarf Company | `scarf_company_name` | string | Company Name as determined by Scarf Enrichment |
110+
| Scarf Domain | `scarf_company_domain` | string | Primary Internet Domain of the Company |
111+
| Scarf First Seen | `scarf_first_seen` | date | Date of First Event Scarf observed attributed to this Company |
112+
| Scarf Last Seen | `scarf_last_seen` | date | Date of most recent Event Scarf observed attributed to this Company |
113+
| Scarf Funnel Stage | `scarf_funnel_stage` | string | Current [Adoption Funnel Stage](https://docs.scarf.sh/funnel-stages/) of the Company |
114+
| Scarf Total Events | `scarf_total_events_last_30_days` | number | Total observed events in the last 30 days |
115+
| Scarf Total Uniques | `scarf_total_unique_sources_last_30_days` | number | Unique observed Event Sources (endpoints) in the last 30 days |
116+
| Scarf Events MoM | `scarf_total_events_mom` | number | Change in Total Events over the previous Month |
117+
| Scarf Events WoW | `scarf_total_events_wow` | number | Change in Total Events over the previous Week |
118+
| Scarf Sources MoM | `scarf_total_unique_sources_mom` | number | Change in Unique Sources over the previous Month |
119+
| Scarf Sources WoW | `scarf_total_unique_sources_wow` | number | Change in Unique Sources over the Previous Week |
120+
121+
122+
### Create Scarf data fields in HubSpot
123+
124+
If present and if Write scope has been granted, Scarf will update HubSpot Company records with Scarf [custom properties](https://knowledge.hubspot.com/properties/create-and-edit-properties).
125+
126+
While logged in as a user with Edit property settings permissions:
127+
128+
1. In your HubSpot account, click the `Settings` icon in the top navigation bar.
129+
130+
2. In the left sidebar menu, navigate to `Properties`.
131+
132+
3. Click the `Select an object` dropdown menu, then select `Company properties`.
133+
134+
<p align="center">
135+
<img src="https://static-assets.scarf.sh/docs/Hubspot/11%20-%20hubspot%20-%20select-an-object-properties.webp" alt="Hubspot Select Properties">
136+
</p>
137+
138+
4. Create a `Property Label` for each of the fields described above, as desired.
139+
140+
<p align="center">
141+
<img src="https://static-assets.scarf.sh/docs/Hubspot/12%20-%20hubspot%20-%20property%20edit.webp" alt="Hubspot Property Edit">
142+
</p>
143+
144+
145+
### Synchronization Frequency
146+
147+
Scarf currently synchronizes with your CRM nightly. The duration of the sync is dependent on the volume of records paired. Manual Company matches are queued for the next nightly sync.
148+
149+
### Configuring the Connection
150+
151+
Once the CRM connection has been initialized, the Integrations menu will add three configuration options:
152+
153+
**Enable Scarf to connect Insights to this CRM**
154+
Toggling this to **off** will temporarily disable the CRM integration. While **off** no reading or writing will be attempted.
155+
156+
**Auto-match to known Accounts from Scarf**
157+
With the integration **enabled**, you have the option to set Scarf to to use text pattern matching to pair existing CRM Accounts with surfaced Scarf Companies. If the setting is **off** then all mapping will be performed manually.
158+
159+
**Automatically create new Accounts in your CRM**
160+
With the integration **enabled**, you also have the option to set Scarf to attempt to create a new Account record in your CRM when the sync process encounters a Company without a match in the CRM. This will include historical matches as well as any newly surfaced companies.
161+
162+
<p align="center">
163+
<img src="https://static-assets.scarf.sh/docs/Hubspot/13%20-%20hubspot%20-%20configurations.png" alt="Hubspot Configurations">
164+
</p>
165+
166+
167+
**NOTE:** By default, all options will be turned on except for Auto-Sync, which will be off. Since Auto-Sync automatically creates records, it is disabled by default to prevent unintended data updates. Users can enable it manually once they have reviewed their setup.

0 commit comments

Comments
 (0)