HubSpot API Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with the HubSpot API involves a sequence of steps designed to ensure secure and efficient access to your HubSpot data. This guide focuses on the initial process: setting up your HubSpot account, generating the necessary authentication credentials, and executing a foundational API request. The HubSpot API supports various integrations, from automating contact management to syncing marketing data, and offers multiple SDKs to facilitate development in languages like Node.js, Python, and Java HubSpot developer documentation.

Before making any API calls, developers must have an active HubSpot account and understand the authentication methods available. HubSpot primarily supports API key-based authentication for private apps and OAuth 2.0 for public integrations HubSpot API overview. For initial testing and private integrations, an API key is often the quickest path to a working request.

This overview table summarizes the core steps for a rapid start:

Create an account and get keys

To begin using the HubSpot API, you need a HubSpot account. If you do not have one, you can sign up for a free account that includes access to CRM tools and starter functionalities across various hubs like Marketing, Sales, and Service HubSpot CRM pricing. A free account is sufficient for generating API keys and testing basic API functionalities. Once logged in, navigate to the developer portal to manage your applications and API access.

Account Creation and Login

1. Go to the HubSpot website and click 'Get started free' or 'Log in' if you already have an account.
2. Follow the prompts to create your account, which typically involves providing an email address and setting up your company profile.
3. Once your account is active, log in to your HubSpot portal.

Generating an API Key for Private Apps

HubSpot recommends using private apps for internal integrations specific to a single HubSpot account. Private apps provide an API key that authenticates requests. For public applications or integrations that serve multiple HubSpot accounts, OAuth 2.0 is the recommended method HubSpot API authentication guide. For this getting started guide, we will focus on generating an API key for a private app.

1. From your HubSpot account, click the gear icon in the top navigation bar to go to Settings.
2. In the left sidebar menu, navigate to Integrations > Private apps.
3. Click Create a private app.
4. Provide an App name and an optional App description. These are for your internal reference.
5. Click the Scopes tab. Here, you define the permissions your private app will have. For a basic test, select a scope like crm.objects.contacts.read to allow reading contact data HubSpot Contacts API documentation. Carefully choose only the necessary scopes to adhere to the principle of least privilege.
6. Click Create app.
7. After creation, you will see a screen displaying your Access token (this is your API key). Copy this token immediately and store it securely. HubSpot will only show this token once. If lost, you will need to generate a new one.

This access token will be used in the Authorization header of your API requests.

Your first request

With your API key in hand, you are ready to make your first authenticated request to the HubSpot API. We will use a simple GET request to retrieve a list of contacts, which falls under the crm.objects.contacts.read scope you likely enabled. This example uses curl, a common command-line tool, but you can adapt it to any HTTP client or one of HubSpot's official SDKs HubSpot developer resources.

Prerequisites

• Your HubSpot API key (Access token).
• A terminal with curl installed. (curl is typically pre-installed on macOS and Linux. For Windows, you might need to install it or use Windows Subsystem for Linux.)

Example: Get a list of contacts

This request fetches a list of contacts from your HubSpot portal. Replace YOUR_HUBSPOT_API_KEY with the actual access token you generated.

curl --request GET \
  --url https://api.hubapi.com/crm/v3/objects/contacts \
  --header 'Authorization: Bearer YOUR_HUBSPOT_API_KEY' \
  --header 'Content-Type: application/json'

Explanation of the request:

• --request GET: Specifies the HTTP method as GET, used for retrieving data.
• --url https://api.hubapi.com/crm/v3/objects/contacts: This is the endpoint for the Contacts API, version 3.
• --header 'Authorization: Bearer YOUR_HUBSPOT_API_KEY': This header contains your API key. The Bearer prefix is standard for token-based authentication, as defined in OAuth 2.0 Bearer Token Usage RFC 6750.
• --header 'Content-Type: application/json': While not strictly necessary for a GET request, it's good practice to specify the expected content type, informing the server that you expect a JSON response.

Expected Response

A successful response (HTTP status 200 OK) will return a JSON object containing a list of contacts. If you have no contacts, the results array will be empty. If you do, you'll see contact properties like firstname, lastname, and email.

{
  "results": [
    {
      "id": "12345",
      "properties": {
        "createdate": "2023-01-01T12:00:00.000Z",
        "email": "[email protected]",
        "firstname": "Jane",
        "lastmodifieddate": "2023-01-01T12:00:00.000Z",
        "lastname": "Doe"
      },
      "createdAt": "2023-01-01T12:00:00.000Z",
      "updatedAt": "2023-01-01T12:00:00.000Z",
      "archived": false
    }
    // ... more contacts
  ],
  "paging": {
    "next": {
      "link": "https://api.hubapi.com/crm/v3/objects/contacts?after=50",
      "after": "50"
    }
  }
}

Common next steps

After successfully making your first API call, consider these next steps to deepen your integration with HubSpot:

• Explore More Endpoints: Review the HubSpot API Reference to understand the full range of available endpoints for contacts, companies, deals, tickets, and other HubSpot objects.
• Use an SDK: For more complex applications, consider using one of HubSpot's official SDKs (Node.js, Python, Ruby, Java, PHP, .NET) to simplify API interaction and handle authentication, request building, and response parsing HubSpot SDKs.
• Implement OAuth 2.0: If you are building a public application or an integration that will serve multiple HubSpot accounts, transition from API keys to OAuth 2.0 for secure and scalable authentication OAuth 2.0 specification.
• Webhooks: Set up webhooks to receive real-time notifications about events in HubSpot, such as new contact creation or property updates, rather than constantly polling the API HubSpot Webhooks documentation.
• Error Handling: Implement robust error handling in your application to gracefully manage various API responses, including rate limits, authentication failures, and validation errors.
• Rate Limits: Understand and respect HubSpot's API rate limits to prevent your application from being throttled HubSpot API rate limits.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check API Key: Ensure your API key (Access token) is correctly copied and included in the Authorization: Bearer YOUR_HUBSPOT_API_KEY header. Even a single character error can lead to authentication failure.
• Verify Scopes: Double-check that the private app associated with your API key has the necessary scopes enabled for the endpoint you are trying to access. For the contacts endpoint (/crm/v3/objects/contacts), you need at least crm.objects.contacts.read. You can review and update scopes in your private app settings within HubSpot.
• Endpoint URL: Confirm that the API endpoint URL is accurate. HubSpot uses versioned APIs (e.g., /v3/), and incorrect paths will result in 404 Not Found errors.
• HTTP Method: Ensure you are using the correct HTTP method (e.g., GET for retrieval, POST for creation, PUT for updates, DELETE for removal).
• Network Connectivity: Verify your internet connection and ensure no firewalls or proxies are blocking your outbound requests to api.hubapi.com.
• Error Messages: Pay close attention to the error messages returned in the API response. HubSpot's error messages are typically descriptive and can guide you toward the solution. Common status codes include 401 Unauthorized (API key issue), 403 Forbidden (scope issue), 404 Not Found (incorrect URL), and 429 Too Many Requests (rate limit exceeded) HubSpot API error handling guidance.
• HubSpot Developer Forum: If you are still stuck, consult the HubSpot Developer Community for solutions or to post your question.