Skip to content

A Developer's Guide to HubSpot CRM Objects: Company Object

| Hannah Seligson Hannah Seligson

In HubSpot’s CRM (customer relationship management) platform, understanding the different objects and how they interconnect is crucial for developers leveraging the platform's full potential. Previously in our series, "A Developer's Guide to HubSpot CRM Objects," we explored the contact object. Now, we are diving into one of the core HubSpot CRM entities: the company object. Companies within HubSpot are the backbone for storing and organizing information about the businesses and organizations a business interacts with. This post will highlight the company object's functionalities, their associations with contacts, and examples of API usage.

Functionality of Company Object

The company object in HubSpot is designed to encapsulate all pertinent information about a business or organization with which a company has a relationship. This includes not just basic details like the company name, address, and website but also custom properties that can be tailored to fit the specific needs of your business, such as industry type, revenue, number of employees, and more. The flexibility of the company object allows developers to create a rich, detailed database of company information that can be easily accessed and manipulated through the HubSpot platform.

Company Associations

One of the powerful features of the HubSpot CRM is the ability to create associations between different objects. A key association is between contacts, companies, or activities tied to a record. For example, you can associate several contacts to a company and then associate the company and specific contacts to a deal. Therefore, associating a contact with its respective companies allows a streamlined approach to managing client data.

Why this Association is Beneficial:

  • Enhanced Targeting and Personalization: By linking contacts to their companies, you gain insights into the role and influence of individuals within an organization, enabling personalized communication strategies.
  • Efficient Data Management: It simplifies the management of contact information by grouping individuals under their respective companies, making it easier to update and maintain accurate records.
  • Enhance Automation: By leveraging associations, companies can automate workflows and tasks more effectively. For instance, a workflow can be triggered when a contact is associated with a specific deal stage and automates follow-up emails or task assignments.

When making associations with the company object, you’ll primarily work with two parameters:

  1. toObjectId: This is the unique ID for the record or activity you intend to associate with the company. Essentially, this ID specifies the association's target, whether it is a contact, deal, ticket, or any other object or activity within HubSpot's ecosystem that can be linked to a company.
  2. associationTypeId: This parameter serves as a unique ID to define the type of association between the company and the other object or activity. HubSpot provides a set of default association types, each signifying a different kind of relationship (for example, associating companies with contacts, deals, etc.).

If you're ever unsure about which association type to use, you can retrieve the appropriate associationTypeId by making a GET request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. This allows you to explore and utilize predefined association types or custom associations defined within your HubSpot account.

These parameters are important when creating associations between companies and entities with the Companies API, enabling you to maintain a comprehensive view of company relationships.

Example Usage

The Companies API in HubSpot is designed to allow developers to interact programmatically with company data within the HubSpot platform. It provides a powerful interface for creating, updating, deleting, and retrieving company information, seamlessly integrating HubSpot's capabilities with external systems and custom applications. Check out HubSpot’s Postman workspace to fork the latest version of the Companies API and test the various endpoints within the Companies API collection yourself.

Below, we have provided examples of using the company object to illustrate common use cases in our developer community.

Setup Your Node.js Environment

If you’re leveraging a Node.js app, you’ll likely need the ‘Axios’ package to request HTTP to HubSpot’s APIs; otherwise, you can use any HTTP client and language you choose for your app.

npm install axios

Obtain OAuth Access

