SyncWith

Login

HubSpot CRM API

Sync HubSpot CRM Data with no Code

If you don’t want to call the API directly and write glue code and just want the data sync’d to your data platform of choice SyncWith does this for 100,000s of users and businesses:
  • HubSpot API to Databases (S3, BigQuery, MySQL, Postgres) - contact support to join our beta

Looking to Call the API Directly?

The hubspot API is not well documented, you can view the official API documents here: https://developers.hubspot.com/docs/api/overview sometimes the legacy docs are more instructive than the newer documentation for the newer endpoints (https://legacydocs.hubspot.com/docs/methods/deals/get-all-deals).

Overview and Introduction

Great, we created this API guide to help you navigate Hubspot’s API and extensive set of endpoints.

HubSpot Follows REST Conventions

HubSpot API uses standard HTTP requests to pull, edit, update and delete data:
  • GET - to pull existing records
  • POST - to create new records
  • PUT - to edit existing records
  • DELETE - to delete records

Endpoint Conventions

  • HubSpot API use a common endpoint with different paths
  • The root endpoint is api.hubapi.com
  • Different endpoints ad paths to this for example
    • Deals uses the path /crm/v3/objects/deals
    • Contacts uses the path /crm/v3/objects/contacts

Query vs Path Parameters

Hupspot uses both query and path parameters, typically path parameters are used to retrieve a specific object and query parameters are used to provide filter, sort, pagination and other parameters to the request.
For example when requesting a specific contact you would use/crm/v3/objects/contacts/{contactId} where {contactId} needs to be replaced with the contact id you wish to retrieve.

Pagination

Most of the Hubspot endpoints have limits of 250 records per request and a default of 100 records (the new and legacy endpoints differ) returned when the limit query parameter is not specified. You can use the offset (legacy api) or after query parameter to enumerate through the records using multiple requests. The last record in the current request can be found in the paging.next.after JSON object.
For example:
"paging": {
    "next": {
      "after": "NTI1Cg%3D%3D",
      "link": "?after=NTI1Cg%3D%3D"
    }
  }

Authentication

Authentication is typically handled via OAuth 2.0 using an authorization header alternatively you can use the query parameter hapikey to pass along your API key. For commercial use HubSpot strongly recommends using OAuth

API Limits

HubSpot has different API limits for OAuth, API Keys and HubSpot Apps

OAuth

  • 100 requests every 10 seconds

Apps

Depends on the tier of HubSpot you’re paying for, limits are per app
  • Free / Starter - 100 per 10 seconds, 250k daily limit
  • Pro / Enterprice - 150 per 10 seconds, 500k daily limit
  • Apps with API Add-on - 200 per 10 seconds, 1M daily limit

API Key

  • Free / Starter - 100 per 10 seconds, 250k daily limit
  • Pro / Enterprice - 150 per 10 seconds, 500k daily limit
  • API Add-on - 200 per 10 seconds, 1M daily limit
If you exceed your rate limit you’ll get a 429 error response from the endpoint
eg
{
  "status": "error",
  "message": "You have reached your daily limit.",
  "errorType": "RATE_LIMIT",
  "correlationId": "c033cdaa-2c40-4a64-ae48-b4cec88dad24",
  "policyName": "DAILY",
  "requestId": "3d3e35b7-0dae-4b9f-a6e3-9c230cbcf8dd"
}
If you’re using an API key you can check your limit with GET /integrations/v1/limit/daily
and get a JSON response:
{
    "name": "api-calls-daily",
    "usageLimit": 1000000,
    "currentUsage": 31779,
    "collectedAt": 1560189939285,
    "fetchStatus": "SUCCESS",
    "resetsAt": 1560204000000
  }

Quick Example Request

If you want to get a list of deals from the HubSpot CRM you would
  • send a GET request
  • use the url https://api.hubapi.com/crm/v3/objects/deals
  • set the query parameters
    • limit=50
    • properties=dealname,dealstage,pipeline,closedate,amount,dealtype

HubSpot CRM API Endpoints

It’s best to think of the CRM in terms of the objects you want to list, edit, create or delete. The HubSpot api lets you access the following objects:
  • Companies
  • Contacts
  • Deals
  • Feedback Submissions
  • Line items
  • Products
  • Tickets
  • Quotes
  • Custom objects

HubSpot Deals

Deals are similar to opportunities in Salesforce, a deal is pursued and tracked until it is won or lost, this endpoint can be useful to pull deals into a spreadsheet for further analysis or to bulk update deals.
There are multiple endpoints associate with deals

Endpoints

Here are some of the more popular and useful endpoints for the deals api:
  • GET /crm/v3/objects/deals
    • Returns a list of deals
    • Default limit of 10 if not specified
    • Query Params
      • properties - list of comma separated parameters to report on
      • preopertiesWithHistory - list of comma separated properties which will return the historic values for the properties specified
      • archived - boolean to determine if you want archived records or not (false or true as values)
  • GET /crm/v3/objects/deals/{dealId}
    • Similar to above except {dealId} must be replaced with the deal you’re looking for
    • Returns a single deal based on ID
  • POST /crm/v3/objects/deals
    • Lets you create a deal
    • Takes a JSON blog in the body to specify the properties of the new deal
Example Body JSON might look like:
{
  "properties": {
    "amount": "10000.00",
    "closedate": "2021-12-01,
    "dealname": "My big sale",
    "dealstage": "proposalSubmitted",
    "hubspot_owner_id": "123456",
    "pipeline": "northAmerica"
  }
}

HubSpot Contacts

If you want to get the lead and person data stored in contacts into another system, into a spreadsheets for bulk editing, to upload emails for CRM retargeting or other use cases the contacts api where to start.
There are multiple endpoints associate with contacts.

Endpoints

Here are some of the more popular and useful endpoints for the deals api:
  • GET /crm/v3/objects/contacts
    • Returns a list of contacts
    • Default limit of 10 if not specified
    • Query Params
      • properties - list of comma separated parameters to report on
      • preopertiesWithHistory - list of comma separated properties which will return the historic values for the properties specified
      • archived - boolean to determine if you want archived records or not (false or true as values)
      • associations - comma separated list of object types to retrieve associated IDs for - eg get me all the associate deals
  • GET /crm/v3/objects/deals/{contactId}
    • Similar to above except {contactId} must be replaced with the deal you’re looking for
    • Returns a single contact based on ID
  • POST /crm/v3/objects/contacts
    • Lets you create a contact
    • Takes a JSON blog in the body to specify the properties of the new deal
Example Body JSON might look like:
{
  "properties": {
    "company": "Acme",
    "email": "bigboss@acme.org",
    "firstname": "Big",
    "lastname": "Boss",
    "phone": "(909) 123-4597",
    "website": "acme.org"
  }
}

Other Popular HubSpot Object Endpoints to Pursue

  • Companies - https://developers.hubspot.com/docs/api/crm/companies
  • Line Items - https://developers.hubspot.com/docs/api/crm/line-items
  • Products - https://developers.hubspot.com/docs/api/crm/products
  • Tickets - https://developers.hubspot.com/docs/api/crm/tickets