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

# TruthFactor Signal API

> Identity corroboration — tell us what you know about a person, and we tell you which of it holds up.

TruthFactor is an identity-corroboration API. You submit what you know about a person — a
phone number, a first and last name, an email, a professional profile URL — choose which
**signals** you want run, and get back, per person, each signal as a `{trusted, confidence}`
verdict plus an overall **score**, risk **band**, and a machine-readable **reason**.

The API is **bulk and asynchronous**: submit an array of inputs, get a `request_id`
immediately, then read results by **polling** or receive them on an optional signed
**webhook**.

> **[Quickstart](https://docs.truthfactor.ai/quickstart.md)**
>
> Submit your first batch and poll for the result in two calls.

> **[Authentication](https://docs.truthfactor.ai/essentials/authentication.md)**
>
> Bearer keys, how they're minted, and what a 401 means.

> **[Reading a verdict](https://docs.truthfactor.ai/essentials/verdicts.md)**
>
> Why `null` is first-class and must never be read as `false`.

> **[API reference](https://docs.truthfactor.ai/api-reference/introduction.md)**
>
> The endpoints, schemas, and an interactive playground from the OpenAPI spec.

## The shape of an integration

**1. Get a key**

An admin of an active account mints an API key from the dashboard. The `tf_live_…`
secret is shown once. See [Authentication](https://docs.truthfactor.ai/essentials/authentication.md).

**2. Submit a batch**

`POST /v1/signals` with your inputs and the signals you want. You get a `request_id`
and a `202` straight away.

**3. Collect results**

Poll `GET /v1/signals/{request_id}`, or set a `webhook_url` and receive the completed,
signed payload. Results stay fetchable either way.

## What you get back

Each person comes back with a per-signal verdict map and an explainable roll-up:

* **`signals`** — each selected signal as `{trusted, confidence}`. See
  [The verdict model](https://docs.truthfactor.ai/essentials/verdicts.md).
* **`score`** (0–100) and **`band`** (`clear` · `caution` · `high_risk`) — a transparent,
  reproducible roll-up over the returned signals. See [Scoring and banding](https://docs.truthfactor.ai/essentials/scoring.md).
* **`reason`** — the dominant factor: an override code, or the lowest-scoring signal.

> [!NOTE]
>
> The machine-readable companion to these docs is the **OpenAPI 3.1 document** at
> `GET /api/v1/openapi.json`, generated from the same signal catalogue and contracts as the
> API itself, so the spec and the API cannot drift. The [API reference](https://docs.truthfactor.ai/api-reference/introduction.md)
> is rendered directly from it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.