Nitrate Processed Mincemeat

    hubspot
    TypeScript icon, indicating that this package has built-in type declarations

    2.3.14 • Public • Published

    node-hubspot

    Build Status Code Climate Test Coverage Issue Count Dependencies

    Javascript / node.js wrapper for the HubSpot API

    Installing

    npm install hubspot

    Instantiate client

    const Hubspot = require('hubspot')
    const hubspot = new Hubspot({
      apiKey: 'abc',
      checkLimit: false // (Optional) Specify whether to check the API limit on each call. Default: true
    })

    You can also authenticate via token:

    const hubspot = new Hubspot({ accessToken: YOUR_ACCESS_TOKEN })

    To change the base url:

    const hubspot = new 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 = new Hubspot({
      clientId: ...,
      clientSecret: ...,
      redirectUri: ...,
      refreshToken: ...
    })
    return hubspot.refreshAccessToken()
      .then(results => {
        console.log(results.access_token)
     
        // this assigns the new accessToken to the client, so your client is ready
        // to use
        console.log(hubspot.accessToken)
        return hubspot.contacts.get()
      })

    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 = new 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:

    hubspot.contacts
      .get(options)
      .then(results => {
        console.log(results)
      })
      .catch(err => {
        console.error(err)
      })

    Samples

    Please see repository with samples applications with common cases.

    {EXAMPLE} Create Contact

    const contactObj = {
      "properties": [
        { "property": "firstname","value": yourvalue },
        { "property": "lastname", "value": yourvalue }
      ]
    };
     
    const hubspot = new Hubspot({ apiKey: YOUR_API_KEY });
    const hubspotContact = await hubspot.contacts.create(contactObj);

    {EXAMPLE} If you need to insert multiple values

    Each value must have a semi colon after each value

    { "property": "foo", "value": "value1;value2;value3;value4" }

    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

    hubspot.companies.get(opts)
    hubspot.companies.getById(id)
    hubspot.companies.getRecentlyCreated(opts)
    hubspot.companies.getRecentlyModified(opts)
    hubspot.companies.getByDomain(domain)
    hubspot.companies.create(data)
    hubspot.companies.addContactToCompany(data)
    // data = { companyId: 123, contactVid: 123 }
    hubspot.companies.getContactIds(id, options)
    hubspot.companies.getContacts(id, options)
    hubspot.companies.update(id, data)
    hubspot.companies.updateBatch(data)
    // data = [{ objectId: 123, properties: [] }]
    hubspot.companies.delete(id)

    Company properties

    hubspot.companies.properties.get(query) // query is optional
    hubspot.companies.properties.getByName(name)
    hubspot.companies.properties.create(data)
    hubspot.companies.properties.update(name, data)
    hubspot.companies.properties.upsert(data)
    // not an official API, wrapper doing two API calls. Callbacks not supported
    // at this time.

    Company properties groups

    hubspot.companies.properties.groups.get(query) // query is optional
    hubspot.companies.properties.groups.create(data)
    hubspot.companies.properties.groups.update(name, data)
    hubspot.companies.properties.groups.upsert(data)
    // not an official API, wrapper doing two API calls. Callbacks not supported at
    // this time

    Contacts

    hubspot.contacts.get(opts)
    hubspot.contacts.getAll(opts)
    hubspot.contacts.getByEmail(email)
    hubspot.contacts.getByEmailBatch(emails)
    hubspot.contacts.getById(id)
    hubspot.contacts.getByIdBatch(ids)
    hubspot.contacts.getByToken(utk)
    hubspot.contacts.update(id, data)
    hubspot.contacts.create(data)
    hubspot.contacts.createOrUpdateBatch(data)
    // data = [{ vid/email: '', properties: [] }]
    hubspot.contacts.search(query)
    hubspot.contacts.getRecentlyCreated()
    hubspot.contacts.getRecentlyModified()
    hubspot.contacts.createOrUpdate(email, data)
    hubspot.contacts.updateByEmail(email, data)
    hubspot.contacts.delete(id)
    hubspot.contacts.merge(primaryId, secondaryId)
     
    // Add a secondary email address to a contact
    hubspot.contacts.addSecondaryEmail(vid, secondaryEmail)

    Contact properties

    hubspot.contacts.properties.get()
    hubspot.contacts.properties.getByName(name)
    hubspot.contacts.properties.create(data)
    hubspot.contacts.properties.update(name, data)
    hubspot.contacts.properties.upsert(data)
    // not an official API, wrapper doing two API calls.
    // Callbacks not supported at this time
    hubspot.contacts.properties.getGroups()
    // => [ {name: '...', displayName: '...'}, ...]
    hubspot.contacts.properties.createGroup({ name, displayName })
    hubspot.contacts.properties.updateGroup(name, { displayName })
    hubspot.contacts.properties.deleteGroup(name)
    hubspot.contacts.properties.delete(name)

    CRM associations

    hubspot.crm.associations.create(data)
    hubspot.crm.associations.createBatch(data)
    hubspot.crm.associations.delete(data)
    hubspot.crm.associations.deleteBatch(data)
    // 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_pages
    hubspot.pages.get(opts) // eg: opts = {is_draft: false}

    Deals

    hubspot.deals.get(opts)
    hubspot.deals.getRecentlyModified(opts)
    hubspot.deals.getRecentlyCreated(opts)
    hubspot.deals.getById(id)
    hubspot.deals.getAssociated(objectType, objectId, opts)
    hubspot.deals.deleteById(id)
    hubspot.deals.updateById(id, data)
    hubspot.deals.updateBatch(data)
    hubspot.deals.create(data)
    hubspot.deals.associate(id, objectType, associatedObjectId)
    hubspot.deals.removeAssociation(id, objectType, associatedObjectId)

    Deals properties

    hubspot.deals.properties.get(query) // query is optional
    hubspot.deals.properties.getByName(name)
    hubspot.deals.properties.create(data)
    hubspot.deals.properties.update(name, data)
    hubspot.deals.properties.upsert(data)
    // not an official API, wrapper doing two API calls. Callbacks not supported at
    // this time

    Deals properties groups

    hubspot.deals.properties.groups.get(query) // query is optional
    hubspot.deals.properties.groups.create(data)
    hubspot.deals.properties.groups.update(name, data)
    hubspot.deals.properties.groups.upsert(data)
    hubspot.deals.properties.groups.delete(name)
    // not an official API, wrapper doing two API calls. Callbacks not supported at
    // this time

    Engagements

    hubspot.engagements.create(data)
    hubspot.engagements.get(opts)
    hubspot.engagements.update(engagementId, data)
    hubspot.engagements.getRecentlyModified(opts)
    hubspot.engagements.getAssociated(objectType, objectId, opts)
    hubspot.engagements.getCallDispositions()

    Owners

    hubspot.owners.get(opts)

    Pipelines

    hubspot.pipelines.get(opts)

    Lists

    hubspot.lists.get(opts)
    hubspot.lists.getOne(id)
    hubspot.lists.getByIdBatch(ids)
    hubspot.lists.create(data)
    hubspot.lists.delete(id)
    hubspot.lists.getContacts(id, opts)
    hubspot.lists.getRecentContacts(id, opts)
    hubspot.lists.getRecentUpdates(opts)
    hubspot.lists.addContacts(id, contactBody)
    hubspot.lists.removeContacts(id, contactBody)

    Files

    hubspot.files.get()
    hubspot.files.getOne(id)
    hubspot.files.upload(fileDetails, overwrite, hidden)
    hubspot.files.uploadByUrl(fileDetails, overwrite, hidden)

    Forms

    hubspot.forms.get(opts)
    hubspot.forms.getById(id)
    hubspot.forms.getSingleField(guid, fieldname)
    hubspot.forms.getSubmissions(guid, opts)
    hubspot.forms.create(data)
    hubspot.forms.update(id, data)
    hubspot.forms.delete(id)
     
    hubspot.forms.submit(portalId, formId, data)
     
    hubspot.forms.getUploadedFileByUrl(url)

    Email

    hubspot.subscriptions.get(opts)
    hubspot.subscriptions.subscribeToAll(email)
    hubspot.subscriptions.unsubscribe(email)

    Email Events

    hubspot.campaigns.getById()
    hubspot.campaigns.get(opts)
    hubspot.campaigns.getOne(id)
    hubspot.campaigns.events(opts)

    Marketing Email

    hubspot.marketingEmail.get(opts)
    hubspot.marketingEmail.getById(id)
    hubspot.marketingEmail.create(data)
    hubspot.marketingEmail.update(id, data)
    hubspot.marketingEmail.clone(id, data)
    hubspot.marketingEmail.delete(id)
    hubspot.marketingEmail.versions(id)
    hubspot.marketingEmail.restore(id)
    hubspot.marketingEmail.hasBufferedChanges(id)
    hubspot.marketingEmail.statistics(opts)
    hubspot.marketingEmail.statisticsById(id)

    Social Media

    hubspot.broadcasts.get(opts)

    Timelines

    // setup for timeline events
    hubspot.timelines.createEventType(applicationId, userId, data)
    hubspot.timelines.updateEventType(applicationId, eventTypeId, data)
    hubspot.timelines.createEventTypeProperty(
      applicationId,
      eventTypeId,
      userId,
      data,
    )
    hubspot.timelines.updateEventTypeProperty(
      applicationId,
      eventTypeId,
      propertyId,
      data,
    )
    // creating timeline events
    hubspot.timelines.createTimelineEvent(applicationId, eventTypeId, data)

    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

    hubspot.emails.sendTransactionalEmail(data)

    Workflows

    hubspot.workflows.getAll()
    hubspot.workflows.get(workflowId)
    hubspot.workflows.create(data)
    hubspot.workflows.delete(workflowId)
    hubspot.workflows.enroll(workflowId, email)
    hubspot.workflows.unenroll(workflowId, email)
    hubspot.workflows.current(contactId)

    OAuth

    hubspot.oauth.getAuthorizationUrl(opts)
    hubspot.oauth.getAccessToken(data)
    hubspot.oauth.refreshAccessToken()
    hubspot.oauth.getPortalInfo(token)

    Obtain your authorization url

    const params = {
      client_id: 'your_client_id',
      scope: 'some scopes',
      redirect_uri: 'take_me_to_the_ballpark',
    }
    const uri = hubspot.oauth.getAuthorizationUrl(params)

    Obtain an access token from an authorization_code

    const hubspot = new Hubspot({
      clientId: '',
      clientSecret: '',
      redirectUri: ''
    })
    return hubspot.oauth.getAccessToken({
      code: 'abc' // the code you received from the oauth flow
    }).then(...)

    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 = new Hubspot(params)
    return hubspot.oauth.getAccessToken(params).then(...)

    Tickets

    const data = [
      {
        name: 'subject',
        value: 'This is an example ticket'
      },
      {
        name: 'content',
        value: 'Here are the details of the ticket.'
      },
      {
        name: 'hs_pipeline',
        value: '0'
      },
      {
        name: 'hs_pipeline_stage',
        value: '1'
      }
    ];
    const ids = [176606, 177919];
    const properties = ['subject', 'content', 'hs_pipeline'];
    const newDataId = [
        {
          objectId: 176606,
          properties: [
            {
              name: 'subject',
              value: 'SUBJECT 001'
            },
            {
              name: 'content',
              value: 'TICKET 001'
            }
          ]
        },
        {
          objectId: 177919,
          properties: [
            {
              name: 'subject',
              value: 'SUBJECT 002'
            },
            {
              name: 'content',
              value: 'TICKET 002'
            }
          ]
        }
      ];
     
    hubspot.tickets.create(data);
    hubspot.tickets.createBatch(data);
    hubspot.tickets.getAll();
    hubspot.tickets.getAll(properties);
    hubspot.tickets.getById(id);
    hubspot.tickets.getById(id, properties);
    hubspot.tickets.getBatchById(ids);
    hubspot.tickets.getBatchById(ids, properties);
    hubspot.tickets.delete(id);
    hubspot.tickets.deleteBatch(ids);
    hubspot.tickets.update(id, newData);
    hubspot.tickets.updateBatch(newDataId);

    Not wrapped endpoint(s)

    It is possible to access the hubspot request method directly, it could be handy if wrapper doesn't have implementation for some endpoint yet. Using of exposed request method benefits by the bottleneck throttling, auth and request parsing and formatting already in place

    hubspot.apiRequest({
                method: 'PUT',
                path: '/some/api/not/wrapped/yet',
                body: { key: 'value' },
              })

    Also it is possible to overlap hubspot base API URL using overlapUrl parameter

    hubspot.apiRequest({
                method: 'GET',
                overlapUrl: 'https://api.hubspot.com/some/alternative/api',
              })

    Typescript

    You may use this library in your Typescript project via:

    import Hubspot from 'hubspot';
    const hubspot = new Hubspot({ apiKey: YOUR_API_KEY });

    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, also you will need to provide api key and set some workflow id;

    NOTE: Your HubSpot user ID; This can be found in the same place as your Developer HAPIkey in your Developer portal.

    APPLICATION_ID=111111
    USER_ID=2222222
    ACCESS_TOKEN=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_BBB_CCCC_____-D_EEEEEEEEEEEEEEEEEEEEEEE_fffffff-gggggg"
    HUBSPOT_API_KEY=1111-2222-3333-4444-5555
    TEST_WORKFLOW_ID=333

    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.

    Keywords

    Install

    npm i hubspot

    DownloadsWeekly Downloads

    34,550

    Version

    2.3.14

    License

    MIT

    Unpacked Size

    215 kB

    Total Files

    98

    Last publish

    Collaborators

    • brainflake
    • kr1sp1n
    • tejasmanohar
    • pcothenet
    • vkhomiv-hubspot
    • yfaktor
    • ksvirkou-hubspot
    • manuelmadkudu