The problem this solves
A signup arrives at 09:14: a work email at a domain your team has never heard of, a first name and a password. Your product has one chance to decide what happens next - a self-serve onboarding, a note to sales, an invitation to a demo - and it has to decide with the data it has at 09:14. What it has is an email address.
That address resolves to a company, and the company resolves to almost everything you need: headcount, industry, the technologies on its site, whether it fits the ICP you sell to. Fetching that by hand from three tools takes a person twenty minutes per signup. Fetching it from one endpoint takes your app one call, and the fit score turns the routing rule into a single comparison.
The endpoint has to behave like infrastructure. Free-mail addresses should come back labeled rather than guessed at, a source outage should degrade to fewer fields rather than a failure, retries should be safe, and every call should say what it cost so the finance conversation is short.
How the mission runs
- Send the email address. Your app sends one JSON body with the email to the enrichment tool through the REST API, authenticated with Authorization: Bearer and a key minted for the app alone. The Enrichment Agent's recipe shows the request as a curl line and as a fetch call so it can be pasted into a signup handler or a queue worker.
- Resolve the person's company. The domain of the address is resolved to a company first. Free-mail and disposable domains are recognized and returned with a personal-email flag and no company block, so your app can ask for a work email instead of enriching nothing. WHOIS and site data confirm the company behind a domain you have never seen.
- Fill the fields through the waterfall. Headcount, industry and HQ come from firmographics, the tech stack from technographics, and where the first source has no answer the next is tried, until the field fills or the sources are exhausted. You pay only when a source answers, so a thin company costs less than a well-documented one.
- Score against your ICP and verify the address. The company is scored against your ICP definition, with the reasons listed, and the email itself passes verification so the response can carry a verified flag your app can trust before it triggers a sales alert or a welcome sequence.
- Return the response and its cost. The response is one JSON object: email, a personal_email flag, company (domain, name, headcount, industry, HQ), tech_stack as an array, fit_score with reasons, verified with the status the verifier gave, and a metered block with the credits this call consumed. The recipe documents every field, which ones can be null, and the status codes to handle: a rate-limit response worth retrying after a pause, a schema error worth logging, and a credit-envelope response that means enrich later.
The prompt
This is the exact objective the agent receives. Swap the obvious placeholders for your own domain, segment or channel and run it as-is from the console, Slack, or the API.
What comes back
An example request, the documented response shape and the handling rules your app needs: a curl line and a fetch snippet, a field-by-field description of the JSON that comes back, the null cases, and the per-call credit cost as the platform reports it for your workspace. Wired into your signup handler, every new account arrives with company, size, industry, stack, a fit score and a verified flag, and the routing decision becomes one comparison on fit_score.
Make it yours
- Call it from a queue worker a few seconds after signup rather than inside the request, so onboarding never waits on enrichment and a retry costs the user nothing.
- Cache by domain in your own store: fifty signups from one company should cost one company lookup, with only the per-address verification repeated.
- Add the primary decision-maker to the response for high-fit signups, so a sales alert already names the person to call alongside the user who signed up.
- Push high-fit signups into HubSpot as a staged batch; the push is approval-gated and the recipe shows where the approval id comes back.
Frequently asked questions
How much does each call cost?
It depends on how many fields a source answers, because the waterfall meters per filled field. The response carries the exact credits for that call, and the console shows the per-call figure for your workspace, so you can budget from real numbers rather than an estimate.
What comes back for a gmail address?
A personal_email flag set to true, the verification status of the address, and no company block. Your app can branch on the flag and ask for a work email or route the signup to self-serve.
How fresh is the data?
Firmographics and technographics are fetched live at call time through the waterfall rather than from a copy your app has to refresh, so the headcount your router sees is the one the sources report today.
What if my app retries a call?
Reads are safe to repeat. Send an idempotency key with the request when you want a retry to replay the earlier result instead of metering again, the same mechanism the CLI uses for async runs and list pushes.
Can a signup spike overrun the budget?
No. The workspace's daily and monthly credit envelopes cap spend, and when they are exhausted the API refuses the call with a payment-required status. Treat that as a soft failure: queue the signup and enrich it when the envelope resets or a top-up lands.