Clearbit API Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with the Clearbit API involves a series of steps designed to get you from account creation to your first successful data enrichment request. This guide focuses on the practical aspects of setting up your environment and making a basic API call. The Clearbit API primarily offers data enrichment services through various endpoints, allowing developers to retrieve company and person data based on email addresses, domain names, or IP addresses. The process generally follows these stages:

1. Account Creation: Registering for a Clearbit account, which provides access to the dashboard and API key management.
2. API Key Retrieval: Locating and securing your unique API key from the Clearbit dashboard. This key authenticates your requests.
3. Environment Setup: Choosing your preferred programming language or tool for making HTTP requests.
4. First API Call: Constructing and executing a basic request to an enrichment endpoint, such as the Person or Company API.
5. Response Handling: Understanding the structure of the API response and how to extract relevant data.

Clearbit provides SDKs for several programming languages, including JavaScript, Ruby, Python, Node.js, PHP, and Go, which can simplify the integration process by abstracting HTTP request details and handling authentication. For initial testing, direct HTTP requests using tools like curl or a simple HTTP client library are also effective.

The following table provides a quick reference for the initial setup steps:

Create an account and get keys

To begin using the Clearbit API, you must first create an account. Navigate to the Clearbit website and follow the signup process. Clearbit offers a free tier that allows you to start with a certain number of API calls per month, making it accessible for initial testing and development before committing to a paid plan. During the signup, you may be asked for basic company or personal information.

Once your account is created and you have logged into your Clearbit dashboard, your API key will be available. This key is a unique string that authenticates your requests to the Clearbit API. It is crucial to keep your API key secure, as unauthorized access could lead to misuse of your account and consumption of your API credits. Clearbit's authentication documentation details how to manage and use your API keys.

Typically, API keys are found in a section of the dashboard labeled "API Keys" or "Settings". The key will be a long, alphanumeric string. When making API requests, you will include this key in the request header or as a query parameter, depending on the specific Clearbit endpoint and the method described in their documentation. For example, many RESTful APIs use an Authorization header with a Bearer token or a custom header like X-Clearbit-API-Key. Always refer to the official Clearbit API reference for the exact method of including your API key.

Your first request

After obtaining your API key, you can make your first request. A common starting point is the Person Enrichment API, which can provide data about an individual based on their email address. For this example, we will use curl, a command-line tool for making HTTP requests, as it is language-agnostic and widely available. Replace YOUR_API_KEY with your actual Clearbit API key and [email protected] with a valid email address for testing.

curl "https://person.clearbit.com/v2/people/[email protected]" \
  -u YOUR_API_KEY:

In this curl command:

• https://person.clearbit.com/v2/people/find is the endpoint for finding person data.
• [email protected] is a query parameter specifying the email address to look up.
• -u YOUR_API_KEY: sends your API key as a username for HTTP Basic Authentication. The colon after your key indicates an empty password, which is the standard practice for Clearbit's API key authentication.

A successful response will return a JSON object containing various data points related to the person associated with the email address. This might include their name, company, social media profiles, and more, if the data is available. An example of a successful (abbreviated) JSON response might look like this:

{
  "id": "person_xxxxxxxxxxxxxx",
  "name": {
    "fullName": "John Doe",
    "givenName": "John",
    "familyName": "Doe"
  },
  "email": "[email protected]",
  "company": {
    "name": "Example Corp",
    "domain": "example.com"
  },
  "employment": {
    "name": "Example Corp",
    "title": "Software Engineer"
  },
  "indexedAt": "2023-01-01T12:00:00.000Z"
  // ... more data fields
}

If the API cannot find data for the provided email, or if there's an issue with your API key, you might receive an error response. Common error codes include 401 Unauthorized for invalid API keys or 404 Not Found if no data matches the query. The Clearbit API error handling guide provides more details on interpreting error codes.

For developers using specific programming languages, Clearbit offers official SDKs that streamline this process. For instance, in Python, you might use the requests library or the official Clearbit Python SDK:

import clearbit

clearbit.key = 'YOUR_API_KEY'

person = clearbit.Person.find(email='[email protected]')

if person:
    print(person)
else:
    print("Person not found or an error occurred.")

