Read Verification Results and Retrieve the Captured Selfie

Both calls on this page require your secret key. The sst_ client token can never reach them. Use the session id your client reported to fetch the authoritative result — what the client says happened is a hint; what the API returns is the truth.

Reading the Result

When your client reports completion, fetch the session by id with your secret key:

const res = await fetch(`https://api.spoofsense.ai/v1/verification_sessions/${sessionId}`, {
  headers: { Authorization: `Bearer ${process.env.SPOOFSENSE_API_KEY}` },
});
const result = await res.json();

if (result.status === "complete" && result.decision === "real") {
  // Genuine live capture: proceed.
} else {
  // "spoof", "failed", or "expired": reject or re-verify.
}

res = requests.get(
    f"https://api.spoofsense.ai/v1/verification_sessions/{session_id}",
    headers={"Authorization": f"Bearer {os.environ['SPOOFSENSE_API_KEY']}"},
)
result = res.json()
ok = result["status"] == "complete" and result["decision"] == "real"

curl https://api.spoofsense.ai/v1/verification_sessions/vs_… \
  -H "Authorization: Bearer $SPOOFSENSE_API_KEY"

Response

{
  "object": "verification_session",
  "id": "vs_…",
  "status": "complete",
  "decision": "real",
  "checks": {
    "face_liveness": { "decision": "real", "genuine_score": 0.94, "threshold": 0.5 },
    "deepfake":      { "decision": "real", "genuine_score": 0.88, "threshold": 0.5 }
  },
  "risk": {
    "attestation": "not_evaluated",
    "injection_blocked": false,
    "signals": { "duplicate_image": false }
  },
  "media": { "available": true, "sha256": "…", "content_type": "image/jpeg", "expires_at": "…" },
  "products": ["face_liveness", "deepfake"],
  "reference_id": "user_123",
  "metadata": null,
  "attempts": 1,
  "failure_code": null,
  "sdk": { "platform": "web", "version": "0.2.0" },
  "created_at": "…", "expires_at": "…", "captured_at": "…", "completed_at": "…"
}

The verification rule: the user is verified only when status is "complete" and decision is "real". Everything else — "spoof", "failed", "expired", or any value relayed by the client — is not verified.

The `risk` Object

signals.duplicate_image — this exact capture was already submitted in another of your sessions. It’s a soft signal worth reviewing, not an automatic rejection.
attestation — status of device attestation (e.g. Play Integrity) when provided by the SDK.
Injection-blocked sessions: when a capture was rejected for suspected injection (for example, a known virtual camera under the enforce policy), decision is "spoof", checks is null, and risk is exactly { "injection_blocked": true, "reason": "suspected_injection" }. Scores and signal details are deliberately withheld so a flagged session can’t be used to probe the detectors.

Retrieving the Captured Selfie

Liveness and deepfake checks confirm the face is real — not whose it is. If you match the capture against an ID document, keep KYC records, or route sessions to manual review, retrieve the exact image the models scored:

const media = await fetch(
  `https://api.spoofsense.ai/v1/verification_sessions/${sessionId}/media`,
  { headers: { Authorization: `Bearer ${process.env.SPOOFSENSE_API_KEY}` } },
).then((r) => r.json());
// media.url is a signed link valid for 5 minutes — fetch the bytes now.

media = requests.get(
    f"https://api.spoofsense.ai/v1/verification_sessions/{session_id}/media",
    headers={"Authorization": f"Bearer {os.environ['SPOOFSENSE_API_KEY']}"},
).json()
selfie = requests.get(media["url"]).content  # signed link, valid 5 minutes

# ?redirect=true 302s straight to the image bytes
curl -L -o selfie.jpg \
  "https://api.spoofsense.ai/v1/verification_sessions/vs_…/media?redirect=true" \
  -H "Authorization: Bearer $SPOOFSENSE_API_KEY"

The image is available as soon as the decision is — it uploads during capture, so there’s nothing to poll.
url is a signed link valid for 5 minutes. Fetch the bytes immediately; don’t store the link.
Verify your download against sha256 — it hashes the exact bytes the models scored, and matches the SDK’s capturedFrameSha256.
Every retrieval is written to your organization’s media access log, keeping biometric access auditable.

When Media Isn’t Available

GET …/media returns 404 MEDIA_NOT_AVAILABLE when the image can’t be served. The media block on the session read explains why:

`media.reason`	Meaning
`not_captured`	The session never completed a capture
`storage_disabled`	Your org has media storage off (Settings → Compliance)
`expired`	The capture passed its retention window
`unavailable`	The image was erased or the upload failed

Media storage, retention windows, and erasure are controlled per organization in the console’s compliance settings.

Get Started

Guides

Verification Sessions

Read Verification Results and Retrieve the Captured Selfie

Reading the Result

The `risk` Object

Retrieving the Captured Selfie

When Media Isn’t Available

​Reading the Result

​The risk Object

​Retrieving the Captured Selfie

​When Media Isn’t Available

Reading the Result

The `risk` Object

Retrieving the Captured Selfie

When Media Isn’t Available