HubSpot API Example: Your Guide to Smarter Integrations

So, you want to really get into HubSpot’s API and make it do some cool stuff for your business? Awesome! Knowing how to use the HubSpot API is like having a secret weapon for connecting all your different business tools. It lets your systems talk to each other, automating those tedious tasks, and keeping your customer data perfectly synced. Back in the day, everyone relied on API keys, but things have shifted. Now, private apps are the go-to for secure authentication, giving you way more control over what your integrations can actually do. If you’ve been wondering how to connect your website forms, manage contacts from a custom app, or even upload files directly to your HubSpot portal, you’re in the right spot. We’re going to break down how to get started, walk through some practical examples in popular programming languages, and even show you how to test everything with a tool like Postman.

Why Even Bother with the HubSpot API?

Look, HubSpot is already a powerful CRM, but its API lets you push the boundaries. It’s not just for big tech companies. even small businesses can use it to make their lives a whole lot easier. You might be thinking, “What can I actually do with it?” Well, the possibilities are pretty vast.

Automating Data Sync Contacts, Companies, Deals

One of the biggest headaches for any business is keeping customer information consistent across different platforms. The HubSpot API shines here. You can automatically sync contacts, companies, and deals between HubSpot and other systems you use, like your internal sales tools or even another CRM. This means no more manually entering data in multiple places, which can save a ton of time and prevent errors. When information gets updated in one system, the API can ensure it’s reflected in HubSpot, and vice-versa. Businesses using CRM systems, for instance, can see around a 29% improvement in sales performance. That’s a pretty compelling reason to keep your data flowing!

Lead Generation & Scoring

If you’re serious about bringing in new leads, the API can be a must. You can integrate it with your website or applications to capture user data and automatically push it right into your HubSpot CRM. Beyond just capturing leads, the API helps with automated lead scoring. This means you can set up rules to automatically score leads based on how they interact with your website, email campaigns, or other touchpoints. This helps your sales team focus on the most promising leads, improving their efficiency.

Marketing Automation & Custom Workflows

Ever wish you could trigger a specific action in HubSpot based on something happening in another system? That’s where custom workflows come in. The API lets you create these custom triggers and actions. For example, if a customer makes a purchase in your e-commerce platform, you could use the API to update their lifecycle stage in HubSpot, enroll them in a follow-up email sequence, or create a task for your sales team. This really extends HubSpot’s marketing automation capabilities.

Integrating with Third-Party Systems

HubSpot’s marketplace has tons of integrations, but sometimes you need something super specific. That’s when the API becomes your bridge. HubSpot’s File Manager: Your Ultimate Guide to Organizing and Optimizing Digital Assets

• Webinars or Events: If you host webinars or events using a different platform, the API can feed registration and attendance data directly into your HubSpot CRM, keeping all your lead information in one place.
• E-commerce: For online stores, you can use the API to pass transaction data to HubSpot, even if your e-commerce platform isn’t natively integrated.
• Other CRMs: Many businesses use multiple tools. The HubSpot API allows you to sync data across different CRM systems, making sure sales, marketing, and customer service all have access to the same up-to-date information.

Getting Started: Authentication – The Gateway to Your Data

Before you can do anything with the HubSpot API, you need to tell HubSpot who you are and that you’re allowed to access your account’s data. This is where authentication comes in, and it’s super important for security.

The Old Way: API Keys and why they’re gone

For a long time, the simplest way to authenticate was using a single HubSpot API key often called the HAPIkey. You’d grab this key from your portal settings and include it as a query parameter in your API requests. It was easy, but it had a huge flaw: it gave root access to almost all endpoints. If someone got hold of your API key, they could access and potentially mess with a lot of your data without any restrictions.

Because of these security concerns, HubSpot stopped supporting API keys as an authentication method on November 30, 2022. So, if you’re building something new or updating an old integration, you absolutely need to use one of the newer, more secure methods.

The New Way: Private Apps Recommended

