OVSE Status

API reference

curl -X GET "https://__playground__/verification/v1/ovse/status/string"

{
  "session_id": "ovse_sess_abc123",
  "session_status": "completed",
  "txn": "txn_xyz789",
  "client_reference_id": "ref-001",
  "success": true,
  "verified_at": 1749456100,
  "name": "Resident Name",
  "dob": "1990-01-15",
  "gender": "M",
  "mobile": "9876543210",
  "full_address": "House 1, Street 2, City, State - 400001",
  "user_photo": "iVBORw0KGgoAAAANSUhEUgAA...",
  "result": {}
}

{
  "detail": {},
  "message": "string"
}

{
  "detail": {},
  "message": "string"
}

{
  "error": "string"
}

Overview

Call GET /verification/v1/ovse/status/{session_id} from your backend after OVSE Init and after the resident has had time to complete Aadhaar App authentication. Poll until session_status reaches a terminal state.

When session_status is completed, the response includes normalized resident identity fields (name, dob, gender, mobile, full_address, user_photo, and nested result) decoded from the UIDAI SD-JWT callback. Treat every completed response as sensitive PII.

Key features

• Tenant-scoped: Session is visible only to the AppSecure tenant that created it.
• Terminal states: completed, failed, expired.
• OKYC-compatible fields: Top-level identity fields for downstream KYC pipelines.
• Webhook alternative: Skip polling when you set webhook_url on Init.

Implementation

Prerequisites

1. session_id from a successful OVSE Init call.
2. Resident has opened the QR or same-device launch link and completed (or abandoned) Aadhaar authentication.

Step 1: Poll from your backend

Headers

• Authorization: Bearer <token>. Required. Scope must include verify-aadhaar-ovse.

GET /verification/v1/ovse/status/ovse_sess_abc123 HTTP/1.1
Host: <verification-api-base-url>
Authorization: Bearer <token>
Accept: application/json

Step 2: Interpret session_status

Step 3: Use completed identity fields

On completed, key top-level fields:

Do: Store and transmit under your Aadhaar data handling policies. Do not: Log full responses or photos in plain-text analytics.

Polling guidance

• Start polling after presenting the QR or launch link to the resident.
• Use exponential backoff with a ceiling (for example 2s, 4s, 8s, max 15s) to avoid hammering the API.
• Stop when status is terminal or when expires_at from Init has passed.

Error handling

Example failed session body (200 with terminal status):

{
  "session_id": "ovse_sess_abc123",
  "session_status": "failed",
  "failure_code": "301",
  "failure_message": "User rejected authentication"
}

Security notes

• Responses contain PII and possibly Aadhaar-linked data. Log only correlation ids.
• Call only from your backend; never expose the Bearer token or raw status payload to the browser.

Benefits

• Simple poll model for async offline verification.
• Normalized fields ready for KYC orchestration without parsing SD-JWT yourself.

Next steps

• OVSE Init
• Verification API index