Quickstart

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

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.

1. Submit

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"]
  }'

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();

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:

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

2. Poll

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:

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

Once it is done:

{
  "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 } }
    }
  ]
}

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.

Get started

Core concepts

1. Submit

2. Poll

Next steps

Pick your signals

Receive results by webhook

​1. Submit

​2. Poll

​Next steps

Pick your signals

Receive results by webhook

1. Submit

2. Poll

Next steps