The best way to authenticate your API calls today, especially for integrations specific to your own HubSpot portal, is through Private Apps. Private apps still use a token, similar to an API key, but they offer a crucial advantage: granular permissions scopes. This means you can create an app and specify exactly what data it can read or modify. So, if one of your apps only needs to read contact information, you grant it only those specific “read contact” permissions. If that token ever gets compromised, the damage is limited to only what you allowed that specific app to do. Cracking the Code: Your Guide to HubSpot on Glassdoor

How to Create a Private App and Get Your Access Token

Creating a private app is pretty straightforward:

1. Log in to HubSpot: Go to your HubSpot account.
2. Navigate to Settings: Click the settings gear icon in the main navigation bar.
3. Find Private Apps: In the left sidebar, go to Integrations > Private apps.
4. Create a New App: Click “Create a private app.”
5. Basic Info: Give your app a name and a description. Make it something clear so you know what it’s for later.
6. Configure Scopes: This is the most important part. Go to the “Scopes” tab. Here, you’ll see a list of all the permissions you can grant your app, categorized by different HubSpot features CRM, CMS, etc.. For example, if you want to create and read contacts, you’d select crm.objects.contacts.read and crm.objects.contacts.write. Only select the permissions your app absolutely needs.
7. Create App: Once you’ve set the scopes, click “Create app.”
8. Get Your Token: After the app is created, go to its “Auth” tab. Click “Show token” and then “Copy” to get your access token. Treat this token like a password! Never hardcode it directly into your public code. use environment variables or a secure configuration file instead.

This token is what you’ll use in your API requests, typically in an Authorization header like Bearer YOUR_ACCESS_TOKEN. Unlike the old API keys, private app tokens don’t expire every few hours, making them more convenient for server-side integrations.

OAuth for public apps/complex integrations

If you’re building an integration that will be used by multiple HubSpot accounts e.g., an app you plan to list on the HubSpot App Marketplace, then OAuth is the way to go. OAuth is a more complex authentication flow where users grant your application permission to access their HubSpot data without you ever seeing their login credentials. It involves redirecting users to HubSpot to authorize your app, which then provides your app with an access_token and refresh_token. The access_token is used for API calls, and the refresh_token lets you get new access_tokens when the old one expires. While more involved to set up initially, it’s the standard for secure third-party applications.

Making Your First API Call with Postman

When you’re first getting your hands dirty with any API, Postman is truly your best friend. It’s a fantastic tool that lets you build, test, and share API requests without writing any code. It’s perfect for quickly seeing if your authentication works, understanding how endpoints behave, and what kind of responses you’ll get back. Hubspot file manager free

Why Postman Is Your Best Friend

• Easy Testing: You can quickly craft requests, send them, and inspect the responses. This is invaluable for debugging.
• Organized Collections: Postman lets you organize your API calls into collections, which is super handy for different HubSpot APIs CRM, CMS, etc..
• HubSpot Public API Workspace: HubSpot provides an official Postman workspace with pre-built collections for their public APIs. This means you don’t have to start from scratch! You can “fork” these collections into your own workspace, customize them, and even receive updates when HubSpot changes their API.
• Code Generation: Once you have a working request in Postman, you can generate code snippets in various programming languages Python, C#, PHP, JavaScript, etc. directly from Postman. This gives you a great starting point for your actual application.

Setting up Postman with HubSpot’s Public API Workspace

1. Download Postman: If you don’t have it, grab the Postman desktop app.
2. Access HubSpot’s Workspace: Head over to the HubSpot Public API Workspace on Postman’s website.
3. Fork a Collection: You’ll see different collections, like “CRM API Collections.” Fork the one you’re interested in e.g., CRM into your own Postman workspace. Make sure to check the notification box so you’re alerted when the collection updates.

Authenticating with a Bearer Token Private App

Once you’ve forked a collection:

1. Select a Request: Pick an endpoint, like “Get all contacts” under the CRM collection.
2. Go to Authorization Tab: In the request builder, click on the Authorization tab.
3. Choose Bearer Token: From the Type dropdown, select Bearer Token.
4. Enter Your Token: Paste the access token you got from your private app into the Token field.
5. Send Request: Hit the “Send” button.

