Skip to content

A Developer's Guide to HubSpot CRM Objects: Contacts Object

| Hannah Seligson Hannah Seligson

Welcome back to our series, "A Developer's Guide to HubSpot CRM Objects." In our first post, we introduced you all to HubSpot standard objects. However, in this second post, we will delve into one of the most fundamental components of the HubSpot CRM: the Contacts object. This deep dive aims to elucidate the purpose of the contacts object, explore their properties and customization options, and introduce the relevant API endpoints for developers looking to leverage this object in their applications.

Properties and Customization

Default Properties

By default, HubSpot provides a set of standard properties for contact objects. These include essential information fields such as:

  • Email: The individual's email address.
  • First Name and Last Name: The personal names of the contact.
  • Company Name: The name of the company the contact is associated with.
  • Phone Number: The contact's phone number.
  • Lifecycle Stage: The stage of the contact in the marketing/sales funnel (e.g., lead, customer).

These properties are designed to facilitate basic contact management and segmentation tasks. However, one size rarely fits all in the world of CRM.

Customization

Recognizing the diverse needs of businesses, HubSpot allows developers to create custom properties for contact objects. This capability is instrumental for tailoring the CRM to specific business requirements. Custom properties can be anything from "Preferred Contact Method" to "Product Interest Level," enabling deeper personalization and targeting.

Developers can create a custom property using the Properties API or the CRM settings interface. This process involves specifying the property's name, type (e.g., text, number, date), and the object type it belongs to (in this case, the contact object).

To better understand how to create custom properties for a contact object, I included an example of using the Properties API to create custom properties for a contacts object using the POST request /crm/v3/properties/contacts endpoint in Postman.

API Endpoints for Contacts

HubSpot provides a rich set of API endpoints for managing contact objects, facilitating a wide range of operations from creating and updating contacts to querying and segmenting them based on specific criteria.

Key Endpoints

  • Create a Contact: This endpoint allows for creating a new contact object with specified properties.
    • Endpoint: POST /crm/v3/objects/contacts
    • Payload Example: {"properties": {"email": "anna.smith@example.com", "firstname": "Anna", "lastname": "Smith"}}
  • Update a Contact: To update existing contact information.
    • Endpoint: PATCH /crm/v3/objects/contacts/{contactId}
    • Payload Example: {"properties": {"firstname": "Anna"}}
  • Search for Contacts: This endpoint can be used to search for contacts based on various criteria.
    • Endpoint: POST /crm/v3/objects/contacts/search
    • Payload Example: {"filterGroups":[{"filters":[{"propertyName":"email","operator":"EQ","value":"anna.smith@example.com"}]}]}

Note: You can also leverage the Search API to search contacts!

Usage Examples

To integrate these API endpoints into your application, you typically use an HTTP client library in your programming language of choice. For example, here is how you would integrate the Contacts API into your Node.js application to create a contact and get a contact by ID.

  • Set up your HubSpot account and create an application (the app can be public or private).
    • Need a HubSpot account: create a test account after signing up for a free developer account.
      • Please note that you must be a Super Admin to install a public app in a HubSpot account or create a private app. If you’re unsure which app to use, here is a helpful blog post explaining the difference.
    • Obtain authorization: Depending on what type of app you create, the type of authentication you need varies. HubSpot offers OAuth or a private app access token. For the sake of this example, we’ll be leveraging OAuth.
  • Install the required Node.js packages: You’ll likely need the ‘Axios’ package to make HTTP requests to HubSpot’s APIs, or you can use any HTTP client of your choice.
npm install axios
  • Create a Contact and get a contact by ID: Using the Contacts API endpoints, you can create a new contact and retrieve a contact by their unique ID.
const axios = require('axios'); const ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'; // You obtain this from the OAuth flow const BASE_URL = 'https://api.hubapi.com'; // Function to create a contact with OAuth async function createContact() { try { const response = await axios.post(`${BASE_URL}/crm/v3/objects/contacts`, { properties: { firstname: 'Anna', lastname: 'Smith', email: 'anna.smith@example.com', company: "Anna Smith's Bakery", phone: '555-555-5555', website: 'http://www.annasbakery.com' } }, { headers: { Authorization: `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' } }); console.log('Contact created:', response.data); return response.data; } catch (error) { console.error('Error creating contact:', error.response ? error.response.data : error.message); } } // Function to get a contact by ID with OAuth async function getContactById(contactId) { try { const response = await axios.get(`${BASE_URL}/crm/v3/objects/contacts/${contactId}`, { headers: { Authorization: `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, params: { properties: ['firstname', 'lastname', 'email'] // Specify the properties you want to retrieve } }); console.log('Contact details:', response.data); return response.data; } catch (error) { console.error('Error getting contact:', error.response ? error.response.data : error.message); } } // Example usage createContact(); // Create a new contact getContactById('CONTACT_ID'); // Replace 'CONTACT_ID' with the actual ID of the contact you want to retrieve
  • You can replace ‘YOUR_ACCESS_TOKEN’ with the access token you obtain through the OAuth process.
  • Obtaining an access token involves user redirection to HubSpot for authorization and then exchanging a code for an access token. This step is not shown here but is essential before making API calls.
  • The ‘createContact’ function demonstrates creating a new contact with some basic fields. You can modify the properties object to include any other fields you need.
  • The ‘getContactById’ function shows how to retrieve a contact by their ID. You need to replace ‘CONTACT_ID’ with the actual ID of the contact you wish to retrieve.

This example will help you integrate HubSpot's Contacts API into your Node.js application. If you want to explore other endpoints for the Contacts API, please check out our Postman workspace. Also, you can fork the latest API version into your own workspace to make it easier to test this API, or you can leverage this custom Postman collection to guide you through creating and retrieving a contact object.

Conclusion

The Contacts object in HubSpot is a powerful tool for developers. It offers extensive customization and integration capabilities. By understanding and utilizing the default and custom properties and the robust API endpoints provided, developers can significantly enhance the CRM's value to their business. This can help in driving more personalized and effective customer engagement strategies.

Stay tuned for the next blog post to explore another critical HubSpot CRM object: companies!
Hannah Seligson

Hannah Seligson is a Developer Advocate who loves to create content to help empower developers with resources and tools to accomplish their development goals!