HubSpot Getting Started: API Access and First Request (2026)

Getting started overview

Integrating with HubSpot's platform involves a sequence of steps designed to secure access and facilitate programmatic interaction with its various services, including CRM, Marketing, Sales, Service, CMS, Operations, and Commerce Hubs. The process typically begins with establishing a HubSpot account, which serves as the foundation for accessing the developer tools and API credentials. Developers can choose between two main authentication methods: API keys for simpler, internal integrations, or OAuth 2.0 for third-party applications and enhanced security. Once authenticated, developers can interact with HubSpot's RESTful APIs to manage data such as contacts, companies, deals, and marketing campaigns. HubSpot provides SDKs in multiple programming languages to streamline this process, abstracting away the complexities of HTTP requests and JSON parsing. Real-time event notifications are supported through webhooks, allowing for reactive application logic based on changes within the HubSpot environment.

The developer experience is supported by extensive API documentation, which includes endpoint specifications, request and response examples, and guides for common use cases. This resource is central to understanding the structure and behavior of the HubSpot API. For developers new to the platform, the primary goal is often to make an initial authenticated call to verify setup and connectivity. Subsequent steps involve exploring specific API endpoints relevant to their integration goals, such as creating or updating contact records, managing marketing lists, or automating sales workflows. Effective troubleshooting resources are available within the documentation and community forums to address common issues related to authentication, request formatting, or rate limiting.

Create an account and get keys

Before making API requests to HubSpot, an active HubSpot account is required. This account provides access to the HubSpot portal, where API keys and OAuth 2.0 applications are managed. HubSpot offers Free Tools that include CRM, Marketing, Sales, Service, CMS, and Operations functionalities, making it possible to begin development without an initial paid subscription.

Account Creation

1. Navigate to the HubSpot homepage.
2. Select a 'Get started free' or similar option to begin the registration process.
3. Follow the prompts to set up a new account, which typically involves providing an email address, creating a password, and answering basic questions about your organization.
4. Once registered, you will gain access to your HubSpot portal.

Obtaining an API Key

For many initial integrations and internal tools, a HubSpot API key provides a direct method of authentication. It is a long-lived token that grants access to your HubSpot data, making it suitable for server-side applications where the key can be securely stored. API keys should be handled with care, as their compromise can lead to unauthorized data access.

1. From your HubSpot portal, navigate to Settings (gear icon).
2. In the left sidebar, go to Integrations > API key.
3. If no API key exists, click Create API key.
4. Copy the generated API key. This key will be used in the hapikey query parameter for authenticated requests, or in the Authorization: Bearer header for newer API versions. Refer to the HubSpot API overview for authentication details.

Setting up OAuth 2.0 (for public or third-party applications)

For applications that interact with multiple HubSpot portals or require more granular permission control, OAuth 2.0 is the recommended authentication method. OAuth 2.0 involves a user authorizing your application to access their HubSpot data on their behalf, without sharing their credentials directly with your application. This is detailed in the HubSpot API documentation on authentication.

1. In your HubSpot portal, go to Settings > Integrations > Private Apps (or Connected Apps for public apps).
2. Click Create a private app.
3. Provide a name and description for your app.
4. Define the necessary scopes, which specify the permissions your application will request (e.g., crm.objects.contacts.read, crm.objects.contacts.write).
5. After creation, you will receive a Client ID and Client Secret. These credentials are used to initiate the OAuth flow.
6. Configure your application's redirect URLs where HubSpot will send the authorization code after user consent.
7. Implement the OAuth 2.0 flow to exchange the authorization code for an access token and refresh token. Access tokens are typically short-lived and used for API calls, while refresh tokens are used to obtain new access tokens without requiring user re-authorization. The OAuth 2.0 specification outlines this process.

Your first request

Making your first API request to HubSpot verifies that your authentication credentials are correct and that your development environment is properly configured. This example uses a simple GET request to retrieve a list of contacts, which is a common starting point for CRM integrations.

Prerequisites

• A HubSpot account with an API key or a valid OAuth 2.0 access token.
• A tool for making HTTP requests (e.g., curl, Postman, or an SDK).

