Laravel Clearbit Laravel Package

Getting Started

1. composer require clearbit/laravel-clearbit (verify the vendor name against the README — this is a thin HTTP client wrapper, so the package name tells you little about scope).
2. Publish the config: php artisan vendor:publish --tag=clearbit-config. You get a single config/clearbit.php holding the API key plus, typically, per-endpoint base URLs and a timeout.
3. Add CLEARBIT_API_KEY=sk_... to .env and to every environment you actually deploy. The package auto-registers its service provider; there's no manual providers entry unless you're on an old skeleton.
4. Look here first, in this order: the config file (tells you what's tunable and what the default base URLs are), the facade's docblock/@method annotations (fastest way to see the whole API surface), then the README's example blocks. The underlying client class is usually a handful of public methods, so reading it end-to-end takes five minutes and beats guessing at return shapes.
5. First use case: enrich a User at registration from their email domain. In a listener on Registered, call the combined person+company lookup, persist the raw payload as JSON on the user, and extract a few columns (company name, domain, role, location) for segmentation. Do it in a queued job — enrichment latency is 300–1500 ms and you don't want that in the signup response.

Implementation Patterns

Wrap it, don't call it from controllers. Bind a thin LeadEnricher service around the facade so you can swap in a fake, add logging, and centralise credit accounting. The facade is convenient but static calls scattered across controllers are the usual path to an unmaintainable integration.

Combined lookup is the default, not the exception. If you need both person and company data for one email, use the combined endpoint — it's one request and one credit charge instead of two. Reach for the person-only or company-only endpoints when you genuinely need just one side.

Cache on the natural key with a real TTL. Enrichment responses are credits, and the data doesn't change fast. Cache by lowercased email for person lookups and by domain for company lookups, 30–90 days. Laravel's Cache::remember around your wrapper is enough; add a clearbit: prefix so you can flush it independently. Invalidate on explicit re-enrichment requests, not on every login.

Store the raw payload, project the columns. Cast a clearbit_data JSON column (or a dedicated enrichments table keyed by subject) and derive typed columns from it. Vendor payloads gain fields over time, and having the original lets you backfill new columns without re-spending credits.

Handle "no match" as a first-class outcome. A 404 means Clearbit has nothing for that email/domain — common for small companies and personal addresses. Your wrapper should return null (or a typed result object with a found flag) rather than letting an exception bubble into your registration flow. Log the miss at debug level so you can measure your hit rate.

IP reveal belongs behind a guard. Anonymous-visitor identification by IP is the highest-risk, lowest-precision feature here: shared NATs, VPNs, and mobile carriers produce wrong companies. Gate it to sessions with meaningful activity (e.g. 3+ pageviews in 10 minutes), cache the IP → company mapping for 24h, and never let it block the request. Also treat "reveal" as enrichment of a data subject, not just a lookup.

Prospector is a batch tool, not a request-cycle tool. Search is paginated and expensive; drive it from an artisan command or queued job, persist results to your own table, and paginate against your table from the UI. Never page through Prospector from a web request.

Respect the rate limit with Laravel primitives. Add ->middleware('throttle:clearbit') to the job, or a RateLimited job middleware, and configure the limiter in a service provider. A naive foreach ($users as $user) { enrich($user); } will burst straight into 429s on any real import.

Test with Http::fake(). The package almost certainly uses the Laravel HTTP client underneath, so faking responses by URL pattern is trivial and you should never hit the live API in tests. Keep a small fixture set: a hit, a 404 miss, a 202 pending, and a 429.

Gotchas and Tips

• 202 is not success. Person enrichment can return a pending/queued status for emails Clearbit hasn't seen before, with the real answer arriving later. Treat 202 as "retry with backoff in a few minutes," not "no data." Most naive integrations lose these records silently.
• Credits are the real failure mode. Every call bills. Watch for enrichment inside loops, inside saving model events, or in a Blade partial that renders per row. Instrument your wrapper with a counter in local/staging so a refactor's cost is visible before it hits production.
• Don't retry 4xx. Retry 429 and 5xx with exponential backoff (Http::retry(3, 200, throw: false)); a 401 or 404 retried three times just triples your latency and log noise.
• Set an explicit timeout. The default can be long enough to stack up queue workers. 5–10 seconds is right; enrichment is a background concern and a slow vendor shouldn't hold a worker slot indefinitely.
• API key leakage is a real risk because the facade exposes the key in config and exception messages sometimes include request context. Keep config('clearbit.api_key') out of dd() output, error trackers, and any endpoint that dumps config. php artisan config:cache in production after any config change, or your new key won't be picked up.
• Verify your Clearbit account still exists before building. Since the HubSpot acquisition, standalone Clearbit API access has been progressively folded into HubSpot's platform and new self-serve signups have been restricted. If you don't already hold a legacy key, confirm access first — this is the single biggest reason an integration like this stalls at step one.
• GDPR/CCPA applies to enrichment. You're inferring professional data about identified individuals from an email address. Make sure there's a lawful basis (usually legitimate interest for B2B), note the processing in your privacy policy, and honour deletion requests against your cached enrichment data — not just your users table.
• Common-domain false positives. gmail.com and outlook.com will resolve to the consumer mail provider, not the user's employer. Filter free-mail domains before enrichment so you don't waste credits or worse, store "Google" as everyone's employer.
• Extension points worth knowing: the base URL in config (point it at a proxy or a recorded fixture server for contract tests), the container binding for the client (rebind to your own wrapper implementation in a service provider), and any Macroable trait on the client if the package ships one — that's the clean way to add your own methods without forking.
• Debugging order when data looks wrong: dump the raw JSON first (the extracted columns may be fine while your mapping isn't), then check whether you hit the combined or single endpoint, then check the cache key's normalisation (case, whitespace, trailing dots on domains). Nine times out of ten it's a cache key or a stale entry, not the vendor.