Helios Verification Status

Poll any verification until it reaches a final decision, then confirm the result with signed webhooks.

GET https://api.sagea.space/helios/verifications/{verification_id}

Status starts at pending while documents and liveness are scored, then moves to approved, review, or declined.

Authentication

Send Authorization: Bearer $SAGEA_API_KEY on every request. Get a key

Parameters

Parameter	Type	Required	Description
`verification_id`	string	Yes	Verification ID from KYC v1 or v2, path parameter
`include_media`	string	No	Set to `extracted` to include OCR fields in the status body
`callback_url`	string	No	HTTPS webhook set at submit time for final decision POSTs
`X-Helios-Signature`	string	No	HMAC header Helios sends on every webhook callback

Poll every 2 to 5 seconds for up to 60 seconds, then rely on webhooks for longer review cases.

Configure callback_url at submit time so Helios POSTs the final decision JSON automatically.

Verify the X-Helios-Signature header with HMAC SHA256 over the raw body using your webhook secret.

Helios retries failed webhook deliveries with backoff over 24 hours before marking delivery dead.

curl https://api.sagea.space/helios/verifications/helios_vrf_8fK2mQ9xT4aZ \
  -H "Authorization: Bearer $SAGEA_API_KEY"

Sample webhook delivery to your callback_url:

{
  "event": "helios.verification.updated",
  "verification_id": "helios_vrf_8fK2mQ9xT4aZ",
  "external_id": "ktm_user_1042",
  "decision": "approved",
  "scores": {
    "document_authenticity": 0.97,
    "face_match": 0.94,
    "liveness": 0.96,
    "overall": 0.96
  },
  "extracted": {
    "full_name": "Aarav Sharma",
    "document_number": "N1234567",
    "date_of_birth": "1995-04-12",
    "expiry_date": "2030-04-11",
    "issuing_country": "NP"
  },
  "model_used": "helios-kyc-1.0"
}

Response

Polling returns the current status plus the latest scores and extracted fields when ready.

{
  "verification_id": "helios_vrf_8fK2mQ9xT4aZ",
  "status": "approved",
  "external_id": "ktm_user_1042",
  "decision": "approved",
  "scores": {
    "document_authenticity": 0.97,
    "face_match": 0.94,
    "liveness": 0.96,
    "overall": 0.96
  },
  "reasons": [],
  "model_used": "helios-kyc-1.0"
}

A pending status returns partial scores, while review includes reviewer reasons and next steps.

Treat approved and declined as terminal and stop polling once either arrives.

Errors

Status	Code	Fix
404	`verification_not_found`	Check the ID spelling and account scope
401	`unauthorized`	Verify `SAGEA_API_KEY` and header formatting
429	`rate_limit_exceeded`	Slow polling to every 5 seconds with jitter
400	`invalid_signature`	Recompute HMAC over raw bytes, not parsed JSON

Limits

120 status polls per verification, webhook retries for 24 hours with backoff.