No Proscribed Meaning

    @hubspot/api-client
    TypeScript icon, indicating that this package has built-in type declarations

    8.4.2 • Public • Published

    hubspot-api-nodejs

    NodeJS v3 HubSpot API SDK(Client) files

    Sample apps

    Please, take a look at our Sample apps

    Installing

    npm install @hubspot/api-client

    Instantiate client

    const hubspot = require('@hubspot/api-client')
    const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN })

    For ES modules

    import { Client } from "@hubspot/api-client";
    const hubspotClient = new Client({ accessToken: YOUR_ACCESS_TOKEN });

    You'll need to create a private app to get your access token or you can obtain OAuth2 access token.

    You can provide developer API key. There is no need to create separate client instances for using endpoints with API key and Developer API key support.

    const hubspotClient = new hubspot.Client({ developerApiKey: YOUR_DEVELOPER_API_KEY })
    const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN, developerApiKey: YOUR_DEVELOPER_API_KEY })

    To change the base path:

    const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN, basePath: 'https://some-url' })

    To add custom headers to all request:

    const hubspotClient = new hubspot.Client({
        accessToken: YOUR_ACCESS_TOKEN,
        defaultHeaders: { 'My-header': 'test-example' },
    })

    If you're an app developer, you can also instantiate a client and obtain a new accessToken with your app details and a refresh_token:

    hubspotClient.oauth.tokensApi
        .createToken('refresh_token', undefined, undefined, YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REFRESH_TOKEN)
        .then((results) => {
            console.log(results)
    
            // this assigns the accessToken to the client, so your client is ready
            // to use
            hubspotClient.setAccessToken(results.accessToken)
    
            return hubspotClient.crm.companies.basicApi.getPage()
        })

    Retry mechanism

    It's possible to turn on retry for failed requests with statuses 429 or 5xx. To turn on/off configurable retries use numberOfApiCallRetries option on Client instance creation. numberOfApiCallRetries can be set to a number from 0 - 6. If numberOfApiCallRetries is set to a number greater than 0 it means that if any API Call receives ISE5xx this call will be retried after a delay 200 * retryNumber ms and if 429 (Rate limit is exceeded) is returned for "TEN_SECONDLY_ROLLING" the call will be retried after a delay 10 sec. Number of retries will not exceed numberOfApiCallRetries value.

    const hubspotClient = new hubspot.Client({
        accessToken: YOUR_ACCESS_TOKEN,
        numberOfApiCallRetries: 3,
    })

    Usage

    All methods return a promise. The success includes the serialized to JSON body and response objects. Use the API method via:

    hubspotClient.crm.contacts.basicApi
        .getPage(limit, after, properties, propertiesWithHistory, associations, archived)
        .then((results) => {
            console.log(results)
        })
        .catch((err) => {
            console.error(err)
        })

    {EXAMPLE} Create Contact, Company and associate created objects

    const contactObj = {
        properties: {
            firstname: yourValue,
            lastname: yourValue,
        },
    }
    const companyObj = {
        properties: {
            domain: yourValue,
            name: yourValue,
        },
    }
    
    const createContactResponse = await hubspotClient.crm.contacts.basicApi.create(contactObj)
    const createCompanyResponse = await hubspotClient.crm.companies.basicApi.create(companyObj)
    await hubspotClient.crm.companies.associationsApi.create(
        createCompanyResponse.id,
        'contacts',
        createContactResponse.id,
        [
            {
                  "associationCategory": "HUBSPOT_DEFINED",
                  "associationTypeId": 280
            }
        ]
    )

    {EXAMPLE} Update multiple objects in batch mode

    const dealObj = {
        id: yourId,
        properties: {
            amount: yourValue,
        },
    }
    
    const dealObj2 = {
        id: yourId,
        properties: {
            amount: yourValue,
        },
    }
    
    await hubspotClient.crm.deals.batchApi.update({ inputs: [dealObj, dealObj2] })

    {EXAMPLE} Import Contacts:

    const fs = require('fs')
    
    const fileName = 'test.csv'
    
    const file = {
        data: fs.createReadStream(fileName),
        name: fileName,
    };
    
    const importRequest = {
        name: 'import(' + fileName + ')',
        files: [
            {
                fileName: fileName,
                fileImportPage: {
                    hasHeader: true,
                    columnMappings: [
                        {
                            columnName: 'First Name',
                            propertyName: 'firstname',
                            columnObjectType: 'CONTACT',
                        },
                        {
                            columnName: 'Email',
                            propertyName: 'email',
                            columnObjectType: 'CONTACT',
                        },
                    ],
                },
            },
        ],
    }
    
    const response = await  hubspotClient.crm.imports.coreApi.create(file, JSON.stringify(importRequest));
    
    console.log(response)

    {EXAMPLE} Search Contacts:

    Only 3 FilterGroups with max 3 Filters are supported.

    Despite 'sorts' is an array, however, currently, only one sort parameter is supported.

    In JS 'sort' it's possible to set as:

    1. < propertyName > - returned results will be sorted by provided property name in 'ASCENDING' order. e.g: 'hs_object_id'
    2. < stringified sort object > - returned results will be sorted by provided property name and sort direction. e.g: JSON.stringify({ propertyName: 'hs_object_id', direction: 'ASCENDING' }) or JSON.stringify({ propertyName: 'hs_object_id', direction: 'DESCENDING' })
    3. < sort object > - returned results will be sorted by provided property name and sort direction. e.g: { propertyName: 'hs_object_id', direction: 'ASCENDING' } or { propertyName: 'hs_object_id', direction: 'DESCENDING' }

    In TS works only the first two options.

    after for initial search should be set as 0

    const filter = { propertyName: 'createdate', operator: 'GTE', value: `${Date.now() - 30 * 60000}` }
    const filterGroup = { filters: [filter] }
    const sort = JSON.stringify({ propertyName: 'createdate', direction: 'DESCENDING' })
    const query = 'test'
    const properties = ['createdate', 'firstname', 'lastname']
    const limit = 100
    const after = 0
    
    const publicObjectSearchRequest = {
        filterGroups: [filterGroup],
        sorts: [sort],
        query,
        properties,
        limit,
        after,
    }
    
    const result = await hubspotClient.crm.contacts.searchApi.doSearch(publicObjectSearchRequest)
    console.log(JSON.stringify(result))

    Get all:

    getAll method is available for all major objects (Companies, Contacts, Deals, LineItems, Products, Quotes & Tickets) and works like

    const allContacts = await hubspotClient.crm.contacts.getAll()

    Please note that pagination is used under the hood to get all results.

    OAuth

    Obtain your authorization url

    const clientId = 'your_client_id'
    const redirectUri = 'take_me_to_the_ballpark'
    const scope = 'some scopes'
    const uri = hubspotClient.oauth.getAuthorizationUrl(clientId, redirectUri, scope)

    Obtain an access token from an authorization_code

    return hubspotClient.oauth.tokensApi.createToken(
            'authorization_code',
            code, // the code you received from the oauth flow
            YOUR_REDIRECT_URI,
            YOUR_CLIENT_ID,
            YOUR_CLIENT_SECRET,
        ).then(...)

    CMS

    Get audit logs

    const auditLogsResponse = await hubspotClient.cms.auditLogs.defaultApi.getPage()

    Not wrapped endpoint(s)

    It is possible to access the hubspot request method directly, it could be handy if client doesn't have implementation for some endpoint yet. Exposed request method benefits by having all configured client params.

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

    get contacts

    const response = await hubspotClient.apiRequest({
        method: 'get',
        path: '/crm/v3/objects/contacts',
    })
    const json = await response.json()
    console.log(json)

    upload a file

    const formData = new FormData();
    const options = {
    // some options
    };
    formData.append("folderPath", '/');
    formData.append("options", JSON.stringify(options));
    formData.append("file", fs.createReadStream('file path'));
    
    const response = await hubspotClient.apiRequest({
        method: 'POST',
        path: '/filemanager/api/v3/files/upload',
        body: formData,
        defaultJson: false
    });
    
    console.log(response);

    Typescript

    You may use this library in your Typescript project via:

    import * as hubspot from '@hubspot/api-client'
    const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN , developerApiKey: YOUR_DEVELOPER_API_KEY })

    License

    Apache 2.0

    Contributing

    Install project dependencies with

    npm install

    You can run the tests by executing:

    npm run test

    You can check the TypeScript code by running:

    npm run lint
    

    If there is a linting error based on formatting, you can run the command below to auto-correct the formatting:

    npm run prettier:write
    

    Install

    npm i @hubspot/api-client

    DownloadsWeekly Downloads

    159,995

    Version

    8.4.2

    License

    ISC

    Unpacked Size

    11.1 MB

    Total Files

    5793

    Last publish

    Collaborators

    • jsines
    • tfinley_hs
    • mshannon_hs
    • bbriggs
    • arota-hubspot
    • bbarbosa-hubspot
    • service-ccs
    • kemmerle
    • banderson
    • also
    • rberdeen-hubspot
    • harminder01
    • bkrainer-hs
    • friss
    • jhilker
    • atanasiuk
    • ksvirkou-hubspot
    • kbreeman-hubspot
    • brodgers16