AI Customer Profile & Identity API

Identity Resolution Deterministic + Probabilistic Consent & Policy Hooks Explainable Match Graph Real-Time Updates Export/Erase APIs
Operated by Spyface Tech Company, LLC • 30 N Gould St Ste N, Sheridan, WY 82801 USA • Support: hello@spyface.com

1) Identity Model

The system uses a canonical person_id with attached identifiers and events. Identifiers can be verified, observed, or derived (hashed/normalized) depending on policy.

2) Identity Resolution Engine

Resolution combines deterministic rules with probabilistic matching. The objective is to minimize both false merges (two different people merged) and false splits (same person fragmented), with configurable thresholds per use-case.

// Conceptual decision
if deterministic_key_match(): LINK(confidence=1.0)
else:
  p_same = model(features)
  if p_same >= merge_threshold: MERGE
  else if p_same >= link_threshold: LINK
  else: KEEP_SEPARATE

3) Match Graph & Explainability

Every match decision produces a match graph: nodes are identities and identifiers, edges are links with timestamps, confidence, and evidence. This is critical for debugging and audit.

{
  "decision":"LINK",
  "confidence":0.93,
  "trace_id":"trace_8f31c",
  "evidence":[
    {"signal":"email_hash_match","value":true,"impact":"HIGH"},
    {"signal":"device_stability","value":"STABLE","impact":"MEDIUM"},
    {"signal":"geo_velocity","value":"NORMAL","impact":"LOW"}
  ]
}

4) Account Takeover & Synthetic Identity Signals

Identity is also security. The API can emit risk flags to feed your fraud/risk controls and step-up auth.

{
  "risk":{
    "ato_probability":0.18,
    "synthetic_probability":0.07,
    "flags":["DEVICE_SHIFT","CLUSTER_DENSITY_RISE"],
    "recommended_action":"STEP_UP_AUTH"
  }
}

5) Privacy, Consent, and Data Controls

6) Endpoints

7) Schemas

Resolve request

{
  "request_id":"req_res_2001",
  "tenant_id":"t_spyface_demo",
  "identifiers":{
    "email_hash":"sha256:8b1a...",
    "phone_hash":"sha256:91c2...",
    "device_id":"dev_77a19",
    "account_id":"acc_1902"
  },
  "attributes":{
    "name":"JANE DOE",
    "country":"US"
  },
  "event":{
    "type":"BOOKING_ATTEMPT",
    "ts":"2026-01-26T17:40:12Z",
    "context":{
      "product":"HOTEL",
      "channel":"WEB",
      "ip_prefix":"203.0.113.0/24"
    }
  },
  "policy":{
    "scope":"TRAVEL",
    "sensitivity":"STANDARD",
    "consent":"GRANTED"
  }
}

Resolve response

{
  "request_id":"req_res_2001",
  "person_id":"p_55019",
  "decision":"LINK",
  "confidence":0.93,
  "trace_id":"trace_8f31c",
  "evidence":[
    {"signal":"email_hash_match","value":true,"impact":"HIGH"},
    {"signal":"device_stability","value":"STABLE","impact":"MEDIUM"},
    {"signal":"geo_velocity","value":"NORMAL","impact":"LOW"}
  ],
  "risk":{
    "ato_probability":0.18,
    "synthetic_probability":0.07,
    "flags":["DEVICE_SHIFT"],
    "recommended_action":"STEP_UP_AUTH"
  },
  "policy_result":"ALLOW"
}

8) Code Examples

Node.js — Resolve identity

const base = "https://api.spyface.com";
const headers = {
  "Authorization": `Bearer ${process.env.SPYFACE_API_KEY}`,
  "Content-Type": "application/json"
};

const res = await fetch(`${base}/v1/identity/resolve`, {
  method: "POST",
  headers,
  body: JSON.stringify(payload)
});
const out = await res.json();

if (out.policy_result !== "ALLOW") {
  throw new Error("Policy blocked identity action");
}

if (out.risk?.recommended_action === "STEP_UP_AUTH") {
  // trigger OTP / WebAuthn / KBA depending on your program
}

console.log(out.person_id, out.decision, out.confidence, out.trace_id);

Python — Minimal PII hashing (email normalization)

import hashlib

def norm_email(s: str) -> str:
  return s.strip().lower()

def sha256_hex(s: str) -> str:
  return hashlib.sha256(s.encode("utf-8")).hexdigest()

email_hash = "sha256:" + sha256_hex(norm_email("User@Example.com"))
print(email_hash)

9) Operational Playbooks

10) Integration Patterns