Quickstart

Score your first phone number.

1. Get an API key

Keys are created in the FIL portal under Keys. Your organisation’s tier is applied server-side — the key is all you send.

Keys look like filk_… and are shown once at creation. Store it in a secret manager.

2. Score a number

Subjects are E.164: +, country code, subscriber number — no national trunk zero. Send [phone], not +44 (0)344…. A trunk zero won’t error; it will quietly resolve to no numbering range and score as unattested.

curl -X POST https://api.fraudintelligencelimited.com/v1/score \
  -H "Authorization: Bearer $FIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": {"phone_number": "[phone]"}}'

That subject is from Ofcom’s reserved TV-drama range — no real subscriber can hold it, which is exactly what the response says:

{
  "score": 88,
  "band": "critical",
  "recommended_action": "challenge",
  "score_basis": "riskier than 88% of scored ranges",
  "primary_risk_factor": {
    "code": "CLI_IMPOSSIBLE",
    "narrative": "The caller-ID sits in an unallocated numbering range — no genuine subscriber number can exist there."
  },
  "components": [
    { "component": "caller_id_integrity", "verdict": "adverse", "detail": "CLI_IMPOSSIBLE", "contribution": 40 },
    { "component": "reputation_ledger", "verdict": "no_match", "contribution": 0 },
    { "component": "ndc_range_risk", "verdict": "elevated", "detail": "NDC_RANGE_ELEVATED", "contribution": 22 }
  ],
  "coverage": "strong",
  "degraded_sources": [],
  "score_id": "sc_…",
  "disclosure": "Ranking relative to scored population. Not a probability of fraud. See the FIL scoring disclosure."
}

3. Read the three answers

Every response carries the same three layers:

Field	What to do with it
band + recommended_action	Map to your workflow. recommended_action is a recommendation — your action_policy decides what actually happens to your customer.
score	The 0–100 ranking, for thresholds and analytics.
components + primary_risk_factor	The evidence. Show the narrative to your analysts.

A clean number reads differently: band: "minimal", recommended_action: "allow", every component clean or unmatched — and coverage tells you how much reporting stood behind that answer. A low score with thin coverage means unwatched, not clean.

4. Retrieve the evidence later

Every score is retained for 13 months and retrievable by its score_id:

curl https://api.fraudintelligencelimited.com/v1/explain/sc_… \
  -H "Authorization: Bearer $FIL_API_KEY"

Scores also appear in the portal’s Activity page as they happen.

Next

• How scoring works — bands, tiers, coverage, degradation.
• Errors and limits — rate limits, credits, idempotency.
• API reference — the full contract. It’s served by the API itself at /v1/openapi.yaml, so it can never drift from deployed behaviour; point any OpenAPI tool at it to generate a client.