Understanding the CRM

Just as the name says, HubSpot’s CRM is a system for managing customer relationships and storing data. Whether you’re here to learn how the HubSpot CRM works or getting ready to integrate it with another system, you’re in the right place. Keep reading for a breakdown of CRM object types, properties, relationships, associations, owners, and engagements. 

Object types

The CRM API provides access to CRM objects or groups of objects, which are represented as a map of property names to values. 

  • Contacts: 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: Company records 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: 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: Tickets represent customer requests for help or support. View tickets endpoints 
  • Products: 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: Line items can be thought of as a subset of products. 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

Object 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": ""} }.

Object owners

You can assign owners to contacts, companies, deals, or tickets. 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. 

CRM object capabilities

CRM Object Create a view of this object Report on this object Automate this object Create lists of this object Create lists of contacts using this object's information Use properties of this object in emails Can have custom properties
crm_object(s) usage
Contact x 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      

 

Object relationships

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

 

Associations between objects

Associations represent the relationships between objects (see above). You can manage associations using the associations endpoints.

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; you can also associate them 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.

Exceptions

  • General: When an integration is a precursor to a full migration, you’ll want to sync engagements across both systems to ensure all users have the data they need during the transition.
  • Example use case: 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.

Deduplication

HubSpot deduplicates CRM objects in several ways. This knowledge base article provides more information about both automatic and manual deduplication methods.

Contacts

An email address is the primary identifier for a contact in HubSpot. The contacts endpoints automatically de-duplicate email addresses to keep HubSpot data clean.

Batch endpoints

Each object provides batch endpoints that all you to create, read, update, and archive multiple object instances in a single request. Batch endpoints have a limit of 100 objects per call except for creating and updating contacts, which is limited to 10 objects per call. 

FAQs

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