If everything is set up correctly, you should get a 200 OK response with data from your HubSpot account! If you get an error, like a 401 Unauthorized or 403 Forbidden, double-check your token and ensure your private app has the necessary scopes.

HubSpot API Examples in Code: Bringing it to Life

Let’s dive into some actual code examples for common HubSpot API interactions. We’ll cover Python, C#, and PHP, focusing on CRM objects like contacts and associations, as well as forms and file uploads.

Mastering HubSpot’s File Manager: Your Go-To Guide for Digital Asset Management

Python Examples

Python is a popular choice for API integrations due to its readability and the availability of excellent libraries. HubSpot even provides an official Python client library.

Setting up the Environment

First, you’ll need Python 3.6+ is recommended and the hubspot-api-client package.

pip install hubspot-api-client

Then, you initialize the client with your access token:

import hubspot
from hubspot.crm.contacts import ApiException
import os

# Best practice: Store your access token in an environment variable
HUBSPOT_ACCESS_TOKEN = os.environ.get"HUBSPOT_PRIVATE_APP_TOKEN"

if not HUBSPOT_ACCESS_TOKEN:
    print"Error: HUBSPOT_PRIVATE_APP_TOKEN environment variable not set."
    exit

api_client = hubspot.Client.createaccess_token=HUBSPOT_ACCESS_TOKEN

 Creating a Contact

To create a new contact, you'll send a POST request with the contact's properties in JSON format. The `email`, `firstname`, or `lastname` properties are typically required. It's best to always include `email` to prevent duplicates.

from hubspot.crm.contacts import SimplePublicObjectInputForCreate

def create_hubspot_contactemail, firstname, lastname:
    try:
        simple_public_object_input_for_create = SimplePublicObjectInputForCreate
            properties={
                "email": email,
                "firstname": firstname,
                "lastname": lastname
            }
        
        api_response = api_client.crm.contacts.basic_api.create
            simple_public_object_input_for_create=simple_public_object_input_for_create
        printf"Contact created successfully: {api_response.id}"
        return api_response
    except ApiException as e:
        printf"Error creating contact: {e}"
        return None

# Example usage:
new_contact = create_hubspot_contact"[email protected]", "Jane", "Doe"


 Reading Contacts

You can fetch a list of contacts or a specific contact by ID.
def get_all_hubspot_contacts:
       # get_page is used to retrieve contacts, and you can add parameters for pagination.
       # all_contacts will handle pagination under the hood to get all results. 
        all_contacts = api_client.crm.contacts.get_all
        printf"Total contacts fetched: {lenall_contacts}"
        for contact in all_contacts:
            printf"ID: {contact.id}, Email: {contact.properties.get'email'}, Name: {contact.properties.get'firstname'} {contact.properties.get'lastname'}"
        return all_contacts
        printf"Error retrieving contacts: {e}"
        return 

all_my_contacts = get_all_hubspot_contacts


 Updating a Contact

To update an existing contact, you'll need its `contact_id` and the properties you want to change.
def update_hubspot_contactcontact_id, company_name:
        updated_properties = {
            "company": company_name
        }
        api_response = api_client.crm.contacts.basic_api.update
            contact_id=contact_id,
            simple_public_object_input=hubspot.crm.contacts.SimplePublicObjectInput
                properties=updated_properties
            
        printf"Contact {contact_id} updated successfully. New company: {api_response.properties.get'company'}"
        printf"Error updating contact: {e}"

# Example usage assuming you have a contact_id:
# update_hubspot_contact"YOUR_CONTACT_ID", "Awesome New Company Inc."

 Handling Associations Contact to Company

Associations link different CRM objects together e.g., a contact to a company, or a deal to a contact. This is crucial for maintaining relationships in your CRM.

from hubspot.crm.associations import ApiException
from hubspot.crm.associations.v4.models import AssociationSpec