First, you need authorization to access any HubSpot API. HubSpot offers OAuth (which can be used for both public and private apps) or a private app access token (which is only for private apps.Then, create an app; it can be public or private.


Next, the type of authentication you need varies depending on the type of app you create. HubSpot offers OAuth (can be used for both public and private apps) or a private app access token (only for private apps). For this example, we’ll leverage OAuth.

Use case #1: Associate a Deal with a Company

You will use the Associations API to associate a deal with a company. The endpoint will look something like this:

POST /crm/v4/objects/deals/{dealId}/associations/companies/{companyId}/{associationTypeId}
  • {dealId} is the ID of the deal you want to associate.
  • {companyId} is the ID of the company you want to associate the deal with.
  • {associationTypeId} is the ID representing the type of association you create (e.g., for associating deals with companies).

Here’s how you might construct that request using JavaScript with the Axios library:

const axios = require('axios'); // Replace these variables with your actual data const accessToken = 'your_oauth_access_token'; const dealId = 'your_deal_id'; const companyId = 'your_company_id'; const associationTypeId = 'your_association_type_id'; // Find the correct ID from HubSpot documentation const endpoint = `https://api.hubapi.com/crm/v4/objects/deals/${dealId}/associations/companies/${companyId}/${associationTypeId}`; const headers = { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' }; axios.post(endpoint, {}, { headers: headers }) .then(response => { console.log('Association created successfully', response.data); }) .catch(error => { console.error('Failed to create association', error); });

Note: Please remove comments if you intend to utilize this code block for testing.

The associationTypeId is crucial for specifying the nature of the association between the deal and the company. HubSpot documentation provides the default IDs. Otherwise, you can retrieve them via API.

This example demonstrates how you can securely associate a deal with a company using the Associations API and OAuth for authentication. You can also leverage this Postman collection to demonstrate the same request for your reference. Now, let’s check out the next use case!

Use case #2: Retrieve Companies with a Specific Property

You'll use the search endpoint to retrieve companies with a specific property using HubSpot’s Companies API. When searching for companies, you’ll use this endpoint:

POST /crm/v3/objects/companies/search

This endpoint lets you send a POST request with a JSON body specifying your search criteria.

Here’s an example of how to use the search endpoint to find companies with a specific property, such as “industry” having a value of “technology” using JavaScript with the Axios library:

const axios = require('axios'); // Replace 'your_oauth_access_token' with your actual OAuth access token const accessToken = 'your_oauth_access_token'; const endpoint = 'https://api.hubapi.com/crm/v3/objects/companies/search'; const headers = {   Authorization: `Bearer ${accessToken}`,   'Content-Type': 'application/json' }; const requestBody = {   "filterGroups":[{     "filters":[{       "propertyName": "industry", // Specify the property name you're interested in       "operator": "EQ", // Operator, EQ for 'equals'       "value": "technology" // The value of the property you're looking for     }]   }],   "properties": ["name", "industry", "website"], // Specify which properties you want returned   "limit": 10 // Adjust the limit as necessary }; axios.post(endpoint, requestBody, { headers: headers })   .then(response => {     console.log('Companies retrieved successfully:', response.data);   })   .catch(error => {     console.error('Failed to retrieve companies:', error);   });

Note: Please remove comments if you intend to utilize this code block for testing.

This example demonstrates a search for companies whose industry property is equal to “technology” and requests that the response include the company “name,” “industry,” and “website” properties.

When using the search endpoint, customize the filters in the requestBody to match the specific search criteria you need. Here is a Postman collection for you to reference and test the search endpoint, but it is also adaptable to any search criteria for your own application.

These examples are just the tip of the iceberg. The Companies API offers extensive functionality for working with the company objects, including retrieving a batch of specific companies by record ID, deleting company records, and more.

What’s Next?

Understanding and utilizing the company object allows developers to build more efficient and effective applications for managing business relationships. Leveraging the Companies API offers developers a powerful tool to manage company data, automate workflows, and create seamless integration between HubSpot and external systems. By understanding its capabilities and adhering to best practices, developers can significantly enhance the efficiency and effectiveness of their CRM strategies. Whether building custom integrations, managing large datasets, or automating data synchronization, the Companies API provides the flexibility and power you need to achieve your objectives.

Let's embark on a journey to explore the different objects within the HubSpot CRM. Together, we will uncover valuable insights and guides to help you reach your full development potential on this platform. Stay tuned for our next blog post, where we will dive deeper into one of the most critical objects in HubSpot CRM: deals!
Hannah Seligson

Hannah Seligson is a Developer Advocate who loves to create content to help empower developers with resources and tools to accomplish their development goals!