node-hubspot
Javascript / node.js wrapper for the HubSpot API
Installing
npm install hubspot
Instantiate client
const Hubspot = const hubspot = apiKey: 'abc' checkLimit: false // (Optional) Specify whether or not to check the API limit on each call. Default: true
You can also authenticate via token:
const hubspot = accessToken: YOUR_ACCESS_TOKEN
To change the base url:
const hubspot = accessToken: YOUR_ACCESS_TOKEN baseUrl: 'https://some-url'
If you're an app developer, you can also instantiate a client with your app details and a refresh_token and obtain a new accessToken:
const hubspot = clientId: ... clientSecret: ... redirectUri: ... refreshToken: ...return hubspot
Changing rate limiter options
Bottleneck is used for rate limiting. To override the default settings, pass a limiter
object when instantiating the client. Bottleneck options can be found here.
const hubspot = apiKey: YOUR_API_KEY limiter: maxConcurrent: 2 minTime: 1000 / 9
Usage
All methods return a promise. The success case includes the returned object from the response. Use the API method via:
hubspotcontacts
{EXAMPLE} Create Contact
const contactObj = "properties": "property": "firstname""value": yourvalue "property": "lastname" "value": yourvalue ; const hubspot = apiKey: YOUR_API_KEY ;const hubspotContact = await hubspotcontacts;
{EXAMPLE} If you need to insert multiple values
Each value must have a semi colon after each value
API limits
HubSpot has relatively stringent API limits (40,000 per day by default). To prevent from consuming it all-at-once, this library checks API quotas regularly and will fail requests if the total is too close to the max. By default
Available Methods
Companies
hubspotcompanieshubspotcompanieshubspotcompanieshubspotcompanieshubspotcompanieshubspotcompanieshubspotcompanies// data = { companyId: 123, contactVid: 123 }hubspotcompanieshubspotcompanieshubspotcompanieshubspotcompanies// data = [{ objectId: 123, properties: [] }]hubspotcompanies
Company properties
hubspotcompaniesproperties // query is optionalhubspotcompaniespropertieshubspotcompaniespropertieshubspotcompaniespropertieshubspotcompaniesproperties// not an official API, wrapper doing two API calls. Callbacks not supported// at this time.
Company properties groups
hubspotcompaniespropertiesgroups // query is optionalhubspotcompaniespropertiesgroupshubspotcompaniespropertiesgroupshubspotcompaniespropertiesgroups// not an official API, wrapper doing two API calls. Callbacks not supported at// this time
Contacts
hubspotcontactshubspotcontactshubspotcontactshubspotcontactshubspotcontactshubspotcontactshubspotcontactshubspotcontactshubspotcontacts// data = [{ vid/email: '', properties: [] }]hubspotcontactshubspotcontactshubspotcontactshubspotcontactshubspotcontacts
Contact properties
hubspotcontactspropertieshubspotcontactspropertieshubspotcontactspropertieshubspotcontactspropertieshubspotcontactsproperties// not an official API, wrapper doing two API calls.// Callbacks not supported at this timehubspotcontactsproperties// => [ {name: '...', displayName: '...'}, ...]hubspotcontactspropertieshubspotcontactspropertieshubspotcontactspropertieshubspotcontactsproperties
CRM associations
hubspotcrmassociationshubspotcrmassociationshubspotcrmassociationshubspotcrmassociations// not an official API, wrapper doing two API calls. Callbacks not supported at// this time
Pages
// more opts can be found at https://developers.hubspot.com/docs/methods/pages/get_pageshubspotpages // eg: opts = {is_draft: false}
Deals
hubspotdealshubspotdealshubspotdealshubspotdealshubspotdealshubspotdealshubspotdealshubspotdealshubspotdealshubspotdealshubspotdeals
Deals properties
hubspotdealsproperties // query is optionalhubspotdealspropertieshubspotdealspropertieshubspotdealspropertieshubspotdealsproperties// not an official API, wrapper doing two API calls. Callbacks not supported at// this time
Deals properties groups
hubspotdealspropertiesgroups // query is optionalhubspotdealspropertiesgroupshubspotdealspropertiesgroupshubspotdealspropertiesgroups// not an official API, wrapper doing two API calls. Callbacks not supported at// this time
Engagements
hubspotengagementshubspotengagementshubspotengagementshubspotengagementshubspotengagements
Owners
hubspotowners
Pipelines
hubspotpipelines
Lists
hubspotlistshubspotlistshubspotlistshubspotlistshubspotlistshubspotlistshubspotlists
Files
hubspotfileshubspotfiles
hubspotsubscriptions
Email Events
hubspotcampaignshubspotcampaignshubspotcampaignshubspotcampaigns
Social Media
hubspotbroadcasts
Timeline
// setup for timeline eventshubspottimelineshubspottimelineshubspottimelineshubspottimelines// creating timeline eventshubspottimelines
NOTE: From the documentation for createTimelineEvent:
Returns a 204 response on success. Otherwise, you'll receive a 4xx error, with more details about the specific error in the body of the response.
So on success the body is empty or undefined
and you will not get a result
from the resolved promise.
Transactional Emails
hubspotemails
OAuth
Obtain your authorization url
const params = client_id: 'your_client_id' scopes: 'some scopes' redirect_uri: 'take_me_to_the_ballpark'const uri = hubspotoauth
Obtain an access token from an authorization_code
const hubspot = clientId: '' clientSecret: '' redirectUri: ''return hubspotoauth
You can also pass the constructor directly as parameters (although with a slightly awkward case change)
const params = code: 'abc' // the code you received from the oauth flow client_id: '' client_secret: '' redirect_uri: ''const hubspot = paramsreturn hubspotoauth
Typescript
You may use this library in your Typescript project via:
;;
License
MIT
Contributing
See our contributing guidelines
Development Workflow
After cloning this repo, run npm install
to fetch dependencies. Then run the
test suite with npm test
. From master, this should be green. Our tests mock
out requests to HubSpot's api using nock. We then recommend running the test
suite without mocking api requests with NOCK_OFF=true npm run mocha
. This
should fail as you'll need some environment variables for real requests to
pass.
If you haven't already, create a developer account on hubspot. You'll want to
create an app and a test account as well. Then, create a new file, .env
in
the root of the repo. Inside you'll need to add an app id, a HubSpot user id,
and an oauth access token;
NOTE: Your HubSpot user ID; This can be found in the same place as your Developer HAPIkey in your Developer portal.
APPLICATION_ID=111111USER_ID=2222222ACCESS_TOKEN=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_BBB_CCCC_____-D_EEEEEEEEEEEEEEEEEEEEEEE_fffffff-gggggg"
To get an access token, you should follow the instructions here after cloning
the oauth-quickstart-nodejs project. Make sure to modify index.js
to include
all the required scopes as shown in this pull-request.
Once you have a green test suite with mocking turned off (run
NOCK_OFF=true npm run mocha
to confirm) you can write a test for the new
feature or bug fix hitting the live API. Once that test is passing try mocking
out the endpoint using the fakeHubspotApi test helper.
Push to your fork. Write a good commit message. Submit a pull request.
Others will give constructive feedback. This is a time for discussion and improvements, and making the necessary changes will be required before we can merge the contribution.
Thank you to all our contributors.