This Python example demonstrates how the SDK simplifies authentication and request construction, returning a Python object that maps directly to the JSON response. Similar SDKs are available for other languages, as detailed in the Clearbit client libraries documentation.

Common next steps

After successfully making your first API call, consider these next steps to further integrate Clearbit into your applications:

1. Explore Other Endpoints: The Clearbit API offers several other powerful endpoints. The API reference details services like the Company API (enriching company data from a domain), Reveal API (identifying companies from IP addresses), and Prospector API (finding contacts at specific companies). Understanding these will help you leverage the full suite of Clearbit's data enrichment capabilities.
2. Integrate SDKs: While curl is useful for testing, integrating one of Clearbit's official SDKs (JavaScript, Ruby, Python, Node.js, PHP, Go) can simplify development. SDKs handle authentication, request formatting, and response parsing, allowing you to focus on your application logic. You can find links to the specific SDKs within the Clearbit client libraries documentation.
3. Error Handling and Rate Limits: Implement robust error handling in your application to gracefully manage API failures, such as rate limit exceeded (HTTP 429) or data not found (HTTP 404). Clearbit's rate limiting policies are important to understand to avoid service interruptions.
4. Data Storage and Caching: For frequently requested data, consider implementing caching mechanisms to reduce API calls and improve performance. Be mindful of data freshness requirements and Clearbit's terms of service regarding data storage.
5. Security Best Practices: Always protect your API key. Avoid hardcoding it directly into your application code. Instead, use environment variables or a secure configuration management system. For web applications, ensure API calls are made from your backend to prevent exposing your key to client-side code. The MDN Web Docs on the Authorization header provide general guidance on secure API authentication.
6. Monitor Usage: Utilize the Clearbit dashboard to monitor your API usage, track credits, and understand your consumption patterns. This helps in managing costs and scaling your integration effectively.
7. Explore Webhooks: For certain use cases, Clearbit may support webhooks to provide real-time notifications about data changes or enrichment completion, reducing the need for polling. Check the Clearbit documentation for specific webhook support.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and common problems:

• Invalid API Key (HTTP 401 Unauthorized):
  • Check your key: Ensure you have copied the API key correctly from your Clearbit dashboard. Even a single character mismatch will cause authentication to fail.
  • Authentication method: Verify that you are passing the API key using the correct authentication method (e.g., HTTP Basic Auth with the key as the username and an empty password, or a specific header). Refer to the Clearbit authentication guide.
  • Key expiration/revocation: Confirm your API key has not expired or been revoked. You can check its status in your Clearbit dashboard.
• Endpoint Not Found (HTTP 404 Not Found):
  • URL accuracy: Double-check the endpoint URL for typos. Ensure it matches the one specified in the Clearbit API reference.
  • Parameter correctness: Verify that query parameters (e.g., email, domain, ip) are correctly spelled and formatted.
• Rate Limit Exceeded (HTTP 429 Too Many Requests):
  • Usage limits: If you are on a free tier or have specific plan limits, you might hit a rate limit quickly during testing. Wait a short period and retry, or review your plan's rate limits.
  • Bursting: Avoid sending too many requests in a very short time. Implement delays or exponential backoff in your retry logic.
• No Data Returned (Successful HTTP 200, but empty/null data):
  • Data availability: Clearbit's database may not have information for every query. For example, a newly registered domain or a very obscure email address might not yield results. Try with a well-known email or domain (e.g., google.com) to confirm the API is working.
  • Query specificity: Ensure your query parameters are specific enough. For example, using a generic email like [email protected] might not return a specific person.
• Network Issues:
  • Connectivity: Ensure your development environment has stable internet connectivity and no firewalls are blocking outbound requests to Clearbit's API domains.
  • DNS resolution: Verify that DNS resolution is working correctly for person.clearbit.com or other Clearbit API domains.
• SDK Specific Issues:
  • Installation: Confirm the SDK is correctly installed and imported into your project.
  • Version compatibility: Ensure you are using a compatible version of the SDK with your programming language and the Clearbit API.
  • Syntax: Double-check the syntax for using the SDK methods, as documented in the Clearbit client libraries.

When seeking support, provide Clearbit's support team with the exact request you made (excluding your API key), the full response (including headers), and any error messages received. This information helps in diagnosing the problem efficiently.