Docs / Lookup API reference · 6 min
Lookup API reference
The POST contract every integration speaks: request, response fields, errors, and the fail-open rule.
The endpoint
Every workspace gets one lookup URL, shown on the dashboard home page. It is the only endpoint an integration needs: your tracker POSTs the inbound caller number to it before the call routes, and the response says allow or block.
POSThttps://api.callersift.com/v1/your-workspace
- Your exact URL is on the home page; the last segment is your workspace slug.
- Form-encoded and JSON bodies both work.
- Typical answer time is milliseconds; cached numbers answer fastest.
Authentication
- Send your API key in the X-Api-Key header, or as an api_key field in the body. Either works; the header keeps keys out of body logs.
- Keys are minted and rotated on the home page without downtime: see the API keys and rotation guide.
- Treat the key like a password. Anyone holding it can spend your lookups.
Request
| Field | Required | Description |
|---|---|---|
| caller_number | required | The inbound caller’s number. E.164 format (+15551234567) is safest; most tracker merge tags emit it already. |
| api_key | required | Your API key. Send it as this body field or as an X-Api-Key header instead; a request carrying neither answers 401. |
curl
curl -X POST https://api.callersift.com/v1/your-workspace \ -H "X-Api-Key: YOUR_KEY" \ -d "caller_number=+15551234567"
TrackDrive example body: caller_number={caller_number}&api_key=YOUR_KEY. Ringba uses [tag:InboundNumber]; Retreaver uses [caller_number].
Response
The response is a small JSON object. Route the call on verdict; everything else is context for humans and reports.
| Field | Values | What it means |
|---|---|---|
| verdict | allowblock | The decision. The only field your routing rule needs. |
| line_type | mobile, landline, fixedVoip, nonFixedVoip, tollFree, … | The carrier classification of the number. |
| reason | text | A human-readable explanation of the verdict, the same text you see in the lookups view. |
| source | livecache | live scored the number against carrier data on this request; cache answered instantly from a recent verdict. |
| intel | object · null | The raw line-type intelligence behind the verdict, for your own logging. |
allow
{
"verdict": "allow",
"line_type": "mobile",
"reason": "Mobile line: real handset traffic",
"source": "live",
"intel": { … }
}block
{
"verdict": "block",
"line_type": "nonFixedVoip",
"reason": "Non-fixed VoIP (e.g. Google Voice, TextNow, burner app): high fraud risk",
"source": "cache",
"intel": { … }
}Errors and the fail-open rule
| Status | Meaning | Route the call? |
|---|---|---|
| 200 | A verdict. Route on it. | On the verdict |
| 400 | No caller_number in the body. The response still carries verdict allow. | Allow |
| 401 | Missing or wrong API key. Check the key on the home page and your header or body field. | Allow |
| 429 | Rate limited. No retry needed; the next call scores normally. | Allow |
Design your routing so anything other than verdict block, including timeouts and network errors, routes the call normally. CallerSift is built fail-open for the same reason: an outage on the scoring path must never block a genuine caller.
Wire it into your platform
- TrackDrive and Ringba: step-by-step in Point your call tracker at the lookup URL.
- Retreaver: see Connect Retreaver.
- Anything else that can fire a webhook per inbound call works the same way: POST, read verdict, route.
- Prove the path end to end with Send a test lookup before real traffic rides on it.