Async Enrichment Pipeline — Submit, Poll, Parse
ClearCheck Data uses an asynchronous enrichment model. Submit a job, receive an ID, poll when ready, parse the result. This tutorial covers the full workflow — from initial request to consuming structured JSON.
- Non-blocking architecture — your system never waits
- Consistent job ID pattern across all lookup types
- Poll once or build a polling loop for high-volume pipelines
- Full JSON response schema with all signal fields explained
Submit the Enrichment Job
POST to the lookup endpoint with your API key and the identifier. The server processes the request immediately and returns a job ID — your system doesn't wait for enrichment to finish.
// Submit enrichment job POST /api/developer/combined_phone Content-Type: application/json Authorization: Bearer YOUR_API_KEY { "lookup_type": "phone", // phone | email | name | image "value": "+14155552671", "lookup_id": 42 // your reference ID — returned as-is } // Immediate response — job has been queued { "id": 8821043, // store this — you'll need it to poll "status": "progress" // enrichment is running asynchronously }
Poll the Monitor Endpoint
Query the monitor endpoint with the job ID. When status returns completed, the enrichment data is ready. Most lookups complete in under 1 second.
// Poll for result using stored job ID GET /api/request-monitor/api-usage/8821043 Authorization: Bearer YOUR_API_KEY // Still processing: { "status": "progress" } // Ready to consume: { "status": "completed", "data": { ... } }
Parse the Structured Response
Once status is completed, the full enrichment payload is in the data field. Route signals to your risk engine, CRM, or review queue.
{
"status": "completed",
"data": {
"type": "phone_lookup",
"lookup_id": 42,
"confidence": 0.94,
"signals": {
"carrier": "Example Carrier",
"line_type": "mobile",
"country": "US",
"active": true,
"risk_score": 0.12,
"spam_flag": false,
"identity_score": 7.4,
"linked_profiles": ["example_network"],
"linked_emails": ["user@example.com"]
}
}
}
Building a Production Enrichment Pipeline
Non-Blocking Submission
Submit lookups and immediately continue processing. Store the job ID and poll asynchronously — your main thread never blocks.
Batch Submissions
For high-volume pipelines, submit multiple jobs in parallel. Each returns a job ID. Collect results via the monitor endpoint when processing allows.
Polling Strategy
For most use cases, a single poll after 0.5–1 second is sufficient. For batch pipelines, implement an exponential backoff polling loop.
Map Results to Records
Pass your internal reference ID as lookup_id. It is returned as-is in the completed response so you can match enrichment data to your records.
Secure Key Handling
Store your API key in an environment variable. Never include it in frontend JavaScript, client-side code, or version control.
Route by Signal
Parse risk_score, line_type, and identity_score. Route results above your threshold to review queues. Route clean signals directly to approvals or CRM updates.