Understanding the CRM

The foundation of your HubSpot account is a database of your business relationships and processes, called the CRM (Customer Relationship Management). To manage this data, HubSpot accounts include objects, which represent types of relationships or processes. All HubSpot accounts include four standard objects: contacts, companies, deals, and tickets. Depending on your HubSpot subscription, there are additional objects, such as products and custom objects.

Records are individual instances of an object (e.g., John Smith is a contact). For each record, you can store information in properties, track interactions, and create reports. You can also make associations between records to understand the relationships between them. Below, learn about CRM objects, records, properties, and additional functionalities.

Objects

The CRM API provides access to objects, records, and activities. The list below explains the objects available in HubSpot.

The following objects each have an index page within HubSpot, and can all be associated with each other:

The following objects do not have index pages within HubSpot, but can be associated with certain other objects: 

  • Engagements (Calls, Emails, Meetings, Notes, Tasks, SMS, LinkedIn, WhatsApp, Postal Mail): represent interactions associated with your records, also called activities. You can associate activities with contacts, companies, deals, tickets, and custom objects. View engagements endpoints.
  • Products: represent goods or services for sale. You can associate products with deals, generate quotes, and report on product performance. View products endpoints
  • Line items: represent a subset of products sold in a deal. When a product is associated with a deal, it becomes a line item. You can create line items that are unique to an individual quote, but they will not be added to your product library. View line items endpoints
  • Feedback submissions: stores information submitted to a feedback survey. Feedback submissions are associated with contact records. View feedback submission endpoints
  • Marketing events: represent events related to your marketing efforts, specifically including events from connected integrations. You can specify whether or not a contact attended, registered for, or cancelled attending a marketing event. View marketing events endpoints

Object relationships

Within HubSpot, to show how objects are related to one another, you can associate records of different objects. For example, you can associate multiple contacts with a company, and then associate the company and relevant contacts with a deal. All HubSpot accounts have contacts, companies, deals, and tickets, which can be associated with one another, shown in the model below. data-model-explorer

Depending on your subscription, you can describe the specific relationship between records using association labels, and your account may have additional custom objects, which can be associated with the other standard objects. Other objects, such as products and line items, can only be associated with certain objects. Learn more about these additional objects and their associations.

If you have access to a HubSpot account, you can review your account's unique object relationships by navigating to Reports > Data Management > Data Model.

Learn more about object relationships and managing associations using the associations endpoints.

Engagements and attachments

Engagements, also called activities, store data from interactions with records. For example, if you call a prospect, you can log a call to the contact record, and also associate the call with their associated company. Possible activities include notes, tasks, meetings, emails, calls, postal mail, SMS, LinkedIn messages, and WhatsApp messaged.

You can also store attachments on records to keep track of relevant files. These are often related to engagements.

Learn more about the engagements APIs.

Data syncing

Syncing engagement data is not required to sync object data. Because an object can be associated with numerous engagements, it’s also important to keep API limits in mind before syncing.

However, you may want to sync engagements rather than properties when an integration is a precursor to a full migration. In this case, syncing engagements across both systems will ensure all users have the data they need during the transition. For example, when a business development team working in HubSpot is handing deals to an inside sales rep working in another CRM, you should sync engagements so both teams have the context they need to close a sale.

Object type IDs

When using certain APIs, you'll need to use the objectTypeId field. Below are the ID values for each object or activity:

  • Contacts: 0-1
  • Companies:  0-2
  • Deals: 0-3
  • Tickets: 0-5
  • Custom objects: to find the ID value for your custom object, make a GET request to /crm/v3/schemas. The value will look similar to 2-3453932. 
  • Calls: 0-48
  • Emails: 0-49
  • Meetings: 0-47
  • Notes: 0-4
  • Tasks: 0-27
  • Products: 0-7
  • Line items: 0-8
  • Communications (SMS, LinkedIn, WhatsApp messages): 0-18
  • Postal mail: 0-116
  • Marketing events: 0-54
  • Feedback submissions: 0-19

