Helios KYC v1

Verify Nepali identity documents, face match, and liveness in one multipart request built for mobile onboarding.

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

Send multipart/form-data with front and back images plus a short liveness video for a synchronous decision.

Authentication

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

Parameters

Parameter	Type	Required	Description
`front_image`	file	Yes	Front of citizenship, passport, or license, JPG or PNG up to 10 MB
`back_image`	file	Yes	Back of the same document, JPG or PNG up to 10 MB
`liveness_video`	file	Yes	Liveness clip in MP4, MOV, or WebM, 3 to 10 seconds
`external_id`	string	No	Your user or application ID, returned verbatim in responses
`callback_url`	string	No	HTTPS URL for async decision webhook when review is needed

Use clear, glare-free photos taken in daylight. Keep the full document inside the frame with all corners visible.

For Kathmandu onboarding, set external_id to your internal customer ID such as ktm_user_1042 so reviews map cleanly.

Videos over 50 MB are rejected. Compress on-device to 720p before upload for faster decisions.

curl -X POST https://api.sagea.space/helios/kyc/v1 \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -F front_image=@"front.jpg" \
  -F back_image=@"back.jpg" \
  -F liveness_video=@"liveness.mp4" \
  -F external_id="ktm_user_1042" \
  -F callback_url="https://example.com/webhooks/helios"

Response

A successful request returns 200 with scores, reasons, and extracted document fields.

{
  "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
  },
  "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"
}

When decision is review, poll the status endpoint or wait for the webhook before approving the user.

Reasons list stays empty on approved and explains review or declined outcomes otherwise.

Errors

Status	Code	Fix
400	`missing_artifact`	Attach all three files with exact field names and retry
413	`payload_too_large`	Compress video under 50 MB and images under 10 MB each
422	`spoof_detected`	Request a fresh live capture, reject photos of screens
401	`unauthorized`	Check `SAGEA_API_KEY` value and header formatting
429	`rate_limit_exceeded`	Back off and retry with exponential delay

Limits

50 MB video max, 10 MB per image, 60 requests per minute per key on shared plans.