RocketReach API: Credits, Match Logic, and CRM Enrichment Workflow
Summarize with AI
The RocketReach API can search for prospects, look up known people and companies, and return enrichment data for a CRM. A reliable implementation uses strong identifiers, handles lookup completion through signed webhooks, watches credits and rate limits, and applies its own deduplication rules before writing. RocketReach documents accepted inputs and statuses, but it does not publish deterministic match precedence or universal CRM merge behavior.
RocketReach API Endpoint Map
RocketReach's API documentation separates search and lookup functions from status, account, and webhook functions. Search discovers candidates. Lookup asks for data on a known person or company. Status and webhooks handle work that has not completed in the first response.
| Job | Documented route | Main control |
|---|---|---|
| Search people | `POST /person/search` | Filter and paginate candidates |
| Look up one person | `GET /person/lookup` | Use the strongest available identifier |
| Check person status | `GET /person/checkStatus` | Correlate with profile IDs or request ID |
| Bulk person lookup | `POST /bulkLookup` | Submit 1 to 100 legacy queries with webhook access |
| Search companies | `POST /searchCompany` | Narrow by company attributes and signals |
| Look up a company | `GET /company/lookup/` | Supply domain, ID, LinkedIn URL, name, or ticker |
| Read usage | `GET /account/` | Monitor allocation, use, and remaining credits |
The API base in the current definitions is https://api.rocketreach.co/api/v2. The account endpoint documents the Api-Key request header. Keep the key in a server-side secret store and do not place it in browser code, logs, URLs, or CRM notes.
Search Discovers Candidates, Lookup Enriches Them
The People Search API accepts filters for titles, employers, company attributes, geography, contact methods, email or phone grades, skills and experience, plus other fields. Page size runs from 1 to 100. RocketReach's FAQ places a 10,000-result ceiling on one query and recommends tighter filters for larger result sets.
Search output should not become a CRM write by itself. The documentation says email grades can change when a lookup performs additional validation. Use search to identify candidate profiles, then request only the enrichment needed by the workflow.
For an existing CRM person, the People Lookup API accepts RocketReach ID, LinkedIn URL, email, phone, NPI number, or name paired with current employer. The name and employer fields require each other. Title can supplement the request.
Our opinion is that a stable vendor ID or profile URL should outrank a name-only route. RocketReach does not publish fuzzy-match thresholds or identifier precedence, including tie-breaking rules, so the client must decide when a returned profile is safe to attach to an existing person.
Asynchronous Lookups Need a Completion Path
A lookup can return waiting, searching, progress, complete, or failed. RocketReach says contact information may remain incomplete until the final complete state. The return_cached_emails option defaults to true; setting it false keeps email fields null until processing completes and fully verified emails are available.
RocketReach recommends webhooks instead of repeated polling. Use the RR-Request-ID to connect the callback with the original CRM job. The service supports an X-RocketReach-Signature, calculated as a Base64-encoded HMAC-SHA256 signature over the raw request body with the webhook secret.
Verify the signature with a constant-time comparison before parsing the callback into a write job. Reject missing or invalid signatures. Store the request ID, status transition, timestamp, and payload hash so retries can be recognized without creating duplicate CRM updates.
The legacy bulk endpoint accepts 1 to 100 queries and requires an enabled webhook or specified webhook ID. Universal bulk lookup supports up to 100 people but requires at least 10; smaller Universal batches belong on the single lookup route.
RocketReach API Credits Need Separate Ledgers
RocketReach currently documents more than one credit system. Legacy people and person-plus-company lookup pages, along with the bulk lookup page, say those actions consume export credits. Its credit FAQ explains that API lookups, bulk lookups, CSV downloads, list uploads, and CRM exports use export allowances.
Annual plans can advertise unlimited lookups, while the same FAQ states a 10,000-lookup monthly fair-use ceiling. Export allowances remain separate. Re-lookups and updates stay free while the plan remains active according to the API FAQ.
Universal endpoints use action-priced credits. The current documentation lists one credit per Universal people-search result page and two per company-search result page, with up to 100 results on a page. Person enrichment prices differ by requested field, including separate amounts for professional email, personal email, phone, detailed-person, and healthcare data. Universal access is not currently available to the public Essentials, Pro, or Ultimate tiers.
Do not merge these systems in one cost estimate. Read the account endpoint and plan contract for the endpoint family used by the implementation. Track each search page, lookup, returned field set, repeat request, and CRM export as a distinct event.
Rate Limits Shape Queue Design
RocketReach publishes a global ceiling of 10 requests per second across its APIs, plus plan and endpoint windows. Search, person lookup, and bulk jobs each have their own minute, hour, day, and sometimes month limits.
A throttled request returns HTTP 429 with a Retry-After value in seconds. Parse that value and wait before retrying. The errors guide says to retry HTTP 500 later but does not specify a backoff formula, jitter rule, idempotency guarantee, or maximum attempt count.
Build a queue that can pause by endpoint and account. Keep request IDs stable where the API allows correlation. Place failed jobs in a review state after a bounded retry policy set by your team. A repeated billable lookup should not happen merely because a worker lost its local acknowledgement.
Write to the CRM Through an Acceptance Layer
A controlled RocketReach API workflow follows seven steps:
- Authenticate with the header-based credential.
- Search only when the CRM lacks a known person or company identifier.
- Look up with the strongest available identifier and request only required fields.
- Receive completion through a verified webhook, using status polling as a fallback.
- Compare the result against field-level acceptance and freshness rules.
- Upsert with a stable external ID and preserve suppression and ownership fields.
- Record credits, status, source time, changed fields, and the final write result.
RocketReach offers direct Salesforce and HubSpot integrations, among others. Its Salesforce page describes lead and contact exports, plus account exports with field mapping, while its HubSpot page describes contact and bulk sync. Those pages do not define universal dedupe keys, null-overwrite behavior, conflict resolution, or rollback.
A custom integration should make those decisions explicit. Our outbound services keep vendor data separate from campaign eligibility and preserve the client-owned CRM as the operating record. Our outbound resources can help define the field acceptance sheet before API work starts.
Ready to Build Controlled CRM Enrichment?
We can design the RocketReach API queue, webhook verification, credit ledger, dedupe rules, and field-level acceptance checks around your client-owned outbound system.
Frequently Asked Questions
A modern outbound stack includes: data enrichment (Apollo, Clay, ZoomInfo), email infrastructure (Google Workspace, custom domains), sending tools (Smartlead, Instantly), warm-up services (Warmbox), LinkedIn automation (Expandi, Dripify), CRM integration (HubSpot, Salesforce), and analytics platforms. Most agencies use 15–30 tools orchestrated together.
Building your own stack costs $3K–5K/month in software alone, plus a dedicated person to manage it. With a managed service, you get all the tooling plus the expertise to orchestrate it, often at lower total cost. The key question: can you afford to spend 6–8 weeks setting up instead of generating pipeline?
There's no single 'best' tool. It depends on your volume, budget, and integration needs. Smartlead and Instantly are popular for high-volume sending. Apollo doubles as a data and sequencing platform. The real advantage comes from how tools are orchestrated together, not from any single tool choice.
Look for three things: (1) Do you own the infrastructure they build? (2) Are the engagement terms clear, including what happens after the initial build-and-learn period? (3) Can you see transparent metrics and real case studies with specific numbers? LeadHaste starts with a three-month engagement, then moves month-to-month. Avoid vague reporting and providers that own your domains.
Data enrichment is the process of taking basic company or contact data and adding layers of detail: job titles, direct emails, phone numbers, technographics, intent signals, company size, funding stage, and more. Enrichment tools like Apollo, Clay, and ZoomInfo pull from multiple data sources to build a complete prospect profile before outreach begins.
Jacob Martinez
GTM Engineer, LeadHaste
Builds the machinery behind client campaigns: scraping, enrichment, lead scoring and the automations that keep a list clean before anyone gets emailed.
