Clearbit User Management API Guide

Auth method: HTTP Basic Auth (API key as username, empty password)

Setup steps

1. Log in to the Clearbit dashboard (or HubSpot if post-migration).
2. Navigate to API settings to retrieve your secret API key.
3. Pass the key as the HTTP Basic Auth username with an empty password: Authorization: Basic base64(api_key:)

User object field mapping is not yet verified for this app.

Person Enrichment (combined lookup)

• Method: GET
• URL: https://person.clearbit.com/v2/combined/find
• Watch out for: Returns 202 Accepted (async) when data is not yet cached; use webhooks to receive the result.

Request example

GET /v2/combined/find?email=alex@example.com
Authorization: Basic <base64(api_key:)>

Response example

{
  "person": {"name":{"fullName":"Alex Smith"},"email":"alex@example.com"},
  "company": {"name":"Example Corp","domain":"example.com"}
}

Company Enrichment

• Method: GET
• URL: https://company.clearbit.com/v2/companies/find
• Watch out for: 202 responses require webhook configuration to receive async enrichment results.

Request example

GET /v2/companies/find?domain=example.com
Authorization: Basic <base64(api_key:)>

Response example

{
  "id": "027b0d40-016c-40ea-8925-a076fa640992",
  "name": "Example Corp",
  "domain": "example.com",
  "metrics": {"employees": 500}
}

Prospector – Find Employees

• Method: GET
• URL: https://prospector.clearbit.com/v1/people/search
• Watch out for: Prospector is a paid add-on; access depends on legacy plan. May be deprecated post-HubSpot migration.

Request example

GET /v1/people/search?domain=example.com&role=engineering
Authorization: Basic <base64(api_key:)>

Response example

{
  "results": [{"name":{"fullName":"Jane Doe"},"email":"jane@example.com"}],
  "page": 1,
  "total": 42
}

Reveal – Identify Anonymous Visitors

• Method: GET
• URL: https://reveal.clearbit.com/v1/companies/find
• Watch out for: IP-to-company matching; accuracy varies. Not a user-management endpoint.

Request example

GET /v1/companies/find?ip=8.8.8.8
Authorization: Basic <base64(api_key:)>

Response example

{
  "ip": "8.8.8.8",
  "fuzzy": false,
  "company": {"name": "Google","domain": "google.com"}
}

• Rate limits: Rate limits vary by plan and endpoint. Enrichment API historically allowed ~600 requests/minute on paid plans. Exact current limits are not publicly documented post-HubSpot acquisition.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: Clearbit returned X-RateLimit-Limit and X-RateLimit-Remaining headers. Post-HubSpot migration, limits are governed by HubSpot Breeze Intelligence credit quotas (credits expire monthly, no rollover).
• Pagination method: none
• Default page size: 0
• Max page size: 0
• Pagination pointer: Not documented

• Webhooks available: Yes
• Webhook notes: Clearbit supports streaming webhooks for async enrichment responses. When a lookup returns 202, Clearbit POSTs the enriched payload to a configured webhook URL once data is ready.
• Alternative event strategy: Poll the same endpoint after a delay if webhooks are not configured; 202 will eventually resolve to 200 once cached.
• Webhook events: person:enriched, company:enriched, combined:enriched

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• Clearbit has no documented SCIM endpoint for platform user provisioning.
• Post-HubSpot acquisition, user provisioning is managed through HubSpot's own SSO/SCIM capabilities, not Clearbit directly.
• Context data indicates no native SCIM support exists for Clearbit/Breeze Intelligence.

The primary async caveat applies to all enrichment endpoints: a 202 Accepted response means the lookup is queued and data is not yet cached. This is not an error - it indicates the identity graph is performing a fresh resolution.

Your code must explicitly handle this state. Two patterns are supported: (1) configure a webhook URL in the Clearbit dashboard to receive a POST when enrichment completes, or (2) use the streaming API subdomain (`person-stream.

clearbit. com`) to hold the connection open for up to 60 seconds rather than receiving a 202.

For webhook delivery, Clearbit passes an X-Request-Signature header for payload verification and retries failed deliveries up to five times with exponential backoff. If your endpoint returns anything other than HTTP 200, the retry cycle begins. The webhook_id parameter can be passed at request time to correlate async responses back to originating requests.

The Prospector endpoint (prospector.clearbit.com/v1/people/search) and the Reveal IP-to-company endpoint (reveal.clearbit.com/v1/companies/find) carry additional caveats: Prospector is a paid add-on that may be deprecated or restricted for new Breeze Intelligence customers, and Reveal's IP resolution is probabilistic - responses with fuzzy: true indicate lower confidence, and residential IPs rarely resolve to a company.

Enrich a lead's email on form submission

1. Capture email from web form.
2. POST or GET to https://person.clearbit.com/v2/combined/find?email={email} with Basic Auth.
3. If 200: parse person and company fields and write to CRM.
4. If 202: receive enriched payload via configured webhook URL and process asynchronously.

Watch out for: 202 is common for first-time lookups. Without a webhook, you must poll and handle eventual consistency.

Identify anonymous website visitor by IP

1. Capture visitor IP server-side.
2. GET https://reveal.clearbit.com/v1/companies/find?ip={ip} with Basic Auth.
3. If company is returned, use domain/name to personalize content or route to sales.

Watch out for: IP resolution is probabilistic; fuzzy=true in the response indicates lower confidence. Residential IPs rarely resolve.

Prospect employees at a target account

1. Identify target company domain.
2. GET https://prospector.clearbit.com/v1/people/search?domain={domain}&role=marketing with Basic Auth.
3. Paginate using page param to retrieve all results (max page size varies by plan).
4. Export emails/names to outreach tool.

Watch out for: Prospector is a paid add-on and may be unavailable or deprecated for new HubSpot/Breeze Intelligence customers. Verify access before building workflows.

The most common integration mistake is treating a 202 as a terminal failure or ignoring it entirely. Without explicit handling, first-time lookups against uncached identities in the identity graph will silently drop data - your pipeline receives no enrichment and no error signal.

Build webhook receipt or streaming fallback into every enrichment flow before going to production.

A second trap is credit accounting. Under Breeze Intelligence, 1 enrichment = 10 HubSpot credits, and credits expire monthly with no rollover.

Pipelines that trigger enrichment across multiple workflows simultaneously - form submissions, CRM record updates, and list uploads running in parallel - can exhaust the monthly credit pool faster than expected, triggering automatic tier upgrades and unplanned billing. There is no per-API-call credit reservation or pre-flight check available.

Finally, the absence of a SCIM endpoint is a hard architectural constraint. User provisioning for the Breeze Intelligence platform cannot be automated via the Clearbit API. Any identity lifecycle automation must go through HubSpot's own SSO/SCIM capabilities, which are gated behind the Enterprise tier.