Quickstart

Set these environment variables using the credentials provided by Trelent. See Authentication for details.

Variable	Value
`TRELENT_API_URL`	Your deployment’s base URL
`TRELENT_CLIENT_ID`	Your client ID
`TRELENT_CLIENT_SECRET`	Your client secret

Typical turnaround is 60–120 seconds, with processing time continually improving.

Three requests

This cURL outline shows the flow with abbreviated responses. Copy the returned token into ACCESS_TOKEN and the detection ID into DETECTION_ID before sending the next request.

# 1. Get a token.
curl -X POST "$TRELENT_API_URL/token" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$TRELENT_CLIENT_ID" \
  --data-urlencode "client_secret=$TRELENT_CLIENT_SECRET" \
  --data-urlencode "scope=DocumentVerification:*"
# { "access_token": "eyJhbGciOi...", ... }

# 2. Create a detection. Replace the example URL with your document URL.
curl -X POST "$TRELENT_API_URL/v1/detection" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://files.example.com/id-card.pdf",
    "doc_type": "id_card",
    "region": "BR"
  }'
# { "id": "detection-...", "status": "QUEUED", ... }

# 3. Repeat every 5 seconds until COMPLETED or FAILED.
curl "$TRELENT_API_URL/v1/detection/$DETECTION_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
# { "id": "detection-...", "status": "COMPLETED", "score": 87, ... }

Run the flow

The Python example uses requests; the TypeScript example uses Node.js with built-in fetch. Both stop polling on success or failure and allow up to 40 minutes before timing out.

Python
TypeScript

import os
import time
import requests

base = os.environ["TRELENT_API_URL"].rstrip("/")

# 1. Get a token.

response = requests.post(f"{base}/token", data={
"grant_type": "client_credentials",
"client_id": os.environ["TRELENT_CLIENT_ID"],
"client_secret": os.environ["TRELENT_CLIENT_SECRET"],
"scope": "DocumentVerification:\*",
}, timeout=10)
response.raise_for_status()
headers = {"Authorization": f"Bearer {response.json()['access_token']}"}

# 2. Create a detection.

response = requests.post(f"{base}/v1/detection", headers=headers, json={
"source_url": "https://files.example.com/id-card.pdf",
"doc_type": "id_card",
"region": "BR",
}, timeout=120)
response.raise_for_status()
detection_id = response.json()["id"]

# 3. Poll for the result.

deadline = time.monotonic() + 2400
while time.monotonic() < deadline:
response = requests.get(
f"{base}/v1/detection/{detection_id}", headers=headers, timeout=30,
)
response.raise_for_status()
detection = response.json()
if detection["status"] == "FAILED":
raise RuntimeError(detection["failure_message"])
if detection["status"] == "COMPLETED":
print(detection["score"])
break
time.sleep(5)
else:
raise TimeoutError(f"Detection {detection_id} is still pending")

const base = process.env.TRELENT_API_URL!.replace(/\/$/, "");
const readJson = async (response: Response) => {
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
};

// 1. Get a token.
const { access_token } = await readJson(await fetch(`${base}/token`, {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.TRELENT_CLIENT_ID!,
    client_secret: process.env.TRELENT_CLIENT_SECRET!,
    scope: "DocumentVerification:*",
  }),
  signal: AbortSignal.timeout(10_000),
}));
const headers = { Authorization: `Bearer ${access_token}` };

// 2. Create a detection.
const { id } = await readJson(await fetch(`${base}/v1/detection`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    source_url: "https://files.example.com/id-card.pdf",
    doc_type: "id_card",
    region: "BR",
  }),
  signal: AbortSignal.timeout(120_000),
}));

// 3. Poll for the result.
const deadline = Date.now() + 2_400_000;
while (true) {
  if (Date.now() >= deadline) throw new Error(`Detection ${id} is still pending`);
  const detection = await readJson(await fetch(`${base}/v1/detection/${id}`, {
    headers,
    signal: AbortSignal.timeout(30_000),
  }));
  if (detection.status === "FAILED") throw new Error(detection.failure_message);
  if (detection.status === "COMPLETED") {
    console.log(detection.score);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

Display the score and detailed reasoning in your platform for human review of high-risk documents. A higher score means a higher likelihood of fraud, but does not guarantee fraud. Humans should always review high-risk cases. Some completed detections have a null score and an authoritative finding instead. See Get a detection for result fields, and Start a detection for supported inputs and request errors. For sample allowances, see Billing. To try requests interactively, download an API collection.

Getting started

API reference

Three requests

Run the flow

​Three requests

​Run the flow

Three requests

Run the flow