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. Individual instances of objects, called records, represent the individual entities under each object type (e.g., John Smith is a contact). To store data in each record, you'll use properties (e.g., the email property), and to represent the relationships between individual entities, you can associate records with one another (e.g., associate John Smith with a company Smith & Co.) Further, CRM records can also store information about interactions through associated engagements/activities, such as emails, calls, and meetings.

Below, learn about CRM objects, records, properties, and additional functionalities. To learn more about managing your CRM database from within HubSpot, check out HubSpot's Knowledge Base.

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

• Contacts: store information about an individual person. View contacts endpoints 
• Companies: store information about an individual business or organization. View companies endpoints 
• Deals: represent revenue opportunities with a contact or company. They’re tracked through pipeline stages, resulting in the deal being won or lost. View deals endpoints
• Tickets: represent customer requests for help or support. They're tracked through pipeline statuses, resulting in the ticket being closed. View tickets endpoints 
• Calls: store information about calls with contacts, but can also be associated with other objects as an engagement. View calls endpoints.
• Quotes: represent pricing information shared with potential buyers. Quotes can be associated with contacts, companies, deals, and line items. View quotes endpoints.
• Custom Objects (Enterprise only): create a custom object to store any type of data in HubSpot—particularly data that doesn't fit the standard objects listed above. View custom object endpoints

• Activities/Engagements (Calls, Emails, Meetings, Notes, Tasks, SMS, LinkedIn, WhatsApp, Postal Mail): represent interactions associated with your records. You can associate activities with contacts, companies, deals, tickets, and custom objects. View engagements endpoints.
• Products: represent goods or services for sale. Products can't be associated with other CRM objects, but you can create line items based on products and associate those with deals and quotes. View products endpoints
• Line items: represent individual products and services sold in a deal. Line items can be created from existing products in your product library, or can be created as standalone line items. Standalone line items will not be added to the 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
• Invoices: represent the invoices that you send for sales made. Invoices can be associated with contacts, companies, deals, line items, discounts, fees, and taxes. 
• Payments: the payments made by buyers through invoices, payment links, and quotes. Payments can be associated with  contacts, companies, deals, invoices, quotes, line items, subscriptions, discounts, fees, and taxes.
• Subscriptions: recurring payments scheduled through payment links and quotes. Invoices can be associated with contacts, companies, deals, quotes, line items, payments, discounts, fees, and taxes.
• Users: represent the users in your HubSpot account. Users cannot be associated with other CRM objects, but can be retrieved and updated through the users API. You can also add users to an account with the user provisioning API.

The following objects can be added via the data model template and object library beta. For these objects, you can use the basic V3 object create, read, update, and delete endpoints (e.g., contacts).

• Appointments: represent encounters or services scheduled for an individual. This object type is often used in the healthcare industry.
• Courses: represent structured programs or series of lessons, trainings, or educational modules.
• Listings: represent properties or units to be bought, sold, or rented.
• Services: represent intangible offerings provided to customers. Examples include onboarding and consulting, repairs and maintenance, and personal care.

In HubSpot, you can show how objects are related to one another by associate records. 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, tickets, and activities, which can be associated with one another, shown in the model below. If you have access to a HubSpot account, you can review your account's unique object relationships by navigating to the data model tool.

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.

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

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.

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.

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-46
• Tasks: 0-27
• Products: 0-7
• Invoices: 0-52
• Line items: 0-8
• Payments: 0-101
• Quotes: 0-14
• Subscriptions: 0-69
• Communications (SMS, LinkedIn, WhatsApp messages): 0-18
• Postal mail: 0-116
• Marketing events: 0-54
• Feedback submissions: 0-19
• Appointments: 0-421
• Courses: 0-410
• Listings: 0-420
• Services: 0-162

• 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.

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. 

For example, the following request would batch update two contact records identified by their ID.

POST /crm/v3/objects/contacts/batch/update

For batch create actions, you can enable multi-status errors which tell you which records were successfully created and which were not. Learn more about setting up multi-status error handling.

Information about records are stored in fields called properties, which are then organized into groups. HubSpot provides a set of default properties for each object. In addition to each object’s default properties, you can store custom data by creating custom 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:

• Contacts
• Companies
• Deals
• Tickets
• Feedback submissions
• Invoices
• Payments
• Subscriptions

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

You can assign HubSpot users as owners of 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. 

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 assigned a number as their unique ID.

In HubSpot, 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.

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 and a company's domain name.

In many cases, you can use the record ID (hs_object_id) generated by HubSpot to drive the logic of your integration. However, your data may require other properties with unique values, or there may be times when record ID either cannot be used or complicates the integration logic of your app. In these cases, you can create a custom unique identifier property via the Properties API.

Once you've created a custom unique ID property, you can use it in API calls to to identify and update specific records in the same way you can use hs_object_id, email for contacts, or domain for companies. For example, to retrieve a deal based on its value for a custom unique ID property, your request URL could look like: GET https://api.hubapi.com/crm/v3/objects/deals/abc?idProperty=system_a_unique.