TL;DR: Send a POST with email or LinkedIn URL or company domain. Get back enriched fields. Same engine as the in-app Enrich button, no UI required.
When to use the API
Three patterns:
- CRM integration. Your CRM is the source of truth for net-new leads. As they're created, hit the Enrichment API to populate contact channels and persona fields before routing.
- Sequencer prep. Before a sequence launches, validate each lead's email via the Enrichment API. Replace bouncing emails on the fly.
- AI-agent workflows. Your LLM agent needs structured contact data on a person it just discovered. Call the Enrichment MCP tool, get the contact channels back as JSON.
API endpoint
POST /enrichment
Headers:
Authorization: Bearer <UNSTUCK_API_KEY>
Content-Type: application/json
Body:
{
"email": "person@company.com", // optional, identity hint
"linkedin_url": "https://...", // optional, identity hint
"company_domain": "company.com", // optional, identity hint
"channels": ["work_email", "phone"] // which channels to enrich
}
At least one identity hint (email, LinkedIn URL, company domain) must be provided. The waterfall runs for the specified channels.
Response:
{
"record_id": "lead_abc123",
"channels": {
"work_email": {
"value": "person@company.com",
"source": "Provider A",
"confidence": 0.94
},
"phone": {
"value": null,
"tried_providers": ["A", "B", "C"]
}
},
"credits_used": 4
}
MCP tool
The same enrichment is exposed as an MCP tool for AI agent workflows:
tool: enrich_record
arguments:
identity_hint: { email | linkedin_url | company_domain }
channels: ["work_email", "personal_email", "phone", "linkedin_url"]
Connect via @unstuckengine/mcp-server (npm). Once registered in your MCP client (Claude Desktop, Cursor, etc.), the agent can call enrich_record as part of any reasoning chain.
Credit accounting via API
Identical to the in-app behavior. Each successful enrichment costs credits per the provider's rate. Failed attempts (waterfall exhausted, no contact found) cost zero.
The response includes credits_used so your downstream system can track burn. You can also poll /credits to check current balance before bulk-enriching via the API.
Idempotency
The Enrichment API is idempotent on a record-channel basis. If you send the same enrich request for a record that's already been enriched for those channels, the response returns the cached values; no credits charged.
To force a re-enrichment via API, include force: true in the body. The previous values are cleared and the waterfall re-runs.
Rate limits
- 100 requests per minute per workspace
- 10,000 requests per day per workspace
- For higher-volume needs (bulk backfills), use the bulk audience-enrich UI action which respects internal batching
CLI
For one-off enrichments from the command line:
$ npx @unstuckengine/cli enrich \
--email person@company.com \
--channels work_email,phone
Returns the same JSON shape. Useful for shell scripts and quick checks.