Using an API Key (older method, still supported for some APIs)

The following curl command demonstrates retrieving contacts using an API key in the query parameter. Replace YOUR_HUBSPOT_API_KEY with your actual API key.

curl "https://api.hubapi.com/crm/v3/objects/contacts?hapikey=YOUR_HUBSPOT_API_KEY" \
  -H "Accept: application/json"

This request targets the CRM Contacts API, specifically the /crm/v3/objects/contacts endpoint, to fetch a list of contact objects. The Accept: application/json header indicates that the client prefers a JSON response.

Using an OAuth 2.0 Access Token (recommended for new integrations)

For modern APIs, HubSpot recommends using an access token in the Authorization: Bearer header.

curl "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Replace YOUR_ACCESS_TOKEN with a valid OAuth 2.0 access token obtained through the authorization flow. This method is generally more secure and aligns with RFC 6750 Bearer Token usage.

Expected Response

A successful response will typically return a JSON object containing an array of contact records, along with pagination information. An example of a simplified successful response would look like:

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

If you receive a response with a 401 Unauthorized or 403 Forbidden status code, it indicates an issue with your authentication credentials or permissions. A 400 Bad Request might suggest incorrect URL parameters or request body formatting.

Quick Reference: Getting Started with HubSpot API

Common next steps

After successfully making your first API call, you can proceed with more advanced integrations and development workflows:

• Explore specific APIs: HubSpot offers a wide range of APIs for different Hubs. Review the API documentation for Contacts, Companies, Deals, Marketing Email, Forms, and other objects relevant to your project.
• Utilize SDKs: For faster development and reduced boilerplate code, consider using one of HubSpot's official SDKs available for Python, Java, .NET, Node.js, PHP, and Ruby. SDKs handle authentication, request formatting, and response parsing.
• Implement Webhooks: Set up webhooks to receive real-time notifications about events in your HubSpot portal, such as new contact creation or deal stage changes. This enables reactive and event-driven architectures.
• Error Handling and Rate Limits: Integrate robust error handling into your application, accounting for various HTTP status codes and API-specific error messages. Familiarize yourself with HubSpot's API rate limits to avoid unexpected throttling.
• OAuth 2.0 for Production: For applications intended for public use or those requiring robust security and user consent, fully implement the OAuth 2.0 authentication flow. This ensures secure access delegation and proper scope management.
• Testing and Development Environments: HubSpot provides development accounts and sandboxes, which are crucial for testing integrations without affecting live production data.
• Community Support: Engage with the HubSpot developer community through forums or public resources for assistance and best practices.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting steps:

• Check API Key/Access Token: Ensure your API key is correct and has not expired. If using OAuth 2.0, verify that your access token is still valid and not expired. Generate a new one if necessary.
• Verify Permissions/Scopes: Confirm that the API key or OAuth 2.0 access token has the necessary permissions (scopes) to access the requested resource. For example, to read contacts, you need crm.objects.contacts.read permission. Details on scopes are in the HubSpot API documentation.
• URL and Endpoint Accuracy: Double-check the API endpoint URL for typos. The base URL is typically https://api.hubapi.com, followed by the specific endpoint path (e.g., /crm/v3/objects/contacts).
• HTTP Headers: Ensure that required HTTP headers, such as Accept: application/json and Authorization: Bearer YOUR_ACCESS_TOKEN (for OAuth), are correctly included in your request.
• Rate Limiting: If you are making multiple rapid requests, you might hit HubSpot's rate limits, resulting in 429 Too Many Requests errors. Wait and retry, or implement exponential backoff.
• Error Messages: Pay close attention to the error message in the API response body. HubSpot's API errors are often descriptive and can point directly to the cause of the problem, such as invalid property values or missing required fields.
• Network Connectivity: Confirm that your development environment has unrestricted access to api.hubapi.com. Firewall rules or proxy settings can sometimes block outbound API calls.
• SDK Specific Issues: If using an SDK, ensure it is up-to-date and correctly initialized with your credentials. Consult the SDK-specific documentation for common setup issues.