def associate_contact_to_companycontact_id, company_id:
       # Define the association type 0-4 represents contact to company
       # HubSpot's API v4 for associations often requires specific AssociationSpec models.
       # Refer to HubSpot's official documentation for the exact association types.
        
       # In this simplified example, we're using a direct v3 association call
       # For v4, you'd typically use the associations_api for specific object types and `AssociationSpec`
       # Example using `crm.associations.v4.basic_api.create` would involve
       # passing `association_category` and `association_type_id` e.g., "0-2" for contact to company
        
       # This example uses the more general v3 endpoint which allows for associating
       # objects during creation or through direct association endpoints.
        
       # For direct association, you'd often use a POST request to an endpoint like:
       # /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}
        
       # The Python client library might abstract this into a simpler call.
       # Let's assume a direct association method for simplicity based on `hubspot-api-python` client capabilities.
        
       # A more direct way with the client library for v3 is often to update one object's associations
       # or associate during creation.
        
       # For an explicit association between two existing objects:
        api_client.crm.associations.v4.basic_api.create
            object_type='contact',
            object_id=contact_id,
            to_object_type='company',
            to_object_id=company_id,
            association_spec=
                AssociationSpec
                   association_category='HUBSPOT_DEFINED', # Standard HubSpot association
                   association_type_id=2 # ID for contact-to-company association
                
            
        printf"Contact {contact_id} associated with Company {company_id} successfully."
        printf"Error associating contact and company: {e}"

# Example usage replace with actual IDs:
# associate_contact_to_company"YOUR_CONTACT_ID", "YOUR_COMPANY_ID"
 Note: The exact `association_type_id` can vary. always check the HubSpot documentation for the specific association you're trying to create.

# C# Example

While the provided search results leaned more towards Python and PHP, the HubSpot API is RESTful, meaning you can interact with it from any language that can make HTTP requests. For C#, you'd typically use `HttpClient` to make these calls. Let's look at an example for submitting form data, which effectively creates or updates contacts.


You'll need a .NET project and the `System.Net.Http` namespace.
```csharp
using System.
using System.Net.Http.
using System.Text.
using System.Threading.Tasks.
using Newtonsoft.Json. // You might need to install Newtonsoft.Json via NuGet

public class HubSpotFormSubmission
{
    private readonly HttpClient _httpClient.
    private readonly string _hubspotPortalId.
    private readonly string _hubspotFormGuid.
    private readonly string _privateAppToken. // Use Private App Token here

    public HubSpotFormSubmissionstring portalId, string formGuid, string privateAppToken
    {
        _httpClient = new HttpClient.
        _hubspotPortalId = portalId.
        _hubspotFormGuid = formGuid.
        _privateAppToken = privateAppToken. // Store securely, not hardcoded!
        _httpClient.DefaultRequestHeaders.Add"Authorization", $"Bearer {_privateAppToken}".
    }

    public async Task<string> SubmitFormstring firstName, string lastName, string email
        // HubSpot's forms API endpoint for submissions
        // The endpoint is typically: https://api.hsforms.com/submissions/v3/integration/submit/:portal_id/:form_guid 
        string formApiUrl = $"https://api.hsforms.com/submissions/v3/integration/submit/{_hubspotPortalId}/{_hubspotFormGuid}".

        var submissionData = new
        {
            fields = new
            {
                new { name = "firstname", value = firstName },
                new { name = "lastname", value = lastName },
                new { name = "email", value = email }
            },
            context = new {
                pageUri = "https://yourwebsite.com/form-page",
                pageName = "My Custom Form"
            // You can add 'legalConsentOptions' if you have GDPR/CCPA fields
        }.

        string jsonPayload = JsonConvert.SerializeObjectsubmissionData.
        var content = new StringContentjsonPayload, Encoding.UTF8, "application/json".

        try
            HttpResponseMessage response = await _httpClient.PostAsyncformApiUrl, content.
            response.EnsureSuccessStatusCode. // Throws an exception if not a 2xx status code

            string responseBody = await response.Content.ReadAsStringAsync.
            Console.WriteLine"Form submitted successfully!".
            Console.WriteLineresponseBody.
            return responseBody.
        catch HttpRequestException e
            Console.WriteLine$"Error submitting form: {e.Message}".
            if e.Data.Contains"HttpResponseMessage"
                HttpResponseMessage errorResponse = HttpResponseMessagee.Data.
                Console.WriteLine$"Status Code: {errorResponse.StatusCode}".
                Console.WriteLine$"Response Body: {await errorResponse.Content.ReadAsStringAsync}".
            return null.

    // Example usage:
    public static async Task Mainstring args
        // Replace with your actual Portal ID, Form GUID, and Private App Access Token
        string portalId = "YOUR_PORTAL_ID".
        string formGuid = "YOUR_FORM_GUID".
        string privateAppToken = "YOUR_PRIVATE_APP_ACCESS_TOKEN". // Get this from your Private App settings

        HubSpotFormSubmission submitter = new HubSpotFormSubmissionportalId, formGuid, privateAppToken.
        await submitter.SubmitForm"John", "Doe", "[email protected]".
}

# PHP Examples

PHP is also a very common language for web applications, and interacting with the HubSpot API from PHP is straightforward, especially with the official PHP client library.


You'll need PHP and Composer to install the `hubspot/api-client`.
composer require hubspot/api-client
Then, you can create the client instance. Just like with Python, keep your access token secure.
```php
<?php
require_once __DIR__ . '/vendor/autoload.php'.

