Taking your first steps towards developing with the HubSpot CRM may seem overwhelming — it takes time to learn and grow familiar with developing with a CRM platform, or any new product, for that matter. To help boost your confidence as you start your HubSpot development journey, I’ll share some insights from my own onboarding process with the CRM.
Here's what we'll cover in this post:
- Develop a basic understanding of REST API fundamentals
- Get comfortable using HubSpot APIs and Associations
- Understand how to implement authorization
- Get familiar with GrapghQL and its syntax
- Connect with the developer community
Let’s dive in!
Real quick - what is a CRM?
If you’re a total newb about what a CRM even is, here’s a quick explanation before we go any further.
Image source: HubSpot
CRM (Customer Relationship Management) is a platform that houses an organization’s relationships and processes. Efficiently managing a CRM tool internally can be a challenge, because there’s no universal ‘out of the box’ CRM platform that suits a company’s every need. This is why they need a developer like you to build solutions that customize or integrate with the CRM platform so they can better optimize their business data and processes.
To learn more about the HubSpot CRM and how you can start using it, I suggest checking out these resources:
Now that you have a better understanding of what a CRM is, let’s highlight some of the technical foundations that will support your CRM development.
Develop a basic understanding of REST API fundamentals
In my opinion, it’s essential to have a basic understanding of REST API architecture and how to test an API when you start your CRM developer journey. Having an API-first approach to your development process will enable you to create custom integrations and extend the CRM.
API
First, let’s review what an API — Application Programming Interface — is,. An API is an intermediary layer between two systems that communicate with each other using a set of rules. Typically, an API is explained in terms of a client and a server. The application sending the request is referred to as the client, and the application sending the response back is what we call the server.
So, what’s a REST API?
REST API
REST, aka Representational State Transfer, is a type of API in which the client sends requests to the server as data. The server then uses the client’s request to initiate a function, and it returns a response containing data back to the client.
REST defines the following functions: GET, POST, PUT, DELETE, etc. The client uses these functions to access the server data, which is exchanged using an HTTP (Hyper-Text Transfer Protocol) request.
The image above is a diagram of a RESTful API.
HubSpot APIs are built using REST guidelines with HTTP features and return data in JSON format. So, having an API understanding will empower you as a developer to get the most out of the HubSpot CRM.
Get comfortable using HubSpot APIs and Associations
HubSpot APIs
HubSpot has several APIs that allow you, as the developer, to understand the architecture of the HubSpot platform — allowing you to access and manage CRM data.
For this post, we will focus on the CRM Objects API:
https://api.hubapi.com/crm/v(version number)/objects
This particular API allows you to access and integrate with CRM objects and records. HubSpot has four standard objects (contacts, companies, deals, and tickets) in addition to other non-standard objects. Each object contains records which are a single instance of an object containing data within properties. Those properties are fields stored on a record.
Objects, records, and properties are the primary components of the CRM. However, these objects have relationships that are called “associations.” For example, you won’t get too far without a contact object pursuing a deal — which is an association, or a relationship, within the CRM.
HubSpot Associations
Associations within HubSpot are the relationships between objects and records that allow you to manage data better.
HubSpot creates default associations, but you can also create custom associations with or without labels and association types.
Association Types and Labels
The difference between these two is that association types are based on the type of objects being associated and their direction. Association definitions, on the other hand, are unidirectional, which means you'll need to use a different definition depending on the starting object type.
For example, the default contact → company association is one association type, and it has a one-to-many relationship. The contacts ←→ deals association is another association type, this time with a many-to-many relationship. Lastly, a contact → company with a CEO label demonstrates a custom association type.
Here is a visual representation of company, contacts, and deal object association types:
With association labels, you’re able to associate objects with more flexibility and define association types clearly. An association label is categorized into two types:
Primary association labels
By default, all HubSpot accounts can use a primary label. The default primary label is only available for object/company relationships — meaning you can set a primary company on a contact record. However, you can't set a primary contact on a company record. You can learn more about primary labels in the Knowledge Base Article, “Associate records.”
Custom association labels
Custom labels are used to specify the relationship between associated records for objects. With custom association labels, you can create additional relationships between contacts, companies, deals, and tickets, identifying relationships that are meaningful to a business. You can learn more about custom labels in the Knowledge Base Article, “Create and use association labels.”
I suggest always using association labels to eliminate confusion, even if an object has only one association. You can create labels within the HubSpot app or with a schema request using the Association API.
The image above demonstrates adding an association label to a company object in the HubSpot UI.
By understanding associations, it will help you manage data efficiently, eliminate duplicate data and allow end-users to execute their business needs with ease.
Understanding how to implement authorization
REST APIs provide a powerful way to interact with the HubSpot APIs. Once you’ve developed a foundation of API knowledge and identified which HubSpot API you need, you are ready to implement the required authorization to access CRM data.
There are currently three ways to authenticate an API request with HubSpot:
Using OAuth
OAuth provides authentication with an authorization token instead of a password so a user’s identity or credentials aren’t revealed. If you’re unfamiliar with OAuth authentication, I suggest checking out HubSpot’s OAuth 2.0 Quickstart App, a demo app that allows you to get familiar with HubSpot’s OAuth 2.0 server. To learn more about how to manage your tokens, read “Managing Tokens” in the API documentation.
With a private app
Another approach to request and access CRM data from a HubSpot API is to create a private app within your HubSpot account to generate a private app access token specific to your app. A private app also allows you to authenticate using scopes and limits the risk of exposing sensitive data tied to your HubSpot account. The scoped form of authentication only allows permission to the scopes you define for the app, which protects your data should someone gain access to the private app access token. To learn more about private apps and other use cases, I suggest referring to the documentation or to this blog post, which highlights the differences between public and private apps.
A developer API key
Currently, you can use a developer API key to set up APIs associated with public apps. An API key is a code you can generate using the HubSpot account for which you're checking API usage. For example, the Webhooks API uses a developer API key for the Developer Hub that a public app is in for the API, since it handles the webhook settings within a public app.
OAuth and private apps both use a token in the authorization header and require scopes to allow you access to the CRM data you need. However, private apps are great for one-off scripts, or if you need to make a single API request to test or get familiar with HubSpot APIs.
To begin any authentication process, create a developer account and review the documentation to determine which authentication approach makes the most sense for you and your needs with the CRM. Once you’ve implemented authentication, you can begin testing HubSpot APIs with the tooling of your choice to initiate your HubSpot developer journey!
Get familiar with GraphQL and its syntax
As a HubSpot developer, knowing GraphQL isn’t essential — but it’s incredibly helpful. GraphQL will enable you, as a developer, to start building solutions that require making multiple requests with the HubSpot APIs.
Traditionally with a REST API, you have a URL or server where your data entities live. When an API request is made and received, the API responds with your data. Since GraphQL is a query language, you can use it to make multiple requests with the API, so you’re never over-fetching or under-fetching data. Therefore, instead of relying on REST APIs and their separate endpoints for each service, GraphQL allows you to create a single endpoint that accepts multiple queries for multiple requests.
In other words, GraphQL enables you to make multiple requests at once so you can access data for CRM objects AND the data for associated objects with one request.
GraphQL with HubSpot
Luckily, HubSpot allows you to natively use GraphQL with the CRM when you need to query HubSpot data or create a data-driven experience with HubSpot. You can do this by defining your schema for your objects that define the data you need.
GraphQL enables both HubSpot CMS and CRM developers to utilize a single query across CMS sites, custom-coded workflow actions, integrations, and more.
GraphQL also allows developers to build purpose-built solutions, such as a customer portal, custom quotes, content library, and commerce portals, as well as customization options for developers who want to take these features further within HubSpot.
GraphQL Schema
A critical aspect of the GraphQL schema when using HubSpot is defining the data source. You can specify the following data sources in your query to fetch HubSpot data:
For this blog, we will focus on the CRM data source for the GraphQL query schema. Each query includes the following nested fields, identified as the “root” and “child” fields. Below is an example of a GraphQL query including the CRM data source.
The root field value is CRM, and below are the child fields based on the data source you specify and for which you want to fetch data — including any associated properties or collections. You can test your query using the GraphiQL tool within your HubSpot account.
Once you have a basic understanding of the GraphQL syntax, there are ways you can advance your query skills (such as refining and adding logic to your GraphQL queries), in addition to learning how to use GraphQL with an API request. In other words, you can specify the data you need from multiple HubSpot APIs that you could use for custom code action in the workflows, or even create dynamic pages.
Once you overcome the complexities with the GraphQL syntax, you’ll realize what a clean approach GraphQL enables when making HubSpot CRM data requests and working with HubSpot APIs.
Connect with the developer community
Are you overwhelmed yet? We hope not! But don’t worry if you are — you’re not alone, and there’s a community of developers you can call on for tips and advice.
Regardless of your skill level, the HubSpot Community Forum enables developers to connect, whether you have questions to ask or solutions to share. Start by checking out the Discussions page for Developers within the community forum to browse and post about technical topics or questions regarding the HubSpot CRM.
HubSpot Community forum for Developers UI.
I also suggest bookmarking or referencing the listed resources when you begin working with the CRM to support your development journey:
This page is an excellent reference point for any documentation specific to HubSpot APIs.
The Changelog contains information on the latest changes and updates that affect HubSpot developers. I suggest you subscribe to the Changelog to keep up-to-date with platform announcements.
This is a developer-centric blog designed to support developers with specific use cases on the HubSpot platforms, highlighting ways to resolve common developer issues and sharing developer best practices.
The HubSpot Academy offers courses and certifications for both technical and marketing topics. It is primarily educational content related to the HubSpot platforms.
This platform contains a wide array of articles, including guides for more high-level use cases specific to marketing folks on how to best use HubSpot products.
Each resource listed is intended to help you succeed and get the most out of your development experience when working with the HubSpot CRM.
Conclusion
Regardless of the platform, software, language, etc. — a newbie in tech never starts as an expert. If we learn from our mistakes, however, that enables us to help other developers who may experience the same challenges.
By working together and learning from one another, HubSpot developers like us can build the best CRM solutions for our end users.
Please make sure to reach out to me with any questions or feedback. You can also check out a recap of this post that was initially presented at HubSpot.Extend() ‘22, along with several other amazing sessions focusing on the HubSpot CRM.