Quickstart

1. Get an API key

Keys are created in the FIL portal under API Keys. Each key has a tier, up to your plan’s, so you can keep a Verify key for quick checks beside an Assess key for full analysis; each call costs its key’s tier’s credits. The tier is applied server-side, so the key is all you send. While you build, create a key with Mode: Test: it scores the published test subjects with fixed answers, free. 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 +443444930787, 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_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": {"phone_number": "+447700900123"}}'

Use a test key for this first call. +447700900123 is one of the published test subjects: it plays a number from an unallocated range (an impossible caller-ID) whose range risk is elevated, and a test key always returns the answer below. When you’re ready to score real numbers, switch to a live key. What comes back depends on your tier:

Verify
Assess

{
  "score": 75,
  "band": "high",
  "recommended_action": "step_up_auth",
  "primary_risk_factor": { "code": "CLI_IMPOSSIBLE" },
  "subject": {
    "phone_number": {
      "e164": "+447700900123",
      "valid": true,
      "country_code": "GB",
      "ndc": "7700",
      "line_type": "mobile",
      "allocated": false
    }
  },
  "suppressed": [
    { "component": "components", "available_in": "assess" },
    { "component": "reputation_ledger", "available_in": "assess" },
    { "component": "caller_id_integrity", "available_in": "assess" },
    { "component": "ndc_range_risk", "available_in": "assess" },
    { "component": "premium_tariff", "available_in": "assess" },
    { "component": "corroboration", "available_in": "assess" },
    { "component": "primary_risk_factor.narrative", "available_in": "assess" }
  ],
  "degraded_sources": [],
  "tier": "verify",
  "score_id": "sc_…",
  "disclosure": "Ranking relative to scored population. Not a probability of fraud. See the FIL scoring disclosure."
}

Verify answers with the score, band, action and reason code, plus the subject block, but not the evidence behind them. The number sits in an unallocated range (allocated: false), so it scores high / step_up_auth. suppressed lists what Assess adds.

{
  "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",
  "subject": {
    "phone_number": {
      "e164": "+447700900123",
      "valid": true,
      "country_code": "GB",
      "ndc": "7700",
      "line_type": "mobile",
      "allocated": false
    }
  },
  "degraded_sources": [],
  "tier": "assess",
  "score_id": "sc_…",
  "disclosure": "Ranking relative to scored population. Not a probability of fraud. See the FIL scoring disclosure."
}

Abridged: the full response also has a row for every other component Assess evaluates, and a few more fields. Assess includes everything Verify returns, subject among it, so one request gets you both. Assess also scores the numbering range, and fraud has accumulated against this one (NDC_RANGE_ELEVATED). That independent signal corroborates the impossible caller-ID and lifts the answer to critical / challenge.

The API reference lists every field, and How scoring works explains what each tier computes.

3. Read the three answers

Every response answers in three layers:

Field	What to do with it
`band` + `recommended_action`	Map to your workflow. `recommended_action` is a recommendation: your own rules decide what 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. `components` and the narrative are Assess and above; Verify returns the code only.

A clean number reads differently: band: "minimal", recommended_action: "allow", every component clean or unmatched — and, from Assess, 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, with the key that scored it:

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

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

How scoring works — bands, tiers, coverage, degradation.
Errors and limits — rate limits, credits, idempotency, retries.
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.

Getting started

Understanding results

1. Get an API key

2. Score a number

3. Read the three answers

4. Retrieve the evidence later

Next

​1. Get an API key

​2. Score a number

​3. Read the three answers

​4. Retrieve the evidence later

​Next

1. Get an API key

2. Score a number

3. Read the three answers

4. Retrieve the evidence later

Next