node-hubspot-api

A wrapper for the HubSpot API based on Node - http://developers.hubspot.com/docs/overview

Installation

npm install node-hubspot-api --save

Tests

npm run test

Get Started

import NodeHubSpotApi from 'node-hubspot-api'
 
const api = new NodeHubSpotApi('your_api_key')

Available Resources

Contacts

- Get all contacts

Return all contacts that have been created. A paginated list of contacts will be returned with a maximum of 100 contacts per page.

Parameter	Description	Required	Default
count	Specify the amount of contacts to return.	No	20
vidOffset	Used to page through the contacts.	No	-
property	By default, only a few standard properties will be included in the response data. Include the 'property' parameter to get the specified property in the response.	No	-
showListMemberships	Indicate whether current list memberships should be fetched for the contact.	No	false

Usage:

api.contacts.getAll({
  count: 20,
  vidOffset: null,
  property: [
    'fistname', 'lastname', 'email',
  ],
  showListMemberships: false,
})
.then(response => console.log(response.data.contacts))
.catch(error => console.error(error))

Reference: http://developers.hubspot.com/docs/methods/contacts/get_contacts

- Get a contact by ID

Returns information about a single contact by its ID. The contact's unique ID is stored in a field called 'vid' which stands for 'visitor ID'.

Parameter	Description	Required	Default
property	By default, you will get all properties that the contact has values for. If you include the "property" parameter, then the returned data will only include the property or properties that you request. You can include this parameter multiple times to specify multiple properties. The lastmodifieddate and associatedcompanyid will always be included, even if not specified. Keep in mind that only properties that have a value will be included in the response, even if specified in the URL.	No	-
propertyMode	One of “value_only” or “value_and_history” to specify if the current value for a property should be fetched, or the value and all the historical values for that property.	No	value_and_history
formSubmissionMode	One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched.	No	all
showListMemberships	Indicate whether current list memberships should be fetched for the contact.	No	false

Usage:

api.contacts.getContactById(123456, {
  property: [
    'firstname', 'lastname', 'email',
  ],
  propertyMode: 'value_and_history',
  formSubmissionMode: 'all',
  showListMemberships: false,
})
.then(response => console.log(response.data))
.catch(error => console.error(error))

Reference: https://developers.hubspot.com/docs/methods/contacts/get_contact

- Get a contact by email address

Returns information about a single contact by its email address.

Usage:

api.contacts.getContactByEmail('[e-mail]', {
  property: [
    'firstname', 'lastname', 'email',
  ],
  propertyMode: 'value_and_history',
  formSubmissionMode: 'all',
  showListMemberships: false,
})
.then(response => console.log(response.data))
.catch(error => console.error(error))

Reference: https://developers.hubspot.com/docs/methods/contacts/get_contact_by_email

- Create a new contact

Create a new contact in HubSpot. Returns a 200 response on success. The response will include the details for the created contact.

If there is an existing contact with the email address included in the request, the response body will include the identityProfile details of the contact, which will include the vid of the existing record.

Usage:

api.contacts.createContact({
  email: '[e-mail]',
  firstname: 'James',
  lastname: 'Bond',
  website: 'http://www.mycompany.com',
  company: 'My Company',
  ...
})
.then(response => console.log(response.data.properties))
.catch(error => console.error(error))

Reference: https://developers.hubspot.com/docs/methods/contacts/create_contact

- Update a contact by ID

Update an existing contact in HubSpot. This method lets you update the properties of a contact in HubSpot. You must pass the Contact's ID that you're updating as second parameter.

If the request succeeds, you'll get an HTTP 204 response, which represents that you have successfully updated the contact in the system. There will be no data in the response body.

Usage:

api.contacts.updateContactById({
  email: '[e-mail]',
  firstname: 'Jon',
  lastname: 'Doe',
  website: 'http://www.my-new-company.com',
  company: 'My Company 2',
  ...
}, 123456)
.then(response => console.log(response.status))
.catch(error => console.error(error))

Reference: https://developers.hubspot.com/docs/methods/contacts/update_contact

- Update a contact by email

Update an existing contact in HubSpot, identified by email. This method lets you update the properties of a contact in HubSpot. You must pass the Contact's email that you're updating as second parameter.

If the request succeeds, you'll get an HTTP 204 response, which represents that you have successfully updated the contact in the system. There will be no data in the response body.

Usage:

api.contacts.updateContactByEmail({
  firstname: 'Jon',
  lastname: 'Doe',
  website: 'http://www.my-new-company.com',
  company: 'My Company 2',
  ...
}, '[e-mail]')
.then(response => console.log(response.status))
.catch(error => console.error(error))

Reference: https://developers.hubspot.com/docs/methods/contacts/update_contact-by-email

- Create or update a contact

Create a contact if it doesn't exist already, or update it with the latest property values if it does.

This returns a 200 response on success. The response will contain a vid of the updated or created record, and an isNew field that indicates if a new record was created. If the field is false, an existing record was updated.

This will return a 409 Conflict error response if you are trying to update the email address of a record, and there is an existing record with the new email address.

Usage:

api.contacts.createOrUpdateContact({
  firstname: 'Jon',
  lastname: 'Doe',
  website: 'http://www.my-new-company.com',
  company: 'My Company 2',
  ...
}, '[e-mail]')
.then(response => console.log(response.status))
.catch(error => console.error(error))

Reference: https://developers.hubspot.com/docs/methods/contacts/create_or_update

Blog

- Get all blogs

List all of the blogs for a portal. Supports paging and filtering.

