Companies
In HubSpot, companies store information about the organizations that interact with your business. The companies endpoints allow you to manage create and manage company records, as well as sync company data between HubSpot and other systems.
Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide. For more general information about objects and records in HubSpot, learn how to manage your CRM database.
To create new companies, make a POST
request to /crm/v3/objects/companies
.
In your request, include your company data in a properties object. You can also add an associations object to associate your new company with existing records (e.g., contacts, deals), or activities (e.g., meetings, notes).
Company details are stored in company properties. There are default HubSpot company properties, but you can also create custom properties.
When creating a new company, you should include at least one of the following properties in your request: name
or domain
. It is recommended to always include domain
, because domain names are the primary unique identifier to avoid duplicate companies in HubSpot. If a company has multiple domains, you can add them through the API by using the hs_additional_domains
field with semicolons separating each domain. For example: "hs_additional_domains" : "domain.com; domain2.com; domain3.com"
.
To view all available properties, you can retrieve a list of your account's company properties by making a GET
request to /crm/v3/properties/companies
. Learn more about the the properties API.
lifecyclestage
in your request, values must refer to the lifecycle stage's internal name. The internal names of default stages are text values, and do not change even if you edit the stage's label(e.g., subscriber
or marketingqualifiedlead
). The internal names of custom stages are numeric values. You can find a stage's internal ID in your lifecycle stage settings, or by retrieving the lifecycle stage property via API.
For example, to create a new company, your request may look similar to the following:
When creating a new company, you can also associate the company with existing records or activities. In the associations object, include the following fields:
Parameter | Description |
---|---|
toObjectId
| The ID of the record or activity that you want to associate the company with. |
associationTypeId
| A unique identifier to indicate the association type between the company and the other object or activity. Default association types are listed here, or you can retrieve the value by making a |
You can also include the label
field to assign a defined association label that describes the association. Learn more about associating records via the associations API.
For example, to associate a new company with an existing contact and email, your request would look like the following:
You can retrieve companies individually or in batches.
- To retrieve an individual company, make a
GET
request to/crm/v3/objects/companies/{companyId}
. - To request a list of all companies, make a
GET
request to/crm/v3/objects/companies
. - To retrieve a batch of specific companies by record ID or a custom unique identifier property, make a
POST
request tocrm/v3/objects/companies/batch/read
.
For these endpoints, you can include the following query parameters in the request URL:
Parameter | Description |
---|---|
properties
| A comma separated list of the properties to be returned in the response. If the requested company doesn't have a value for a property, it will not appear in the response. |
associations
| A comma separated list of objects to retrieve associated IDs for. Any specified associations that don't exist will not be returned in the response. Learn more about the associations API. |
For the batch read endpoint, you can also use the optional idProperty
parameter to retrieve companies by a custom unique identifier property. By default, the id
values in the request refer to the record ID (hs_object_id
), so the idProperty
parameter is not required when retrieving by record ID. To use a custom unique value property to retrieve companies, you must include the idProperty
parameter.
For example, to retrieve a batch of companies, your request could look like either of the following:
You can update companies individually or in batches. For existing companies, the company's record ID is a unique value that you can use to update the company via API.
To update an individual company by its company ID, make a PATCH
request to /crm/v3/objects/companies/{companyId}
, and include the data you want to update.
To associate a company with other CRM records or an activity, make a PUT
request to /crm/v3/objects/companies/{companyId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
associationTypeId
value, refer to this list of default values, or make a GET
request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels
.
Learn more about associating records with the associations API.
To remove an association between a company and a record or activity, make a DELETE
request to the following URL: /crm/v3/objects/companies/{companyId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
You can delete companies individually or in batches, which will add the company to the recycling bin in HubSpot. You can later restore the company within HubSpot.
To delete an individual company by its ID, make a DELETE
request to /crm/v3/objects/companies/{companyId}
.
Learn more about batch deleting companies on the Endpoints tab at the top of this article.
Thank you for your feedback, it means a lot to us.