Standalone tools

The /v3/tools/* endpoints are one-shot utilities that mirror the console Manual Tools, tenant-scoped by the API key. They run a single check without creating a verification session — useful for ad-hoc screening, back-office review, dedup lookups, and enrichment. Images are passed as base64-encoded strings in the body (a data: URI prefix is accepted and stripped).

Image inputs

Every image argument funnels through one decode chokepoint. Only JPEG and PNG are accepted — HEIC (iPhone), WEBP, GIF, BMP, and TIFF are rejected with 415 unsupported_image_type rather than failing confusingly downstream. Images must be ≤ 8 MB after base64 decoding.

Billing & entitlements

Every tool carries the same entitlement gate and per-use billing as its console Manual Tool, at the rate your plan sets for its key (a tenant rate, else the platform rate, else 1 credit):

• If the feature isn't enabled for the tenant → 403 { "detail": "feature_not_enabled", "features": ["<KEY>"] }.
• If the balance can't cover the per-use rate → 402 { "detail": "insufficient_credits" }.
• On success, one use is debited to the credit ledger with reason: "tool_usage". Failed calls are never charged.

document-extract is gated and billed under DOCUMENT_OCR, but only debits when the read returned something — fields or a generic full_text. A portrait-only read, 422 ocr_no_fields and 503 ocr_not_configured pass the gate without being charged.

signature-enroll is gated and billed per enrolled specimen under SIGNATURE_ENROLL, on /v3 and in the console alike. The console twin additionally requires the operator to hold the console_manage_kyc permission.

face-enroll is billed per enrolled face under FACE_ENROLL, and additionally needs the opt-in IDENTITY_IMPORT grant — the same capability as identity import, off until the platform enables it for your tenant (403 naming IDENTITY_IMPORT). Re-sending a photo already enrolled for the identity is a free replay. Listing and removing enrolled faces are neither gated nor charged.

registry-lookup is gated and billed under REGISTRY_VALIDATION, the same key and rate as the console Registry Lookup — an opt-in key, off until the platform enables it for your tenant (403 naming REGISTRY_VALIDATION). It debits one use for every lookup the registry answered, not_found included; a lookup that could not be made (502 registry_unavailable, 503 registry_not_configured) or a rejected number (400 invalid_number — including one that is only punctuation, which has nothing to look up) is free. A workflow step's registry check bills the same way.

business-document and registry-lookup cover Nepal's documents and official records only. While Nepal is switched off for your account, both are refused with the same 422 document_type_not_available body ({ detail, message, country: "NP" }) before anything runs — never charged.

Retries. Send an Idempotency-Key header (≤128 chars) and a retry of the same request — same key, same body, same UTC day — is not charged again (nor refused with a 402). Reusing a key with a different body is a new, billed use.

Endpoints

AML check

Screen a name against sanctions / PEP / watchlist datasets. Same engine as the AML_SCREENING module, run standalone.

POST /v3/tools/aml-check/

curl -X POST https://acme.thirdfactor.ai/v3/tools/aml-check/ \
  -H "x-api-key: $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "full_name": "Aarav Sharma", "date_of_birth": "1990-04-12", "nationality": "NP" }'

const resp = await fetch("https://acme.thirdfactor.ai/v3/tools/aml-check/", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OBSIDIAN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    full_name: "Aarav Sharma",
    date_of_birth: "1990-04-12",
    nationality: "NP",
  }),
});
const result = await resp.json();

import requests

resp = requests.post(
    "https://acme.thirdfactor.ai/v3/tools/aml-check/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
    json={"full_name": "Aarav Sharma", "date_of_birth": "1990-04-12", "nationality": "NP"},
)
result = resp.json()

{
  "risk_level": "clear",
  "matches": [],
  "possible_matches": [],
  "informational_matches": [],
  "lists_checked": ["pep", "sanctions"],
  "provider": "watchlist",
  "dataset": "default",
  "algorithm": "logic-v1",
  "threshold": 0.85
}

A confirmed hit looks like this (abbreviated match object):

{
  "risk_level": "high",
  "matches": [
    {
      "entity_id": "NK-abc123",
      "name": "Aarav Sharma",
      "schema": "Person",
      "score": 0.97,
      "match": true,
      "lists": ["sanctions"],
      "topics": ["sanction"],
      "datasets": ["us_ofac_sdn"],
      "birth_date": "1990-04-12",
      "countries": ["np"],
      "aliases": [],
      "positions": [],
      "url": "https://…/entity/NK-abc123"
    }
  ],
  "possible_matches": [],
  "informational_matches": [],
  "lists_checked": ["pep", "sanctions"],
  "provider": "watchlist"
}

Errors

Face search

1:N search over the tenant's enrolled identities — rank identities whose enrolled face best matches the probe photo. Read-only (nothing is flagged).

The searchable gallery holds two face sources: selfies captured live during a session and photos enrolled from outside — in bulk through identity import, or one at a time through face enroll. Document portraits, vendor reference faces and liveness stills are excluded, so a hit always means "we hold this face as this person".

POST /v3/tools/face-search/

curl -X POST https://acme.thirdfactor.ai/v3/tools/face-search/ \
  -H "x-api-key: $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_base64": "'"$(base64 -i selfie.jpg)"'", "top_k": 5 }'

import { readFileSync } from "node:fs";

const image_base64 = readFileSync("selfie.jpg").toString("base64");
const resp = await fetch("https://acme.thirdfactor.ai/v3/tools/face-search/", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OBSIDIAN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ image_base64, top_k: 5 }),
});
const { matches } = await resp.json();

import base64, requests

image_base64 = base64.b64encode(open("selfie.jpg", "rb").read()).decode()
resp = requests.post(
    "https://acme.thirdfactor.ai/v3/tools/face-search/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
    json={"image_base64": image_base64, "top_k": 5},
)
matches = resp.json()["matches"]

{
  "matches": [
    {
      "individual_id": "0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "name": "Aarav Sharma",
      "external_user_id": "your-user-reference-123",
      "status": "active",
      "kyc_status": "approved",
      "score": 0.9142,
      "thumb": "https://acme.thirdfactor.ai/media/…/thumb.jpg"
    }
  ],
  "threshold": 0.35
}

Errors

Signature verify

1:1 comparison — compare a probe signature against a reference. Both inputs are first cropped to the signature ink, so a full ID photo or a video frame is matched on its signature, not the surrounding scene.

POST /v3/tools/signature-verify/

curl -X POST https://acme.thirdfactor.ai/v3/tools/signature-verify/ \
  -H "x-api-key: $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference_base64": "<b64>", "probe_base64": "<b64>" }'

const resp = await fetch("https://acme.thirdfactor.ai/v3/tools/signature-verify/", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OBSIDIAN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ reference_base64: refB64, probe_base64: probeB64 }),
});
const { verdict, matched } = await resp.json();

resp = requests.post(
    "https://acme.thirdfactor.ai/v3/tools/signature-verify/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
    json={"reference_base64": ref_b64, "probe_base64": probe_b64},
)
verdict = resp.json()["verdict"]

{
  "score": 0.9,
  "verdict": "match",
  "matched": true,
  "threshold": 0.62,
  "signals": {}
}

Errors

Signature search

Reverse (1:N) search over the tenant's enrolled signature specimens — a recall aid for operators, not a verdict.

POST /v3/tools/signature-search/

{
  "matches": [
    {
      "individual_id": "0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "name": "Aarav Sharma",
      "external_user_id": "your-user-reference-123",
      "status": "active",
      "score": 0.8321,
      "thumb": "https://acme.thirdfactor.ai/media/…/sig.png"
    }
  ],
  "threshold": 0.6,
  "beta": true
}

Errors

Signature enroll

Add a reference signature specimen to an identity's gallery, growing what reverse search can find. Returns 201. Not gated or charged.

POST /v3/tools/signature-enroll/

curl -X POST https://acme.thirdfactor.ai/v3/tools/signature-enroll/ \
  -H "x-api-key: $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_user_id": "your-user-reference-123", "image_base64": "<b64>", "label": "account-opening" }'

resp = requests.post(
    "https://acme.thirdfactor.ai/v3/tools/signature-enroll/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
    json={"external_user_id": "your-user-reference-123", "image_base64": sig_b64, "label": "account-opening"},
)
sample = resp.json()  # 201

{
  "sample_id": "7a8b9c0d-1e2f-4a3b-5c6d-7e8f9a0b1c2d",
  "individual_id": "0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f"
}

Errors

Face enroll

Enroll one face into your tenant's 1:N gallery — what face search and the automatic duplicate check match against. The face counterpart of signature enroll, and the one-at-a-time sibling of identity import: same storage, same rules. Returns 201.

POST /v3/tools/face-enroll/

curl -X POST https://acme.thirdfactor.ai/v3/tools/face-enroll/ \
  -H "x-api-key: $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_user_id": "user-ref-123", "image_base64": "'"$(base64 -i photo.jpg)"'",
        "label": "loan-application-2026", "consent_reference": "Customer T&C v3 accepted at signup" }'

resp = requests.post(
    "https://acme.thirdfactor.ai/v3/tools/face-enroll/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
    json={"external_user_id": "user-ref-123", "image_base64": photo_b64,
          "label": "loan-application-2026",
          "consent_reference": "Customer T&C v3 accepted at signup"},
)
face = resp.json()  # 201 — or 200 with replayed: true for a re-sent photo

{
  "face_id": "9d2f7c11-4b8e-4a3d-bb6e-2f1c0a9e8d77",
  "individual_id": "0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "external_user_id": "user-ref-123",
  "label": "loan-application-2026",
  "identity_created": true,
  "replayed": false,
  "duplicates": []
}

The face is stored as an imported enrolment: searchable by 1:N, but never treated as a verification selfie.

List and remove. GET /v3/tools/face-enroll/?external_user_id=… (or ?individual_id=…) lists an identity's enrolled faces — { face_id, label, origin, image_url, created_at }, where origin is api or import. DELETE /v3/tools/face-enroll/{face_id}/ permanently removes one enrolled face (and the identity this API created, once nothing else remains on it). Enrolled faces hang off no session, so the evidence-retention sweep never reaches them — this is how you dispose of one. Neither call is gated or charged, and both keep working if the IDENTITY_IMPORT grant is later withdrawn.

Errors

Document extract

Run OCR / field extraction on a single identity-document image via the platform document-OCR service. Works on any account (independent of the tenant's Lens config). Gated and charged under DOCUMENT_OCR — see billing & entitlements — on this endpoint and on its console twin alike; a read that returned no fields and no full_text is not charged.

POST /v3/tools/document-extract/

Which documents it classifies

Classification is limited to your account's document types: the platform's country documents narrowed to the countries — and document types — enabled for your account. There is no separate "international" switch: a country on the international classifier that is enabled for you contributes its documents (e.g. with India enabled an Aadhaar card is auto-detected as Aadhaar Card and an Indian PAN card as PAN Card, with India as their country), and its documents are read by that classifier — whether you send the hint or leave auto-detect on. Auto-detect runs the local read first and hands the document to the international classifier whenever the local read can't settle it within your set: nothing recognised, a document family that an enabled international country also issues with no country named on it, or a country named that is on the international classifier. Its document type and issuing country then pick the document, so a UAE ID or an Indian passport auto-detects with the same fields and country as when you name it. List the set with a free GET:

GET /v3/tools/document-extract/

{
  "candidates": [
    { "key": "NP:citizenship", "country": "NP", "country_name": "Nepal", "type": "citizenship", "subtype": "", "label": "Citizenship certificate", "classifier": "local", "generic": false },
    { "key": "IN:aadhaar", "country": "IN", "country_name": "India", "type": "id_card", "subtype": "aadhaar", "label": "Aadhaar Card", "classifier": "international", "generic": false }
  ]
}

A hint outside the set is refused before anything is read (400 document_type_not_available), and an auto-detected document whose country or type isn't enabled for you is refused rather than reported as something else (422 document_type_not_available) — neither is charged. Switching a country off for your account removes its documents from the hint list and from auto-detect immediately; documents read earlier are unaffected.

curl -X POST https://acme.thirdfactor.ai/v3/tools/document-extract/ \
  -H "x-api-key: $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_base64": "'"$(base64 -i passport.jpg)"'" }'

import { readFileSync } from "node:fs";

const image_base64 = readFileSync("passport.jpg").toString("base64");
const resp = await fetch("https://acme.thirdfactor.ai/v3/tools/document-extract/", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OBSIDIAN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ image_base64 }),
});
const doc = await resp.json();

import base64, requests

image_base64 = base64.b64encode(open("passport.jpg", "rb").read()).decode()
resp = requests.post(
    "https://acme.thirdfactor.ai/v3/tools/document-extract/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
    json={"image_base64": image_base64},
)
doc = resp.json()

{
  "fields": {
    "full_name": "AARAV SHARMA",
    "document_number": "PA1234567",
    "date_of_birth": "1990-04-12",
    "expiry_date": "2030-04-11",
    "nationality": "NPL"
  },
  "translated_fields": {},
  "detected_type": "passport",
  "confidence": 0.96,
  "is_document_valid": true,
  "has_portrait": true,
  "document": { "key": "NP:passport", "country": "NP", "country_name": "Nepal", "type": "passport", "subtype": "", "label": "Passport", "classifier": "local", "generic": false },
  "country": "NP",
  "country_name": "Nepal"
}

Errors

Registry lookup

Look a business up in Nepal's official records by its number — the API twin of the console Registry Lookup tool, and the same registry check a BUSINESS_DOCUMENT workflow step runs on an uploaded certificate. No image is involved: you send the number, optionally with the name you expect on file.

POST /v3/tools/registry-lookup/

Try it live in the API Explorer under Tools → Registry lookup — it sends real (billed) requests to your tenant with your API key.

curl -X POST https://acme.thirdfactor.ai/v3/tools/registry-lookup/ \
  -H "x-api-key: $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "pan", "number": "000000000", "name": "Acme Technologies Pvt. Ltd." }'

const resp = await fetch("https://acme.thirdfactor.ai/v3/tools/registry-lookup/", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OBSIDIAN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    kind: "pan",
    number: "000000000",
    name: "Acme Technologies Pvt. Ltd.",
  }),
});
const lookup = await resp.json();
if (lookup.status === "matched") {
  console.log(lookup.record.name_english, lookup.record.tax_clearance);
}

import requests

resp = requests.post(
    "https://acme.thirdfactor.ai/v3/tools/registry-lookup/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
    json={"kind": "pan", "number": "000000000", "name": "Acme Technologies Pvt. Ltd."},
    timeout=60,
)
lookup = resp.json()

{
  "kind": "pan",
  "source": "ird_pan",
  "status": "matched",
  "found": true,
  "number": "000000000",
  "number_used": "000000000",
  "name_check": { "similarity": 1.0, "threshold": 0.8, "matched": true },
  "record": {
    "number": "000000000",
    "name_english": "ACME TECHNOLOGIES",
    "name_nepali": "एक्मे टेक्नोलोजिज",
    "registration_date_bs": "2072.04.11",
    "address": "ललितपुर, महानगरपालिका कुपन्डोल",
    "company_type": null,
    "office": "आन्तरिक राजस्व कार्यालय ललितपुर-१",
    "registrations": [
      { "type": "Income Tax", "status": "Active" },
      { "type": "VAT", "status": "Active" }
    ],
    "tax_clearance": "Cleared"
  }
}

A company looked up by number alone, and a number with no record:

{
  "kind": "company",
  "source": "company_registrar",
  "status": "matched",
  "found": true,
  "number": "000000/00/00",
  "number_used": "000000/00/00",
  "name_check": null,
  "record": {
    "number": "000000",
    "name_english": "Acme Technologies",
    "name_nepali": "एक्मे टेक्नोलोजिज",
    "registration_date_bs": "2081-08-27",
    "address": "Lalitpur Metropolitan City-1, Lalitpur",
    "company_type": "All Nepali Ownership",
    "office": null,
    "registrations": null,
    "tax_clearance": null
  }
}

{
  "kind": "company", "source": "company_registrar", "status": "not_found", "found": false,
  "number": "999999", "number_used": null, "name_check": null, "record": null
}

Errors

Errors carry { "detail": "<code>" }; a lookup that could not be made adds a human-readable message (for example, which official website is down).

Tools vs. a session

Common pitfalls

FAQ

Related