Step 1 of 2. Sends an OTP to the mobile number linked to the Aadhaar and returns the session_id you need for /v2/verify/okyc_get_result.

aadhaar_number must be exactly 12 digits with a first digit of 2-9, and user_consent must be true. Both are checked before any upstream call, so a malformed request is rejected free. Send an optional Idempotency-Key header (up to 255 characters) to make retries safe.

Response contract: every HTTP 2xx is status: "success" and only a raised error is status: "error", so branch on error_code, never on status. Every response carries tranx_id (quote it to support), timestamp (ISO 8601 UTC), billed (whether the call was charged to your idto credits) and the legacy string fields chargeble and user_consent. Authenticate with your X-Client-ID and X-API-KEY headers. A definitive "no record" answer is a successful, billed call: status: "success", data: null and error_code: "IDTO_202".

Codes: IDTO_202 (200, Aadhaar invalid or not found; billed), IDTO_001 (invalid input: Aadhaar not 12 digits or starts with 0/1, or a required field missing; 400, or 422 if the request body fails schema validation), IDTO_005 (user_consent is not true, 400), IDTO_004 (duplicate request with an Idempotency-Key already in progress, 409), IDTO_010 (Idempotency-Key reused with a different body, 422), IDTO_009 (insufficient idto credits, 402), IDTO_006 (too many requests, 429), IDTO_007 (service configuration issue on idto's side; contact [email protected] with the tranx_id, 500), IDTO_008 (upstream Aadhaar service busy, unavailable or timed out; retry shortly, 503), IDTO_103 (OTP generation temporarily blocked for this Aadhaar, 503). Only IDTO_202 is billed; every other code is free.