use HubSpot\Client\Crm\Contacts\ApiException.
use HubSpot\Client\Crm\Contacts\Model\SimplePublicObjectInputForCreate.
use HubSpot\Client\Crm\Associations\V4\Model\AssociationSpec.
use HubSpot\Client\Crm\Associations\ApiException as AssociationsApiException.

// Best practice: Store your access token in an environment variable or secure config
$accessToken = getenv'HUBSPOT_PRIVATE_APP_TOKEN'.

if !$accessToken {
    die"Error: HUBSPOT_PRIVATE_APP_TOKEN environment variable not set.\n".

$hubspot = \HubSpot\Factory::createWithAccessToken$accessToken.
?>



// ... setup code from above

function createHubspotContact$hubspotClient, $email, $firstname, $lastname {
    try {
        $contactProperties = 
            'email' => $email,
            'firstname' => $firstname,
            'lastname' => $lastname,
        .
        $simplePublicObjectInput = new SimplePublicObjectInputForCreate.
        
        $apiResponse = $hubspotClient->crm->contacts->basicApi->create$simplePublicObjectInput.
        echo "Contact created successfully: " . $apiResponse->getId . "\n".
        return $apiResponse.
    } catch ApiException $e {
        echo "Error creating contact: " . $e->getMessage . "\n".
        return null.

// Example usage:
$newContact = createHubspotContact$hubspot, "[email protected]", "Bob", "Smith".



Associating objects in PHP is similar to Python, using the client library's association methods.


function associateContactToCompany$hubspotClient, $contactId, $companyId {
        // Define the association type. 'HUBSPOT_DEFINED' is for standard associations.
        // The type ID '2' typically represents a contact-to-company association.
        $associationSpec = new AssociationSpec
            'association_category' => 'HUBSPOT_DEFINED',
            'association_type_id' => 2, // Contact to Company
        .

        $hubspotClient->crm->associations->v4->basicApi->create
            'contacts', // From object type
            $contactId,   // From object ID
            'companies',  // To object type
            $companyId,   // To object ID
             // Array of association specs
        .
        echo "Contact {$contactId} associated with Company {$companyId} successfully.\n".
    } catch AssociationsApiException $e {
        echo "Error associating contact and company: " . $e->getMessage . "\n".

// Example usage replace with actual IDs:
// if $newContact {
//     // Assuming you have a company ID already
//     $companyId = "YOUR_COMPANY_ID". 
//     associateContactToCompany$hubspot, $newContact->getId, $companyId.
// }


 Beyond the Basics: More Powerful Integrations

The HubSpot API goes way beyond just contacts. Let's touch on a few other key areas.

# HubSpot Form API Example Submitting External Forms

Sometimes you have forms on your website that aren't native HubSpot forms, but you still want those submissions to land in your HubSpot CRM. This is a perfect use case for the HubSpot Form API. You can take the data from your custom form and programmatically submit it to a HubSpot form endpoint. This will create or update contacts in HubSpot, just as if they filled out a native HubSpot form.

You'll need your HubSpot `portalId` and the `formGuid` ID of the specific HubSpot form you want to submit data to. The endpoint looks like this: `https://api.hsforms.com/submissions/v3/integration/submit/:portal_id/:form_guid`.

import requests
import json

def submit_external_form_to_hubspotportal_id, form_guid, data:
    url = f"https://api.hsforms.com/submissions/v3/integration/submit/{portal_id}/{form_guid}"
    
    headers = {
        "Content-Type": "application/json"
    
   # The 'data' dictionary should contain 'fields' and optionally 'context' and 'legalConsentOptions'
   # Example data structure:
   # {
   #   "fields": 
   #     { "name": "firstname", "value": "John" },
   #     { "name": "lastname", "value": "Doe" },
   #     { "name": "email", "value": "[email protected]" }
   #   ,
   #   "context": {
   #     "pageUri": "https://www.example.com/pricing",
   #     "pageName": "Pricing Page"
   #   }
   # }

        response = requests.posturl, headers=headers, data=json.dumpsdata
       response.raise_for_status # Raise an exception for bad status codes
        print"Form submission successful!"
        printresponse.json
        return response.json
    except requests.exceptions.RequestException as e:
        printf"Error submitting form: {e}"
        if e.response:
            printf"Response status: {e.response.status_code}"
            printf"Response body: {e.response.text}"

# my_portal_id = "YOUR_PORTAL_ID"
# my_form_guid = "YOUR_FORM_GUID"
# form_data = {
#     "fields": 
#         { "name": "email", "value": "[email protected]" },
#         { "name": "firstname", "value": "External" },
#         { "name": "lastname", "value": "User" }
#     ,
#     "context": {
#         "pageUri": "https://myawesomewebsite.com/contact-us",
#         "pageName": "Custom Contact Form"
#     }
# }
# submit_external_form_to_hubspotmy_portal_id, my_form_guid, form_data

# HubSpot File Upload API Example

Need to upload documents, images, or other files directly to your HubSpot file manager or attach them to CRM records? The HubSpot File Upload API is what you'll use. This is particularly useful if your company builds its website using HubSpot's CMS and needs to manage assets programmatically.

Uploading files can be a bit tricky due to specific requirements for encoding and headers, but it's definitely doable. You'll make a `POST` request to the `/filemanager/api/v3/files/upload` endpoint, typically using `multipart/form-data`.


def upload_file_to_hubspotfile_path, folder_path, access_token:
    upload_url = "https://api.hubapi.com/filemanager/api/v3/files/upload"

    file_options = {
       'access': 'PUBLIC_NOT_INDEXABLE', # Options can be PUBLIC_NOT_INDEXABLE, PRIVATE, etc. 
       'overwrite': False, # Set to True to overwrite existing files with the same name 
       'duplicateValidationStrategy': 'NONE', # Or 'NONE', 'ENTIRE_PORTAL', 'EXACT_FOLDER' 
       'duplicateValidationScope': 'EXACT_FOLDER' # Applies if strategy is not NONE 

    files_data = {
        'file': os.path.basenamefile_path, openfile_path, 'rb', 'application/octet-stream',
        'options': None, json.dumpsfile_options, 'application/json',
        'folderPath': None, folder_path, 'text/plain'

        'Authorization': f'Bearer {access_token}'

        response = requests.postupload_url, files=files_data, headers=headers
        response.raise_for_status
        printf"File '{os.path.basenamefile_path}' uploaded successfully!"
        printf"Error uploading file: {e}"

# my_file_path = "path/to/your/document.pdf"
# my_folder_path = "/My Uploaded Files" # Folder path in HubSpot file manager
# my_access_token = os.environ.get"HUBSPOT_PRIVATE_APP_TOKEN"
# if my_access_token:
#     upload_file_to_hubspotmy_file_path, my_folder_path, my_access_token
 After uploading, you can then use the file ID to attach it to a deal or other engagement via the engagements API.

# HubSpot Search API Example Searching Contacts by Email

Need to find a specific contact or a group of contacts based on certain criteria? The HubSpot CRM objects have search capabilities. While `get_all` can fetch contacts, the search API allows for more targeted queries. For instance, searching for a contact by email is a very common task.

from hubspot.crm.contacts import PublicObjectSearchRequest
from hubspot.crm.contacts import ApiException as ContactsApiException

def search_contact_by_emailemail, access_token:
    api_client = hubspot.Client.createaccess_token=access_token
    
    public_object_search_request = PublicObjectSearchRequest
        filter_groups=
                "filters": 
                    {
                        "property_name": "email",
                       "operator": "EQ", # Equal to
                        "value": email
                    }
                
        ,
       properties=, # Properties you want to retrieve
       limit=1 # We expect only one contact for a unique email
    

        search_results = api_client.crm.contacts.search_api.do_search
            public_object_search_request=public_object_search_request
        if search_results.results:
            contact = search_results.results
            printf"Found contact: ID: {contact.id}, Name: {contact.properties.get'firstname'} {contact.properties.get'lastname'}, Email: {contact.properties.get'email'}"
            return contact
        else:
            printf"No contact found with email: {email}"
            return None
    except ContactsApiException as e:
        printf"Error searching for contact: {e}"

# search_email = "[email protected]"
# if HUBSPOT_ACCESS_TOKEN:
#     found_contact = search_contact_by_emailsearch_email, HUBSPOT_ACCESS_TOKEN
 This `do_search` method is available for other objects like companies and deals too, letting you build flexible search functionalities.

 Important Considerations & Best Practices

Working with any API means keeping a few things in mind to ensure your integrations are robust, secure, and respectful of the platform's limits.

# API Rate Limits

HubSpot, like most API providers, has rate limits to prevent abuse and ensure fair usage for everyone. For instance, HubSpot's threshold typically allows up to 100 requests per 10 seconds. If you make too many requests in a short period, your requests will start getting rejected with a `429 Too Many Requests` error.

Best Practice:
*   Implement Backoff/Retry Logic: If you hit a `429` error, your application should wait for a specified period before retrying the request. Don't just hammer the API with retries!
*   Batch Requests: When possible, use batch endpoints to update or create multiple records in a single API call e.g., `crm/v3/objects/contacts/batch/upsert`. This significantly reduces the number of API calls you make.

# Error Handling

Things can and will go wrong. Network issues, incorrect data, or permission problems can all lead to API errors.

*   Check Status Codes: Always check the HTTP status code of the API response. A `200 OK` means success, but `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, or `500 Internal Server Error` tell you something went wrong.
*   Parse Error Responses: HubSpot's API returns JSON error messages that provide helpful details. Parse these messages and log them so you can understand and fix issues.
*   Graceful Degradation: Your application should be able to handle errors gracefully without crashing or providing a poor user experience.

# Security Keep Those Tokens Safe!

We've already talked about the shift from API keys to private app access tokens, but it bears repeating: security is paramount.

*   Environment Variables: Never hardcode sensitive credentials like access tokens directly in your code. Use environment variables as shown in the examples or secure configuration management tools.
*   Least Privilege: Grant your private apps only the specific scopes they need. Don't give full access if it's not required.
*   Regular Audits: Periodically review your private apps and their granted permissions. Rotate tokens if you suspect a compromise.

# API Versioning V3 and Date-based

HubSpot, like many platforms, updates its APIs. The current stable version is v3, which offers improved consistency and a more predictable, resource-oriented approach compared to older versions.

HubSpot is also rolling out date-based versioned APIs. Instead of `v3`, you might see versions like `2025-09`. This calendar-based versioning helps you know you're using the most up-to-date endpoints and lets you plan for future updates more effectively. If you're starting a new project, definitely stick with v3 or the new date-based versions.

*   Consult the Changelog: Keep an eye on the HubSpot Developer Changelog. It's your source for new functionality, announcements about sunsets, and deprecations like the old API keys.
*   Use Latest Versions: Always use the latest API version for new integrations.

# Leveraging the Developer Changelog

Consider the developer changelog your daily newspaper for HubSpot API news. HubSpot is constantly enhancing its API offerings, from expanding the Commerce Hub Payments API to supporting more CRUD operations for payments, to new features for the v4 Automation API. Staying current with these updates means you can leverage the newest features and avoid issues with deprecated endpoints.

---

 Frequently Asked Questions

# What is the main difference between HubSpot API keys and Private Apps?

The old HubSpot API keys provided full, unrestricted access to your entire HubSpot portal, making them a security risk if compromised. Private Apps, on the other hand, generate an access token that you can scope with very specific permissions e.g., only read contacts, or only create deals. This "least privilege" approach significantly enhances security by limiting what an app can do even if its token is exposed. HubSpot deprecated API keys in November 2022, so Private Apps are now the recommended authentication method.

# How do I get an access token for a HubSpot Private App?

You create a Private App within your HubSpot account settings. Go to `Settings` > `Integrations` > `Private apps`. After naming your app, you'll specify the `scopes` permissions it needs, such as `crm.objects.contacts.read` to read contacts. Once created, navigate to the app's `Auth` tab, click `Show token`, and copy your access token. Remember to keep this token secure and never hardcode it directly into your public codebase.

# Can I use the HubSpot API to submit data from an external form?

Absolutely! This is a common use case for the HubSpot Form API. You can collect data from any form on your website and programmatically send it to a specific HubSpot form endpoint using a `POST` request. This makes the submission appear as if it came from a native HubSpot form, creating or updating contacts and triggering any associated workflows within HubSpot. You'll need your HubSpot `portalId` and the `formGuid` for this.

# What programming languages are commonly used for HubSpot API integrations?

The HubSpot API is built on REST conventions, meaning you can interact with it using any language capable of making HTTP requests. However, Python, PHP, JavaScript Node.js, and C# are among the most popular. HubSpot provides official client libraries for Python and PHP, which simplify interactions by handling authentication, request formatting, and response parsing.

# How do I handle file uploads to HubSpot via the API?

To upload files, you'll use the HubSpot File Upload API. This involves making a `POST` request to the `/filemanager/api/v3/files/upload` endpoint with a `multipart/form-data` payload. You'll include the file content, file name, and specify options like the target folder and visibility. Once uploaded, you'll receive a file ID, which can then be used to attach the file to CRM records like deals or contacts through the engagements API.

# What are HubSpot API rate limits, and how should I manage them?

HubSpot API rate limits are restrictions on how many requests you can make within a certain timeframe e.g., 100 requests per 10 seconds. These limits prevent system overload and ensure fair usage. If you exceed them, you'll get a `429 Too Many Requests` error. To manage this, implement backoff and retry logic in your code, which means your application waits for a short period before retrying a failed request. Also, utilize batch endpoints whenever possible to send multiple record updates or creations in a single API call, reducing your overall request count.

# What is HubSpot's current API versioning strategy?

HubSpot's API is primarily in v3, which introduced more consistent and standardized approaches. They are also progressively rolling out date-based versioning e.g., `2025-09` for various APIs, which will eventually replace the numerical versions. This date-based system aims to provide more predictable update cycles. For new development, it's always recommended to use the latest available version, and keep an eye on the HubSpot Developer Changelog for announcements and deprecations.

HubSpot’s Freemium Magic: What’s Truly Free?