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 provides a set of standard objects, each representing a different type of relationship or process. For each object, you can create individual records where you can store information in properties and track interactions. You can also make associations between records to understand the relationships between them. 

Below, learn about CRM objects, records, properties, and more. 

Object types

The CRM API provides access to CRM objects and records. The following are the types of objects available in HubSpot:

  • Contacts: store information about an individual person. From marketing automation to smart site content, the lead-specific data found in contact records can help you leverage much of HubSpot's functionality. View contacts endpoints 
  • Companies: store information about an individual business or organization. Multiple contacts can be associated with a company to represent its organizational makeup. View companies endpoints 
  • Deals: represent revenue opportunities with a contact or company. They’re tracked through pipeline stages, eventually resulting in the deal being won or lost. View deals endpoints
  • Tickets: represent customer requests for help or support. View tickets endpoints 
  • Products: represent goods or services for sale. Building a product library allows you to quickly add products to 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 attached to 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.
  • Custom Objects: create a custom object to store any type of data in HubSpot—particularly data that doesn't fit the standard objects listed above. Custom objects are created via the custom object endpoints and can be associated with standard objects. View custom object endpoints

Properties

Detailed information (metadata) for HubSpot’s CRM objects is stored in 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 contacts, companies, deals, or ticket records. Any HubSpot user with access to contacts 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. 

Object capabilities

The table below shows which functionalities are available for each HubSpot object.

CRM Object CRM views Reports Automation Lists Email personalization Custom properties
Contact x x x x x x x
Company x x x x x x x
Deal x x x x x x x
Ticket x x x x   x x
Line Item   x   x x x x
Product           x x
Quote     x        
Engagement/Task x x   x      
Timeline Event       x   x  
Analytics Event       x      
Custom Object x x x x x x x

 

Object relationships

This entity relationship diagram (ERD) illustrates the organization of and relationships between CRM objects.

 

Object and record associations

Associations represent the relationships between objects. You can manage associations using the associations endpoints.

Record engagements

Engagements store data from 1:1 interactions between contacts and your company, including notes, tasks, meetings, and calls. At a minimum, engagements should be associated with at least one contact record, but they can also be associated with deals, tickets, and companies.

Data syncing

Syncing engagement data is not required to sync object data. It’s usually easier to sync property data (such as date of last contact or number of calls to a contact) than the engagement behind it. 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.

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 except for creating and updating contacts, which are limited to 10 records per call. 

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 right records, and handle any needed 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. This ID looks like an incrementing number, though it 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. 

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 those types of cases, you want may to instead create your own unique ID field by following the steps below:

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. 

Note: you can have two unique ID fields for any account-specific custom objects and 10 for standard objects. Contacts cannot have custom defined idProperties, you can use email as the idProperty parameter for calls to the contacts API. 

FAQs

Still have questions about CRM objects? Check out this FAQ.


Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.