Developers

TFSA REST API

Programmatic access to email-verification recording and your account's verification history, plus a set of public, unauthenticated, anonymised data endpoints (government-domain lookup, fraud map, trends, impact counters, changelog). A small, stable REST surface served same-origin — authenticate account reads with a Bearer API key from the admin portal; the public endpoints need no key. Machine-readable spec: /openapi.json.

Quick start

curl -X POST /api/verify \
  -H "Authorization: Bearer $TFSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"procurement@example.com","domain":"example.com","isLegitimate":false}'

Response

{
  "ok": true
}

Endpoints

POST/api/verify

Record a verification outcome for an email/domain. Body: { email, domain, isLegitimate }. Returns { ok: true } on success.

Auth: PublicRate limit: 30 / min per IP
GET/api/verifications

Your account's own verification history (newest first, up to 500) plus real summary counts. Other accounts' records are never returned.

Auth: API keyRate limit: 60 / min per account
GET/api/verifications/{id}

A single owned verification, including the analyzed body, headers, signals and submission metadata. A non-owned id returns 404.

Auth: API keyRate limit: 60 / min per account
GET/api/public/domain-lookup

Is a domain a recognised SA government / state-owned-entity / municipal domain? Query ?domain=example.gov.za. Returns { status, message, reviewAvailable }; never enumerates the corpus.

Auth: PublicRate limit: 30 / min per IP
POST/api/public/domain-lookup

The same recognition check via JSON body { domain }. The GET alias above is easier for agents and links to crawl.

Auth: PublicRate limit: 30 / min per IP
GET/api/public/fraud-map

Anonymised provincial fraud-activity aggregates behind the live map (counts and severity by province). Query ?window=24h|7d|30d|90d. Never names a domain, organisation or person.

Auth: PublicRate limit: 60 / min per IP
GET/api/public/fraud-trend

Anonymised monthly fraud-detection trend (trailing months) plus current-month impact figures. Scalar aggregates only.

Auth: PublicRate limit: 60 / min per IP
GET/api/public/impact-stats

Aggregate platform impact counters: emails verified, fraud blocked, RFQs analysed, and the measured detection rate. Scalar counts only.

Auth: PublicRate limit: 60 / min per IP
GET/api/public/changelog

Published release notes as structured JSON (versions, dated titles, grouped change entries).

Auth: PublicRate limit: 60 / min per IP

Webhooks

Register an HTTPS endpoint from the admin portal. Deliveries are signed HMAC-SHA256 with your endpoint secret. Subscribable events:

  • verification.completed

    A verification finished analysis.

  • verification.flagged

    A verification was flagged as high-risk.

  • pattern.discovered

    A new fraud pattern was identified.

  • report.received

    A fraud report was submitted to the platform.

  • user.invited

    A team member was invited to your account.

  • system.health

    A platform health/status change occurred.

Authentication

Authenticated endpoints use Bearer-token auth on the Authorization header. Keys are created in the admin portal and shown once — store them securely.

  • Live keys are prefixed tfsa_live_; sandbox keys tfsa_test_.
  • Scopes: verify:read, verify:write, patterns:read, admin:read.
  • Optionally restrict a key to an IP allowlist and set an expiry.

Error handling

  • 400 Invalid input / malformed body
  • 401 Missing or invalid bearer token
  • 404 Record not found or not owned
  • 429 Rate limit exceeded (see Retry-After)
  • 500 Server error — retry with backoff

Get an API key

Authenticated endpoints require a key. Create and manage keys in the admin portal — the secret is shown once at creation.

Manage API keys

Support & discovery

Machine-readable spec

OpenAPI description of the public endpoints, plus the AI index.

/openapi.json →