Helios KYC v2

Verify identity from server-side files with a single JSON request, including optional 1:1 portrait matching.

POST https://api.sagea.space/helios/kyc/v2

Send base64-encoded artifacts as JSON when files already live on your server or come from another upload pipeline.

Authentication

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

Parameters

Parameter	Type	Required	Description
`front_image_b64`	string	Yes	Base64 JPG or PNG of the document front without data URI prefix
`back_image_b64`	string	No	Base64 JPG or PNG of the document back for two-sided documents
`liveness_video_b64`	string	Yes	Base64 MP4, MOV, or WebM liveness clip, 3 to 10 seconds
`reference_portrait_b64`	string	No	Base64 portrait for 1:1 match against the liveness video
`external_id`	string	No	Your user or application ID, returned verbatim in responses
`options`	object	No	Options object with `store_media` boolean to retain source media
`options.store_media`	boolean	No	Set true to retain media for audit, defaults to false

Use v2 when your backend already holds the files, when the client uploads to your S3-compatible bucket first, or when you need JSON-only logs.

Use Helios KYC v1 when the mobile or web client can POST multipart/form-data directly and you want smaller payloads.

Base64 inflates payloads by about 33 percent, so keep source video under 35 MB before encoding.

curl -X POST https://api.sagea.space/helios/kyc/v2 \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "front_image_b64": "'$(base64 -w0 front.jpg)'",
    "back_image_b64": "'$(base64 -w0 back.jpg)'",
    "liveness_video_b64": "'$(base64 -w0 liveness.mp4)'",
    "external_id": "ktm_user_1042",
    "options": {"store_media": false}
  }'

Response

A successful request returns 200 with the same decision schema as v1.

{
  "verification_id": "helios_vrf_2pL7nR4wY9bQ",
  "external_id": "ktm_user_1042",
  "decision": "approved",
  "scores": {
    "document_authenticity": 0.96,
    "face_match": 0.93,
    "liveness": 0.95,
    "overall": 0.95
  },
  "reasons": [],
  "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"
}

Set reference_portrait_b64 for step-up re-auth where the stored portrait must match the live user.

When decision is review, poll verification status or wait for the configured webhook.

Errors

Status	Code	Fix
400	`missing_artifact`	Include required base64 fields with valid encoding
413	`payload_too_large`	Shrink source media so encoded JSON stays under limits
422	`spoof_detected`	Capture fresh liveness video and resubmit
401	`unauthorized`	Verify `SAGEA_API_KEY` and header formatting
429	`rate_limit_exceeded`	Retry with backoff and batch server-side jobs

Limits

25 MB JSON body max, 60 requests per minute per key on shared plans.