Parameter	Description	Required	Default
limit	The number of items to return.	No	20
offset	The offset set to start returning rows from.	No	0
created	exact, range, gt, gte, lt, lte - When the post was first created, in milliseconds since the epoch.	No	-
deleted_at	exact, gt, gte - When the post was deleted, in milliseconds since the epoch. Zero if the blog post was never deleted.	No	-
name	exact, in - The internal name of the blog	No	-

Usage:

api.blog.getAllBlogs({
  limit: 20,
  offset: 0,
  created: null,
  deleted_at: null,
  name: null,
})
.then(response => console.log(response.data.objects))
.catch(error => console.error(error))

Reference: http://developers.hubspot.com/docs/methods/blogv2/get_blogs

- List blog posts

Get the posts from your blogs.

Parameter	Description	Required	Default
limit	The number of items to return.	No	20
offset	The offset set to start returning rows from.	No	0
archived	Returns the posts that match the boolean lookup (e.g. archived=false returns all posts currently not archived).	No	false
blog_author_id	Returns the posts that match a particular blog author ID value.	No	-
campaign	Returns the posts that match the campaign guid.	No	-
content_group_id	Returns the posts that match the blog guid. The blog guid can be found in the blog dashboard URL (e.g. https://app.hubspot.com/blog/:portal_id/dashboard/:blog_guid).	No	-
created	Returns the posts that match a particular created time value. Supports exact, range, gt, gte, lt, lte lookups.	No	-
deleted_at	Returns the posts that match a particular deleted time value. Supports exact, gt, gte, lt, lte lookups.	No	-
name	Returns the posts that match the name value. Supports exact, contains, icontains, ne lookups.	No	-
slug	Returns the posts that match a particular slug value.	No	-
updated	Returns the posts that match a particular updated time. Supports exact, range, gt, gte, lt, lte lookups.	No	-
state	DRAFT, PUBLISHED, or SCHEDULED.	No	PUBLISHED
order_by	Return the posts ordered by a particular field value. Blog posts can currently only be sorted by publish_date. Use a negative value to sort in descending order (e.g. order_by=-publish_date).	No	publish_date

Usage:

api.blog.getPosts({
  limit: 20,
  offset: 0,
  archived: false,
  blog_author_id: null,
  campaign: null,
  content_group_id: null,
  created: null,
  deleted_at: null,
  name: null,
  updated: null,
  state: 'PUBLISHED',
  order_by: 'publish_date',
})
.then(response => console.log(response.data.objects))
.catch(error => console.error(error))

Reference: http://developers.hubspot.com/docs/methods/blogv2/get_blog_posts

- Get the blog post by ID

Get a specific blog post by ID.

Usage:

api.blog.getPostById(3198892953)
.then(response => console.log(response.data))
.catch(error => console.error(error))

Reference: http://developers.hubspot.com/docs/methods/blogv2/get_blog_posts_blog_post_id

Deals

- Get all deals

Get all of the deals in a portal. Returns a paginated set of deals.

In addition to the list of deals, each request will also return two values, offset and hasMore. If hasMore is true, you'll need to make another request, using the offset to get the next page of deal records.

Parameter	Description
limit	The number of records to return. Defaults to 100, has a maximum value of 250.
offset	Used to page through the results. If there are more records in your portal than the limit= parameter, you will need to use the offset returned in the first request to get the next set of results.
properties	Used to include specific deal properties in the results. By default, the results will only include Deal ID and will not include the values for any properties for your Deals. Including this parameter will include the data for the specified property in the results. You can include this parameter multiple times to request multiple properties. Note: Deals that do not have a value set for a property will not include that property, even when you specify the property. A deal without a value for the dealname property would not show the dealname property in the results, even with &properties=dealname in the URL.
propertiesWithHistory	Works similarly to properties=, but this parameter will include the history for the specified property, instead of just including the current value. Use this parameter when you need the full history of changes to a property's value.
includeAssociations	If it's set to true, it will include the IDs of the associated contacts and companies in the results. This will also automatically include the num_associated_contacts property.

Usage:

api.deals.getAllDeals({
 limit: 100,
 offset: null,
 properties: [
   'hubspot_owner_id',
 ],
 propertiesWithHistory: 'dealname',
 includeAssociations: false,
})
.then(response => console.log(response.data.deals))
.catch(error => console.error(error))

Reference: https://developers.hubspot.com/docs/methods/deals/get-all-deals

- Create a deal

This methods creates a deal on HubSpot. You can create associations between Deals and Contacts and Companies but it's not required.

The dealstage property is required when creating a deal. If the pipeline property is not specified, the default pipeline is assumed. However, it is recommended to always specify the pipeline, especially on portals with multiple pipelines.

Returns a 200 on success with the data for the newly created deal in the response.

You must pass an object to the method with these parameters:

Parameter	Description
Associated records	"associations": {} - A set of IDs for records that the new deal should be associated with. Deals can be associated with a single company (associatedCompanyIds) and any number of contacts (associatedVids).
Deal properties	"properties": [] - A list of property names, and the value you want to set for the property.

Usage:

api.deals.createDeal({
  associations: {
    associatedCompanyIds: [
      123456
    ],
    associatedVids: [
      1234, 12345, 123456, ...
    ],
  },
  properties: {
    dealname: 'This is a brand new deal. Awesome!',
    hubspot_owner_id: 123456,
    amount: '50000',
    dealtype: 'newbusiness',
    dealstage: 'appointmentscheduled',
  },
})
.then(response => console.log(response.data))
.catch(error => console.error(error))

Reference: https://developers.hubspot.com/docs/methods/deals/create_deal

Disclaimer

This tool is under development and don't have all HubSpot API endpoints implemented yet.