> For the complete documentation index, see [llms.txt](https://docs.greytrix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.greytrix.com/pre-requisites-for-integrations/hubspot.md).

# Hubspot

The prerequisites for integrating with **HubSpot** depend on the application you're connecting (e.g., Sage ERP, Magento, a custom app, or GUMU Copilot). In general, the following prerequisites are required.

### 1. HubSpot Account

* An active **HubSpot account**.
* The appropriate subscription plan based on the objects and APIs you intend to use:
  * Free – Basic contacts, companies, deals.
  * Starter/Professional/Enterprise – Custom objects, workflows, advanced automation, and additional API limits.

### 2. HubSpot App Authentication

You need authentication credentials for API access.

#### For Private App Authentication (Recommended)

* Create a **Private App** in HubSpot.
* Generate an **Access Token**.
* Grant the required scopes.

Common scopes include:

* `crm.objects.contacts.read`
* `crm.objects.contacts.write`
* `crm.objects.companies.read`
* `crm.objects.companies.write`
* `crm.objects.deals.read`
* `crm.objects.deals.write`
* `crm.schemas.contacts.read`
* `crm.schemas.companies.read`

### 3. Object Mapping

Identify which HubSpot objects will be synchronized.

Examples:

| External System | HubSpot Object                |
| --------------- | ----------------------------- |
| Customer        | Contact                       |
| Account         | Company                       |
| Sales Order     | Deal                          |
| Product         | Product                       |
| Invoice         | Custom Object (if applicable) |

### 4. Field Mapping Document

Prepare a mapping document containing:

* Source field name
* Destination field name
* Data type
* Mandatory/optional indicator
* Default values
* Transformation rules

Example:

| Source Field | HubSpot Field          |
| ------------ | ---------------------- |
| CustomerID   | external\_customer\_id |
| Name         | firstname / lastname   |
| Email        | email                  |
| Phone        | phone                  |

### 5. Custom Properties

If HubSpot does not already contain the required fields:

* Create custom properties.
* Configure picklists/enumerations if needed.

Examples:

* ERP Customer Number
* Territory
* Credit Limit
* Tax ID

### 6. API Limits Consideration

HubSpot enforces API rate limits.

Examples:

* Private Apps generally allow **100 requests every 10 seconds**.
* Daily limits depend on the subscription plan.

Integrations should implement:

* Retry mechanisms
* Error handling
* Batch processing

### 7. Webhooks (Optional)

If near real-time synchronization is required:

* Enable webhooks.
* Subscribe to events such as:
  * Contact created
  * Contact updated
  * Deal updated

### 8. Integration Server Requirements

The middleware or connector should have:

* Internet access to HubSpot APIs
* HTTPS support
* Ability to store access tokens securely
* Logging and monitoring capabilities

### 9. Testing Data

Prepare sample records for:

* Contacts
* Companies
* Deals
* Products

### 10. Information Typically Requested from the Client

* HubSpot Portal ID
* HubSpot subscription type
* Private App Access Token
* Required scopes
* List of objects to synchronize
* Field mapping sheet
* Synchronization frequency (real-time, scheduled, manual)
* Expected data volume

These prerequisites are generally sufficient for integrations involving **HubSpot and Sage 100, Sage 300, Sage Intacct, Magento, or GUMU Copilot**.