> ## 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.

# Quickstart

> Submit a batch and poll for the result in two calls.

Submitting is asynchronous: you get a `request_id` straight away and poll it. A batch of one
is fine.

> [!NOTE]
>
> Every request carries a bearer key. An admin of an active account mints keys from the
> dashboard; the secret is shown once at creation. See [Authentication](https://docs.truthfactor.ai/essentials/authentication.md).

## 1. Submit

```bash cURL theme={null}
curl -sS -X POST https://api.truthfactor.ai/api/v1/signals \
  -H "Authorization: Bearer $TF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{ "phone": "+447911123456", "correlation_id": "lead-4417" }],
    "signals": ["phone_connectivity"]
  }'
```

```js Node theme={null}
const res = await fetch("https://api.truthfactor.ai/api/v1/signals", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    inputs: [{ phone: "+447911123456", correlation_id: "lead-4417" }],
    signals: ["phone_connectivity"],
  }),
});
const { request_id } = await res.json();
```

```python Python theme={null}
import os, requests

res = requests.post(
    "https://api.truthfactor.ai/api/v1/signals",
    headers={"Authorization": f"Bearer {os.environ['TF_API_KEY']}"},
    json={
        "inputs": [{"phone": "+447911123456", "correlation_id": "lead-4417"}],
        "signals": ["phone_connectivity"],
    },
)
request_id = res.json()["request_id"]
```

Returns `202`:

```json theme={null}
{
  "request_id": "rq_8efcd577456f4bd1",
  "requested_datetime": "2026-09-26T14:03:11Z",
  "status": "pending",
  "accepted": 1
}
```

## 2. Poll

```bash theme={null}
curl -sS https://api.truthfactor.ai/api/v1/signals/rq_8efcd577456f4bd1 \
  -H "Authorization: Bearer $TF_API_KEY"
```

`status` stays `pending` until every item is terminal, then flips to `complete`. While it is
still running, `completed_datetime` is `null` — the key is always present:

```json theme={null}
{
  "request_id": "rq_8efcd577456f4bd1",
  "requested_datetime": "2026-09-26T14:03:11Z",
  "completed_datetime": null,
  "status": "pending",
  "data": []
}
```

Once it is done:

```json theme={null}
{
  "request_id": "rq_8efcd577456f4bd1",
  "requested_datetime": "2026-09-26T14:03:11Z",
  "completed_datetime": "2026-09-26T14:03:41Z",
  "status": "complete",
  "data": [
    {
      "correlation_id": "lead-4417",
      "input": { "phone": "+447911123456", "correlation_id": "lead-4417" },
      "status": "scored",
      "score": 92,
      "band": "clear",
      "reason": "phone_connectivity",
      "signals": { "phone_connectivity": { "trusted": true, "confidence": 92 } }
    }
  ]
}
```

> [!TIP]
>
> `correlation_id` is yours. Pass whatever identifies the row on your side and it comes back
> untouched, so you never have to match on array position.

## Next steps

> **[Pick your signals](https://docs.truthfactor.ai/essentials/signals.md)**
>
> The full catalogue, required inputs, and the premium tier.

> **[Receive results by webhook](https://docs.truthfactor.ai/essentials/webhooks.md)**
>
> Skip polling and verify the signed delivery.


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