> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudintelligencelimited.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Score your first phone number.

## 1. Get an API key

Keys are created in the [FIL portal](https://portal.fraudintelligencelimited.com) 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 `+443444930787`, not `+44 (0)344…`. A trunk zero won't error; it will quietly resolve to no numbering range and score as unattested.

```bash theme={null}
curl -X POST https://api.fraudintelligencelimited.com/v1/score \
  -H "Authorization: Bearer $FIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": {"phone_number": "+447700900123"}}'
```

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

```json theme={null}
{
  "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`:

```bash theme={null}
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](/how-scoring-works) — bands, tiers, coverage, degradation.
* [Errors and limits](/errors-and-limits) — rate limits, credits, idempotency.
* [API reference](/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.