While you can always use the numerical ID value, in some cases, you can also use the object's name for contacts, companies, deals, tickets, or notes. For example:

  • When starting an import with the imports API, the columnObjectTypeId specifies which object the data in your file belongs to. To import data for contacts, your value for columnObjectTypeId could be contact or 0-1.
  • When using the associations API, the fromObjectType and toObjectType values specify the objects and the direction of the association. To view association types for contacts to companies, your GET request URL could be crm/v4/associations/contact/company/labels or crm/v4/associations/0-1/0-2/labels.

Batch actions

Each object provides batch endpoints that let you create, read, update, and archive multiple object records in a single request. Batch endpoints have a limit of 100 records per call.

Properties

Information about records are stored in fields called properties, which are then organized into groups. In addition to each object’s default properties, you can store custom data by creating custom properties. 

Default properties

CRM objects are defined by a primary type and a set of properties. Each type has a unique set of standard properties, represented by a map of name-value pairs. Learn more about default properties for different objects:

Custom properties

Create custom properties to store specialized information for an object. Custom properties can be managed through the CRM object properties endpoints.

Property groups

Property groups are used to group related properties. When viewing records in HubSpot, any grouped properties will appear next to each other. If your integration creates any custom object properties, organizing them in a custom property group will make it easy to identify that data.

Clearing properties

You can clear an object property value via the API by setting the property value to an empty string.

Example: To clear the firstname from a contact object, send a PATCH request to https://api.hubapi.com/crm/v3/objects/contacts/{contactId} with the body { "properties": { "firstname": ""} }.

Record owners

You can assign owners to records. Any HubSpot user with access to an object can be assigned as an owner, and multiple owners can be assigned to an object by creating a custom property for this purpose. Owners can only be created in HubSpot, but you can use the owners endpoint to get their identifying details, including IDs and email addresses. This data can then be assigned to CRM records in HubSpot or via property change API calls. 

Unique identifiers and record IDs

A unique identifier is a value that differentiates one record in a database from another, even if they have otherwise identical information. For example, a database for a bank might have records for two people named John Smith.  To avoid accidentally sending money to the wrong John Smith, each record is given a number as their unique ID.

You'll use these unique identifiers to send your data to the correct records, and manage deduplication. Learn more about the ways that HubSpot handles deduplication in the Knowledge Base.

HubSpot’s default unique identifiers

When a record is created in HubSpot, a unique ID is automatically generated and should be treated as a string. These IDs are unique only within the object type, so there can be both a contact and company with the same ID. 

For contacts and companies, there are additional unique identifiers, including a contact's email address and a company's domain name.

Creating your own unique identifiers

In many cases, you can use the record ID generated by HubSpot to drive the logic of your integration. However, there are times when that isn't possible or it complicates the integration logic of your app. For example:

  • A legacy CRM can't store HubSpot's object ID with the associated record, making it impossible to match corresponding records in the two systems.
  • An integration is syncing updates from another app to HubSpot, but not from HubSpot to the other app. Instead of mapping IDs from both systems, the integration simply uses the external app's IDs when creating or updating records. 

In these cases, you want may to create your own unique ID property. You can have up to ten unique ID properties per object. Follow the steps below to create your unique ID property:

1. Create your unique ID field via the Properties API.  Your API call might look something like this:

JSON 
//POST https://api.hubapi.com/crm/v3/properties/deals
{
  "groupName": "dealinformation",
  "hidden": false,
  "displayOrder": 2,
  "name":"system_a_unique",
  "label": "Unique ID for System A",
  "hasUniqueValue": true,
  "type": "string",
  "fieldType": "string"
}

The key field to set is the hasUniqueValue. This tells HubSpot to make sure that any objects (in this case, deals) created in the future will never have the same value for this property. Note: this field cannot be changed, so we recommend you exercise caution when using it. 

2. Once you've created your unique ID field, you can use it in an API call to get specific records. That call might look like this:

GET https://api.hubapi.com/crm/v3/objects/deals/abc?idProperty=system_a_unique

This will return the deal with the value of abc in the system_a_unique field. You never have to know that HubSpot assigned this deal an object ID of 263782, though this will be included in the response by default. 

FAQs

For more information about objects in HubSpot, learn how to manage your CRM database.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.