Document-Only Checks

Use Helios v2 to verify an ID document without collecting a liveness video.

• Send a v2 JSON request with only front and back images
• Get a document-only decision with authenticity scores and extracted fields
• Decide when to escalate to full liveness verification

Time to complete: ~8 minutes

Prerequisites

• SAGEA_API_KEY set in your environment as Bearer auth.
• Read Send your first API request to create a key.
• Read How Helios works to understand decisions and scores.
• Two test images: front.jpg (required) and back.jpg (optional, recommended for two-sided IDs).

Step 1: Prepare your images

Helios v2 accepts base64-encoded images in JSON. Encode your test files and check sizes before sending.

ls -lh front.jpg back.jpg
python3 -c "import base64; print(len(base64.b64encode(open('front.jpg','rb').read())))"

Keep each image under 10MB. Use JPG or PNG with the ID fully visible and at least 1200px wide.

Step 2: Send a document-only v2 request

POST https://api.sagea.space/helios/kyc/v2 normally takes front_image_b64, back_image_b64, and liveness_video_b64. Omit liveness_video_b64 to get a document-only decision.

curl -X POST https://api.sagea.space/helios/kyc/v2 \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(python3 -c "import base64, json; print(json.dumps({'external_id': 'doc_only_001', 'front_image_b64': base64.b64encode(open('front.jpg','rb').read()).decode(), 'back_image_b64': base64.b64encode(open('back.jpg','rb').read()).decode(), 'options': {'store_media': False}}))")"

Without liveness_video_b64, Helios skips face match and liveness and returns a document-only decision based on authenticity and extraction.

Step 3: Handle the document-only decision

A document-only response uses the same schema, but face_match and liveness scores are absent or zero. Gate on document_authenticity and extracted fields.

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

Example response keeps the standard schema with verification_id, decision, scores, reasons, extracted, and model_used.

Verify

A successful run returns HTTP 200 with decision set to approved, review, or declined and an extracted block. If it fails, check below.

What's next

• Liveness and face match
• Review queue and webhooks
• How Helios works