Developer Tutorial
A production-friendly pattern: submit lookup → async id → poll → normalize → cache → audit trail.
Engineering teams and decision-makers building:
This tutorial covers: creating enrichment jobs, async polling, normalizing output, caching to control costs, and audit trails.
Request Path (sync)
Worker Path (async)
Create an enrichment_jobs table:
| Field | Type | Description |
|---|---|---|
| job_id | UUID | Your internal UUID |
| tenant_id | string | Customer / org identifier |
| input_type | enum | phone | email | name |
| input_value | string | Hashed + raw if needed |
| lookup_id | integer | IRBIS lookupId used |
| irbis_request_id | integer | Numeric id returned by IRBIS |
| status | enum | queued | running | completed | failed |
| result_normalized | JSON | Your stable internal schema |
| created_at | timestamp | Job creation time |
| updated_at | timestamp | Last status update |
| error | string | Error message if failed |
Call once per tenant or daily and cache the mapping.
curl -X GET \
'https://irbis.espysys.com/api/request-monitor/lookupid-list?key=YOUR_API_KEY' \
-H 'accept: application/json'
Store: combined_phone → lookupId | combined_email → lookupId | combined_name → lookupId
Phone example — same pattern for email and name:
EndpointPOST https://irbis.espysys.com/api/developer/combined_phonecURLcurl -X POST \
'https://irbis.espysys.com/api/developer/combined_phone' \
-H 'Content-Type: application/json' \
-d '{
"key": "YOUR_API_KEY",
"value": "+79017007397",
"lookupId": YOUR_LOOKUPID
}'
Response gives a numeric id + status: "progress". Save as irbis_request_id.
Email: POST /api/developer/combined_email | Name: POST /api/developer/combined_name
EndpointGET https://irbis.espysys.com/api/request-monitor/api-usage/{id}?key=YOUR_API_KEYcURLcurl -X GET \
'https://irbis.espysys.com/api/request-monitor/api-usage/1486?key=YOUR_API_KEY' \
-H 'accept: application/json'
Backoff: 2s → 5s → 10s between attempts. Max 12–18 attempts. Mark failed if still pending after that.
Do not depend on provider-specific JSON forever. Normalize into a stable schema:
{
"provider": "clearcheck-data",
"input": { "type": "phone", "value": "+79017007397" },
"status": "completed",
"signals": [
{ "type": "identity", "name": "..." },
{ "type": "exposure", "label": "..." },
{ "type": "footprint", "label": "..." }
],
"raw_ref": { "irbis_request_id": 1486 }
}
Store raw JSON optionally for debugging. Always record: provider, request id, timestamps, lookup type.
Cache key: tenant_id + input_type + normalized(input_value)
Phone / Email
TTL: 7–30 days. Stable identifiers.
Name
TTL: 1–7 days. Higher ambiguity.
If cached and fresh → return cached. If missing/stale → create new job.
curl -X GET \
'https://irbis.espysys.com/api/request-monitor/credit-stat?key=YOUR_API_KEY' \
-H 'accept: application/json'
Implement: per-tenant daily budget, per-workflow limits, rate limiting per identifier.
Mistake: Hardcoding lookupId
Fix: Call lookupid-list and cache the mapping. Package changes can shift your active IDs.
Mistake: Blocking user request while waiting for IRBIS
Fix: Return job_id immediately. Process enrichment in a background worker.
Mistake: Too many repeated requests causing timeout error
Fix: Use caching + backoff + cooldown per tenant/workflow.
Mistake: Storing only raw provider JSON
Fix: Store a normalized schema. Raw JSON for debug only. Normalized output for product stability.
Get your API key and connect your first workflow today.
Why return job_id immediately instead of waiting?
Enrichment can take seconds to minutes. Blocking user requests causes timeouts and poor UX. Return a job_id immediately and poll from background.
What if IRBIS returns an error instead of a request id?
Check your lookupId against the lookupid-list endpoint, verify your API key and credit balance. Log the error and mark the job failed.
Should I store the raw IRBIS JSON?
Optionally, for debugging and audit. Always store normalized output in your own schema for product stability.
How do I handle the 30-second timeout?
Implement a per-identifier cooldown in your queue. Return cached result if a second request arrives within 30 seconds.
How large should my credit buffer be?
Keep at least 20-30% above expected daily usage. Check credit-stat at job submission to block requests when balance is too low.