> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehatchapp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# HubSpot v2
> What Hatch's HubSpot v2 integration is, how it works, and where to begin.
### What does the HubSpot v2 integration do?
Hatch offers a native integration with Hubspot that you can activate within the App
Marketplace (located in your Hatch workspace). This integration syncs HubSpot contacts, companies, and deals into
Hatch so you can target them in campaigns, and logs Hatch activity back into HubSpot as notes.
The Hubspot v2 integration syncs contacts, companies, and deals from HubSpot every **5 minutes** via scheduled reads.
When the integration is first installed, Hatch automatically runs a 90 day back-sync of your HubSpot
data.
### How do you set up the integration?
#### **Requirements**
You will need the following to set up the integration:
* Hatch account with manager privileges
* HubSpot account with permission to install apps and grant access to contacts, companies, and deals
#### **Setup Steps**
1. In Hatch, open the **App Marketplace**.
2. Under the **CRMs** filter, click the Connect button for **HubSpot v2**.
3. In the setup window, click **Install**.
4. Hatch uses OAuth to connect with HubSpot. Log in to your HubSpot account, choose the HubSpot portal you want to
connect, and authorize the connection.
5. Review the objects Hatch will read — **Contacts**, **Companies**, and **Deals** — and confirm the field selections
for each. Required fields are pre-selected for you; all remaining HubSpot properties, **including your custom
properties**, must be manually enabled by checking off each field. To enable all fields, check "Select all fields."
6. Answer the optional mapping prompts so Hatch knows which HubSpot property to treat as each value (see
**Configuration Options** below).
7. **For each object**, ensure to select "Install" (or "Save" if not the first object being installed) to setup the integration. When finished, a green checkmark will appear next to the object.
8. Once activated, a 90 day back-sync of your HubSpot data will automatically initiate.
9. After the back-sync completes, set up your audience and campaign workflow to launch your HubSpot contacts into a
campaign.
#### Configuration Options
During setup you are asked to point a handful of Hatch values at the HubSpot property that holds them. These prompts
exist because HubSpot has no standard property for these values, and every portal models them differently:
* **Contact status** — the contact property Hatch should read as the opportunity status.
* **Company email** — the company property to use as the email address for contacts generated from a company.
* **Company first name** and **Company last name** — the company properties to use as the name for contacts
generated from a company.
* **Company status** — the company property Hatch should read as the opportunity status.
* **Deal status** — the deal property Hatch should read as the opportunity status (commonly the deal stage).
### When does Hatch sync data to/from HubSpot?
#### HubSpot → Hatch
HubSpot data reaches Hatch two ways:
* **Every 5 minutes** — Hatch reads contacts, companies, and deals that have changed since the last read.
* **On install** — a 90 day back-sync of all three object types runs automatically.
#### Hatch → HubSpot
**Sync Communications**
When a Hatch communication occurs on a HubSpot-sourced opportunity, Hatch writes it into HubSpot as a **Note**
engagement and associates that note with the HubSpot record the communication belongs to — the contact, the company,
or the deal.
* When a Hatch campaign sends a text/email/voicemail to a contact
* When a contact calls or sends a text/email/voicemail to a Hatch workspace
* When a Hatch user calls or sends a text/email to a contact
Push communications occur instantaneously. There must be a HubSpot-sourced opportunity in Hatch at the time of the
communication event in order for it to succeed.
### What HubSpot data is available in Hatch?
#### Selecting Object Resources
Object selection happens during setup. Hatch reads three HubSpot resources — **Contacts**, **Companies**, and
**Deals** — and for each one a small set of required fields is pre-selected (the fields Hatch maps to its
standard fields). Every other field HubSpot returns for those objects, **including your custom properties**, can be enabled during setup.
HubSpot object names and Hatch object names differ. A HubSpot **company** is an `account` in Hatch, and a HubSpot
**deal** is an `opportunity` in Hatch. The detail field prefixes below follow the Hatch names.
#### Available Resource Fields
Every HubSpot property returned for a contact, company, or deal lands in the matching opportunity's details, under
the `contact:`, `account:`, or `opportunity:` prefix. Custom properties are included. By default a property is
treated as **text**.
The properties listed below are the exception: Hatch recognizes them as **dates, numbers, or true/false values**, so
you can build audience rules on them using date ranges and numeric comparisons rather than text matching. Any HubSpot
property that isn't on this list — including all of your custom properties — is still available, as text.
| Resource | Field Name | Data Type |
| ------------------ | ---------------------------------------------------------- | --------- |
| Account (Company) | `account:annualrevenue` | Number |
| Account (Company) | `account:closedate` | Date |
| Account (Company) | `account:createdate` | Date |
| Account (Company) | `account:days_to_close` | Number |
| Account (Company) | `account:engagements_last_meeting_booked` | Date |
| Account (Company) | `account:facebookfans` | Number |
| Account (Company) | `account:first_contact_createdate` | Date |
| Account (Company) | `account:first_conversion_date` | Date |
| Account (Company) | `account:first_deal_created_date` | Date |
| Account (Company) | `account:hs_analytics_first_timestamp` | Date |
| Account (Company) | `account:hs_analytics_first_visit_timestamp` | Date |
| Account (Company) | `account:hs_analytics_last_timestamp` | Date |
| Account (Company) | `account:hs_analytics_last_visit_timestamp` | Date |
| Account (Company) | `account:hs_analytics_latest_source_timestamp` | Date |
| Account (Company) | `account:hs_analytics_num_page_views` | Number |
| Account (Company) | `account:hs_analytics_num_visits` | Number |
| Account (Company) | `account:hs_created_by_user_id` | Number |
| Account (Company) | `account:hs_is_enriched` | Boolean |
| Account (Company) | `account:hs_is_target_account` | Boolean |
| Account (Company) | `account:hs_last_booked_meeting_date` | Date |
| Account (Company) | `account:hs_last_logged_call_date` | Date |
| Account (Company) | `account:hs_last_open_task_date` | Date |
| Account (Company) | `account:hs_last_sales_activity_timestamp` | Date |
| Account (Company) | `account:hs_lastmodifieddate` | Date |
| Account (Company) | `account:hs_num_blockers` | Number |
| Account (Company) | `account:hs_num_child_companies` | Number |
| Account (Company) | `account:hs_num_contacts_with_buying_roles` | Number |
| Account (Company) | `account:hs_num_decision_makers` | Number |
| Account (Company) | `account:hs_num_open_deals` | Number |
| Account (Company) | `account:hs_object_id` | Number |
| Account (Company) | `account:hs_parent_company_id` | Number |
| Account (Company) | `account:hs_total_deal_value` | Number |
| Account (Company) | `account:hs_updated_by_user_id` | Number |
| Account (Company) | `account:hubspot_owner_assigneddate` | Date |
| Account (Company) | `account:is_public` | Boolean |
| Account (Company) | `account:notes_last_contacted` | Date |
| Account (Company) | `account:notes_last_updated` | Date |
| Account (Company) | `account:notes_next_activity_date` | Date |
| Account (Company) | `account:num_associated_contacts` | Number |
| Account (Company) | `account:num_associated_deals` | Number |
| Account (Company) | `account:num_contacted_notes` | Number |
| Account (Company) | `account:num_conversion_events` | Number |
| Account (Company) | `account:numberofemployees` | Number |
| Account (Company) | `account:recent_conversion_date` | Date |
| Account (Company) | `account:recent_deal_amount` | Number |
| Account (Company) | `account:recent_deal_close_date` | Date |
| Account (Company) | `account:total_revenue` | Number |
| Account (Company) | `account:twitterfollowers` | Number |
| Contact | `contact:closedate` | Date |
| Contact | `contact:createdate` | Date |
| Contact | `contact:days_to_close` | Number |
| Contact | `contact:engagements_last_meeting_booked` | Date |
| Contact | `contact:first_conversion_date` | Date |
| Contact | `contact:first_deal_created_date` | Date |
| Contact | `contact:hs_analytics_average_page_views` | Number |
| Contact | `contact:hs_analytics_first_timestamp` | Date |
| Contact | `contact:hs_analytics_first_visit_timestamp` | Date |
| Contact | `contact:hs_analytics_last_timestamp` | Date |
| Contact | `contact:hs_analytics_last_visit_timestamp` | Date |
| Contact | `contact:hs_analytics_num_event_completions` | Number |
| Contact | `contact:hs_analytics_num_page_views` | Number |
| Contact | `contact:hs_analytics_num_visits` | Number |
| Contact | `contact:hs_analytics_revenue` | Number |
| Contact | `contact:hs_contact_enrichment_opt_out` | Boolean |
| Contact | `contact:hs_contact_enrichment_opt_out_timestamp` | Date |
| Contact | `contact:hs_content_membership_email_confirmed` | Boolean |
| Contact | `contact:hs_content_membership_follow_up_enqueued_at` | Date |
| Contact | `contact:hs_content_membership_registered_at` | Date |
| Contact | `contact:hs_content_membership_registration_email_sent_at` | Date |
| Contact | `contact:hs_created_by_user_id` | Number |
| Contact | `contact:hs_email_bad_address` | Boolean |
| Contact | `contact:hs_email_bounce` | Number |
| Contact | `contact:hs_email_click` | Number |
| Contact | `contact:hs_email_delivered` | Number |
| Contact | `contact:hs_email_first_click_date` | Date |
| Contact | `contact:hs_email_first_open_date` | Date |
| Contact | `contact:hs_email_first_reply_date` | Date |
| Contact | `contact:hs_email_first_send_date` | Date |
| Contact | `contact:hs_email_last_click_date` | Date |
| Contact | `contact:hs_email_last_open_date` | Date |
| Contact | `contact:hs_email_last_reply_date` | Date |
| Contact | `contact:hs_email_last_send_date` | Date |
| Contact | `contact:hs_email_open` | Number |
| Contact | `contact:hs_email_optout` | Boolean |
| Contact | `contact:hs_email_quarantined` | Boolean |
| Contact | `contact:hs_email_replied` | Number |
| Contact | `contact:hs_email_sends_since_last_engagement` | Number |
| Contact | `contact:hs_first_closed_order_id` | Number |
| Contact | `contact:hs_first_engagement_object_id` | Number |
| Contact | `contact:hs_first_order_closed_date` | Date |
| Contact | `contact:hs_is_enriched` | Boolean |
| Contact | `contact:hs_is_unworked` | Boolean |
| Contact | `contact:hs_last_sales_activity_timestamp` | Date |
| Contact | `contact:hs_latest_disqualified_lead_date` | Date |
| Contact | `contact:hs_latest_open_lead_date` | Date |
| Contact | `contact:hs_latest_qualified_lead_date` | Date |
| Contact | `contact:hs_latest_sequence_ended_date` | Date |
| Contact | `contact:hs_latest_sequence_enrolled` | Number |
| Contact | `contact:hs_latest_sequence_enrolled_date` | Date |
| Contact | `contact:hs_latest_source_timestamp` | Date |
| Contact | `contact:hs_lifecyclestage_customer_date` | Date |
| Contact | `contact:hs_lifecyclestage_evangelist_date` | Date |
| Contact | `contact:hs_lifecyclestage_lead_date` | Date |
| Contact | `contact:hs_lifecyclestage_marketingqualifiedlead_date` | Date |
| Contact | `contact:hs_lifecyclestage_opportunity_date` | Date |
| Contact | `contact:hs_lifecyclestage_other_date` | Date |
| Contact | `contact:hs_lifecyclestage_salesqualifiedlead_date` | Date |
| Contact | `contact:hs_lifecyclestage_subscriber_date` | Date |
| Contact | `contact:hs_membership_has_accessed_private_content` | Number |
| Contact | `contact:hs_membership_last_private_content_access_date` | Date |
| Contact | `contact:hs_object_id` | Number |
| Contact | `contact:hs_recent_closed_order_date` | Date |
| Contact | `contact:hs_registered_member` | Number |
| Contact | `contact:hs_sa_first_engagement_date` | Date |
| Contact | `contact:hs_sales_email_last_clicked` | Date |
| Contact | `contact:hs_sales_email_last_opened` | Date |
| Contact | `contact:hs_sales_email_last_replied` | Date |
| Contact | `contact:hs_sequences_enrolled_count` | Number |
| Contact | `contact:hs_sequences_is_enrolled` | Boolean |
| Contact | `contact:hs_time_to_first_engagement` | Number |
| Contact | `contact:hs_updated_by_user_id` | Number |
| Contact | `contact:hs_v2_date_entered_customer` | Date |
| Contact | `contact:hs_v2_date_entered_evangelist` | Date |
| Contact | `contact:hs_v2_date_entered_lead` | Date |
| Contact | `contact:hs_v2_date_entered_marketingqualifiedlead` | Date |
| Contact | `contact:hs_v2_date_entered_opportunity` | Date |
| Contact | `contact:hs_v2_date_entered_other` | Date |
| Contact | `contact:hs_v2_date_entered_salesqualifiedlead` | Date |
| Contact | `contact:hs_v2_date_entered_subscriber` | Date |
| Contact | `contact:hs_v2_date_exited_customer` | Date |
| Contact | `contact:hs_v2_date_exited_evangelist` | Date |
| Contact | `contact:hs_v2_date_exited_lead` | Date |
| Contact | `contact:hs_v2_date_exited_marketingqualifiedlead` | Date |
| Contact | `contact:hs_v2_date_exited_opportunity` | Date |
| Contact | `contact:hs_v2_date_exited_other` | Date |
| Contact | `contact:hs_v2_date_exited_salesqualifiedlead` | Date |
| Contact | `contact:hs_v2_date_exited_subscriber` | Date |
| Contact | `contact:hubspot_owner_assigneddate` | Date |
| Contact | `contact:hubspotscore` | Number |
| Contact | `contact:lastmodifieddate` | Date |
| Contact | `contact:notes_last_contacted` | Date |
| Contact | `contact:notes_last_updated` | Date |
| Contact | `contact:notes_next_activity_date` | Date |
| Contact | `contact:num_associated_deals` | Number |
| Contact | `contact:num_contacted_notes` | Number |
| Contact | `contact:num_conversion_events` | Number |
| Contact | `contact:num_notes` | Number |
| Contact | `contact:num_unique_conversion_events` | Number |
| Contact | `contact:recent_conversion_date` | Date |
| Contact | `contact:recent_deal_amount` | Number |
| Contact | `contact:recent_deal_close_date` | Date |
| Contact | `contact:total_revenue` | Number |
| Opportunity (Deal) | `opportunity:amount` | Number |
| Opportunity (Deal) | `opportunity:amount_in_home_currency` | Number |
| Opportunity (Deal) | `opportunity:closedate` | Date |
| Opportunity (Deal) | `opportunity:createdate` | Date |
| Opportunity (Deal) | `opportunity:days_to_close` | Number |
| Opportunity (Deal) | `opportunity:engagements_last_meeting_booked` | Date |
| Opportunity (Deal) | `opportunity:hs_acv` | Number |
| Opportunity (Deal) | `opportunity:hs_analytics_latest_source_timestamp` | Date |
| Opportunity (Deal) | `opportunity:hs_arr` | Number |
| Opportunity (Deal) | `opportunity:hs_closed_won_count` | Number |
| Opportunity (Deal) | `opportunity:hs_created_by_user_id` | Number |
| Opportunity (Deal) | `opportunity:hs_deal_stage_probability` | Number |
| Opportunity (Deal) | `opportunity:hs_exchange_rate` | Number |
| Opportunity (Deal) | `opportunity:hs_forecast_amount` | Number |
| Opportunity (Deal) | `opportunity:hs_forecast_probability` | Number |
| Opportunity (Deal) | `opportunity:hs_is_closed` | Boolean |
| Opportunity (Deal) | `opportunity:hs_is_closed_count` | Number |
| Opportunity (Deal) | `opportunity:hs_is_closed_lost` | Boolean |
| Opportunity (Deal) | `opportunity:hs_is_closed_won` | Boolean |
| Opportunity (Deal) | `opportunity:hs_is_open_count` | Number |
| Opportunity (Deal) | `opportunity:hs_lastmodifieddate` | Date |
| Opportunity (Deal) | `opportunity:hs_mrr` | Number |
| Opportunity (Deal) | `opportunity:hs_num_of_associated_line_items` | Number |
| Opportunity (Deal) | `opportunity:hs_object_id` | Number |
| Opportunity (Deal) | `opportunity:hs_projected_amount` | Number |
| Opportunity (Deal) | `opportunity:hs_projected_amount_in_home_currency` | Number |
| Opportunity (Deal) | `opportunity:hs_tcv` | Number |
| Opportunity (Deal) | `opportunity:hs_updated_by_user_id` | Number |
| Opportunity (Deal) | `opportunity:hubspot_owner_assigneddate` | Date |
| Opportunity (Deal) | `opportunity:notes_last_contacted` | Date |
| Opportunity (Deal) | `opportunity:notes_last_updated` | Date |
| Opportunity (Deal) | `opportunity:notes_next_activity_date` | Date |
| Opportunity (Deal) | `opportunity:num_associated_contacts` | Number |
| Opportunity (Deal) | `opportunity:num_contacted_notes` | Number |
| Opportunity (Deal) | `opportunity:num_notes` | Number |
#### Standard Field Mapping
Hatch standard fields are mapped from HubSpot detail fields as detailed below.
**Contact Opportunity**
The base object of this opportunity model is the HubSpot **Contact**. Therefore, (as an example) the **External ID**
field would indicate the ID of the HubSpot **Contact** record.
| Hatch Standard Field | HubSpot Detail Field |
| -------------------------------------------------------------- | ------------------------------------------------------------------ |
| **External ID** | `contact:id` |
| **External Contact ID** | `contact:id` |
| **External Created At** | `contact:createdate` |
| **External Updated At** *(used for Hatch opportunity sorting)* | `contact:lastmodifieddate` |
| **First Name** | `contact:firstname` |
| **Last Name** | `contact:lastname` |
| **Phone** | `contact:phone` |
| **Email** | `contact:email` |
| **Status** | the contact property you mapped to **Contact status** during setup |
**Account Opportunity**
The base object of this opportunity model is the HubSpot **Company**. Therefore, (as an example) the **External ID**
field would indicate the ID of the HubSpot **Company** record.
| Hatch Standard Field | HubSpot Detail Field |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **External ID** | `account:id` |
| **External Contact ID** | the associated contact's `contact:id`, or `account:id` when the company has no contacts |
| **External Created At** | `account:createdate` |
| **External Updated At** *(used for Hatch opportunity sorting)* | `account:hs_lastmodifieddate` |
| **First Name** | the company property mapped to **Company first name**, otherwise the associated contact's `contact:firstname` |
| **Last Name** | the company property mapped to **Company last name**, otherwise the associated contact's `contact:lastname` |
| **Phone** | `account:phone`, falling back to the associated contact's `contact:phone` |
| **Email** | the company property mapped to **Company email**, falling back to the associated contact's `contact:email` |
| **Status** | the company property you mapped to **Company status** during setup |
**Opportunity**
The base object of this opportunity model is the HubSpot **Deal**. Therefore, (as an example) the **External ID**
field would indicate the ID of the HubSpot **Deal** record.
| Hatch Standard Field | HubSpot Detail Field |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **External ID** | `opportunity:id` |
| **External Contact ID** | the associated contact's `contact:id`, or the associated company's `account:id` |
| **External Created At** | `opportunity:createdate` |
| **External Updated At** *(used for Hatch opportunity sorting)* | `opportunity:hs_lastmodifieddate` |
| **First Name** | the associated contact's `contact:firstname`, or the company's mapped first name |
| **Last Name** | the associated contact's `contact:lastname`, or the company's mapped last name |
| **Phone** | the associated contact's `contact:phone`, or the associated company's phone |
| **Email** | the associated contact's `contact:email`, or the associated company's mapped email |
| **Status** | the deal property you mapped to **Deal status**, falling back to the associated record's status |
### FAQ
The HubSpot v2 integration syncs data every 5 minutes.
For each object, you must select "Install" (or "Save") in the top right corner of the integration configuration, in order to sync data for that object.
Yes. Hatch captures every property HubSpot returns for contacts, companies, and deals, including custom
properties.
We will be offering migrations to HubSpot v2 at a later date. Once available, we will provide more information!