Run a TrustCheck

Submit one or more pieces of identity input — a name plus any combination of emails, phones, or addresses — and get back a scored verification with per-field match status, sub-scores, history, and an overall verdict. TrustMatch generates the request_id for you; you don't need to mint or pass an identifier.

Authentication

Send your key as either X-API-Key: tm_... or Authorization: Bearer tm_.... Each successful call counts against your monthly included quota; calls beyond your plan's included calls are billed as overage on your next invoice.

Request body

At minimum you must include a name. Adding email and phone dramatically improves the score's precision because TrustMatch can cross-reference identities.

Example request

{
  "operation": "validate",
  "nameAddresses": [
    { "fullName": "Jane Doe" }
  ],
  "emailAddresses": ["jane@example.com"],
  "phoneNumbers": ["+15551234567"]
}

Response

{
  "success": true,
  "request_id": "5f3c8b1e-2a4d-4e9c-b6a1-9c7e3f1d8b25",
  "trustworthiness_score": 87,
  "status": "HIGH",
  "confidence_level": "HIGH",
  "possible_catfish": false,
  "summary": "Identity matched across name, email and phone.",
  "input_validation": {
    "name":  { "input": "Jane Doe",          "match_status": "Primary Match",  "matched_identity": 1, "is_primary": true,  "match_message": "VERIFIED MATCH: Name matches the primary verified identity." },
    "email": { "input": "jane@example.com",  "match_status": "Primary Match",  "matched_identity": 1, "is_primary": true,  "match_message": "VERIFIED MATCH: Email matches the primary verified identity." },
    "phone": { "input": "15551234567",       "match_status": "Primary Match",  "matched_identity": 1, "is_primary": true,  "match_message": "VERIFIED MATCH: Phone matches the primary verified identity." },
    "overall_match": { "all_components_match_same_identity": true, "matched_identity": 1 }
  },
  "identity_score":      { "final": 90, "raw": 90, "match_flags": { "name": "Primary Match", "email": "Primary Match", "phone": "Primary Match" } },
  "trust_score":         { "final": 85, "raw": 85, "reasons": ["Identity history: 4+ years", "No recent risk signals"] },
  "combined_trust_score":{ "final": 87, "pre_capped": 87, "confidence_level_label": "high", "explanation": "Strong cross-channel match with established history." },
  "verification_flags": [],
  "insights": [],
  "history": {
    "first_seen": "2021-08-14T00:00:00Z",
    "last_seen": "2026-04-30T00:00:00Z",
    "days_since_first_seen": 1721,
    "days_since_last_seen": 14
  }
}

Notes

• request_id is server-generated. Use it to look up this call later or correlate logs.
• trustworthiness_score is 0–100. Verdicts: 85+ = VERIFIED, 65–84 = LIKELY REAL, 40–64 = SUSPICIOUS, below 40 = HIGH RISK.

Intent — tailoring the AI narrative

The optional intent field tells TrustMatch what situation the check is for. The Gemini overview adjusts its positive_signals, risk_factors, and recommended_actions to match — the same scores get a different story. The numeric trustworthiness_score and signal status flags are intent-agnostic.

AI enhancement

TrustMatch can layer a Gemini-powered analysis on top of any verification. Two opt-in modes, same endpoint, same auth:

Request — call with AI enabled

curl -X POST "https://api.trustmatch.app/v1/validate?ai=true" \
  -H "X-API-Key: tm_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "validate",
    "nameAddresses": [{ "fullName": "Jane Doe" }],
    "emailAddresses": ["jane@example.com"],
    "phoneNumbers": ["+15551234567"],
    "intent": "online-dating"
  }'

Response — same as above, plus ai_insights

{
  "request_id": "5f3c8b1e-2a4d-...",
  "trustworthiness_score": 87,
  "status": "HIGH",
  /* …all the normal fields… */
  "ai_insights": {
    "ai_enabled": true,
    "trust_enhancement": {
      "overview": "Strong cross-channel identity match with established history.",
      "risk_assessment": "low",
      "confidence_adjustment": "+2",
      "reasoning": "All three contact channels match the same dominant identity..."
    },
    "intent": "online-dating",
    "overview": {
      "overview": "Jane Doe’s identity verifies cleanly across name, email and phone — no catfish signals.",
      "key_findings": [
        "Three contact channels resolve to the same dominant identity.",
        "Identity history spans 4+ years — well above the catfish threshold."
      ],
      "positive_signals": [
        "Email and phone both match primary identity.",
        "Established history is inconsistent with romance-scam patterns."
      ],
      "risk_factors": [],
      "recommended_actions": [
        "Video chat before any in-person meeting.",
        "First meet in a public place — don’t accept rides.",
        "Even with a strong verification, never send money to someone you haven’t met."
      ],
      "review_priority": "AUTO_APPROVE"
    }
  }
}

With /v1/validate/enhanced, the same response also includes ai_insights.fraud_detection and ai_insights.name_matching.

Field reference

• overview.overview — 1–2 sentence headline summary, safe to show to end users.
• overview.positive_signals[] — verified facts that raise confidence (max 5 items).
• overview.risk_factors[] — flagged concerns; empty when none are detected.
• overview.recommended_actions[] — suggested next steps; use these to drive your own UI checklist.
• overview.review_priority — one of AUTO_APPROVE, MANUAL_REVIEW, AUTO_REJECT. Treat as a hint, not a decision.
• ai_insights.ai_enabled — true when the AI call succeeded. If false, the base response is still valid and complete — treat the AI block as a soft-failure.