Node.js and client documentation

[Wallace]

Hi,

I have a node script writtent that uses @hubspot/api-client but Its not clear to me how to use this module. I was hoping to find documentation on its github page but all I see is into stuff and examples.

What am I missing, where is the documentation for it?

When I look at the API reference the node examples simply use require() and not the api-client so Im thinking of just ignoring the client and sticking with basic require()

What is the advantage of the node client module?

All thoughts and suggestions welcome 🙂

[JForcherio]

Found this while looking for docs. Are those up yet?

[Wallace]

And for those who like doing things faster.. looks like we can run the APIs in parralel by grouping all of the requests into one promise and waiting for them all to finish.

Here is the same code above modified to get the deals and line items in parallel and using map to process each found:

  let deals = await getDeals(companyId).catch(e => { showError(e) });
  // TODO: handle retrieving more than one page of deals via deals.status;
  if (deals.results.length > 0) {
    let dealList = deals.results[0];
    if (dealList.to) {
      await Promise.all(dealList.to.map(async (dealInfo) => {
        if (dealInfo.id) {
          const lineItems = await getLineItems(dealInfo.id);
          if (lineItems.results.length > 0) {
            let lineItemList = lineItems.results[0];
            if (lineItemList.to) {
              await Promise.all(lineItemList.to.map(async (lineItemInfo) => {
                if (lineItemInfo.id) {
                  let lineItem = await getLineItem(lineItemInfo.id).catch(e => { showError(e) });
                  if (lineItem.hs_product_id) {
                    let product = await getProduct(lineItem.hs_product_id).catch(e => { showError(e) });

[dennisedson]

So when are we going to talk about that blog post 😎

[NMichniok]

Thanks Wallace. That is helpful. I've only been able to find any of the functions by either sifting through the source code our doing a getOwnPropertyNames() call to see what the properties are available. I have also been digging through the basicApi for companies and contacts as well as the associationsApi that associates a company with a contact (and vice versa). I found that the Readme on github is incorrect for the associationsApi. 

In the docs it shows the following for the associationsApi:

hubspotClient.crm.companies.associationsApi.create(
    createCompanyResponse.body.id,
    'contacts',
    createContactResponse.body.id,
)

When in fact there is a 4th property necessary, associationType: string. The associationType must be one of 28 different types (https://legacydocs.hubspot.com/docs/methods/crm-associations/crm-associations-overview). For companies and contacts I have been using either 'company_to_contact' or 'contact_to_company'. Thus, the above code is now:

hubspotClient.crm.companies.associationsApi.create(
    createCompanyResponse.body.id,
    'contacts',
    createContactResponse.body.id,
    'company_to_contact'
)

[Wallace]

Good find!

I also found out something invaluable when working with the client in node.js..   don't use forEach() as I had initially (above).

When you are reading one object and from that getting a batch of associated objects, loop though them with for() not forEach() otherwise the code does not wait for each to finish even thought you added await.

You need this sort of looping logic to build up a complete temporary model of what your working with.

  let deals = await getDeals(companyId).catch(e => { showError(e) });
  // TODO: handle retrieving more than one page of deals via deals.status;
  if (deals.results.length > 0) {
    let result = deals.results[0];
    for (const deal of result.to) {
      let dealId = deal.id;
      if (dealId) {
        // TODO when we need info about the deal..
        // let deal = await getDeal(dealId).catch(e => { showError(e) });
        let lineItems = await getLineItems(dealId).catch(e => { showError(e) });
        if (lineItems.results.length > 0) {
          let lineItemResult = lineItems.results[0];
          for (const lineItem of lineItemResult.to) {
            let lineItemId = lineItem.id;
            if (lineItemId) {
              let lineItem = await getLineItem(lineItemId).catch(e => { showError(e) });
              let productId = lineItem.hs_product_id;
              if (productId) {
                let product = await getProduct(productId).catch(e => { showError(e) });
...

I'll keep posting useful bits of info here for now.. no time to do anything more useful or productive.

[Wallace]

If it helps I found that we can call any API using something like this:

async function getLineItems(dealId) {
  showApiCall('Calling /crm/v3/associations/deal/line_items/batch/read API method. id:', dealId);
  let apiResponse = await hubSpotClient.apiRequest({
    method: 'POST',
    path: '/crm/v3/associations/deal/line_items/batch/read',
    body: { inputs: [{ id: dealId }] },
  });

  return apiResponse.body;
}

Then we can call it and loop through linked line items like:

  let deals = await getDeals(companyId).catch(e => { showError(e) });
  let requestStatus = deals.status;
  // TODO: handle retrieving more than one page of deals
  if (deals.results.length > 0) {
    let result = deals.results[0];
    let to = result.to;
    to.forEach(async function (deal) {
      let dealId = deal.id;
....

So we can use the client modeule even though it has not been configured for all end points.

The endpoints I have worked out so far as the nice and simple ones like:

apiResponse = await hubSpotClient.crm.companies.basicApi.getById(id);
apiResponse = await hubSpotClient.crm.deals.basicApi.getById(id);
apiResponse = await hubSpotClient.crm.lineItems.basicApi.getById(id);
apiResponse = await hubSpotClient.crm.products.basicApi.getById(id);
// the pattern becomes obvious after a while 🙂

Still would have been nice to read this in a simple doc page somwhere.. which Im sure exists....

[WaydeChristie1]

Thanks very much for your post Wallace.

I'd hit a wall writing custom code workflow steps which require use of the sparsely documented Hubspot Node API. There are a lot of methods which the Node API doesn't include (like support for custom objects), and your post has now opened up all of the Hubspot APIs I need.

The only Hubspot documentation I could find about this was on their Node JS API page on Github, but your post got me over the line.

Thanks very much.

[dennisedson · Accepted solution]

@Wallace ,

Thanks!  We are actively working on documentation.  I also invite the community to write up their version of documentation and share it with the community 😀.  Let me know if you are interested and we can write up a blog post!

[ABrown65]

Do these documents exist yet? When I go through the API reference docs I dont see any for Client Libraries

[JForcherio]

Has this documentation been uploaded somewhere?

[NMichniok]

I too have the same question. The examples provided aren't very helpful. Where is a basic get request of a specific company or contact?