Gridlines UIDAI OVSE API

openapi: 3.2.0
info:
  title: Aadhaar UIDAI OVSE API
  version: '1.0'
  description: 'This is a suite of instant Aadhaar APIs containing verification and data extraction APIs which can be used for onboarding, eKYC and verification of Aadhaar details of users. Aadhaar verification API verifies Aadhaar details using the database of the UIDAI. Aadhaar OCR API extracts data of the fields present in a standard and a valid Aadhaar document.


    > Additon of new fields in all the APIs should be permissible.


    ### Boson API

    1) Call **Generate OTP** API with the Aadhaar number, if the given Aadhaar number is valid then a `transaction_id` is generated and OTP is sent to the mobile number registered/ linked with the given Aadhaar number.


    2) Now call **Submit OTP** API with the `transaction_id` and OTP obtained, which will fetch the Aadhaar details. In addition to this the client can also enter an optional 4-digit "share_code" of their choice which is used to encrypt the downloaded xml.'
  contact:
    name: OnGrid
    url: ongrid.in
    email: contact@ongrid.in
servers:
- url: https://api.gridlines.io
  description: Production
security:
- X-API-Key: []
tags:
- name: UIDAI OVSE
paths:
  /uidai-api/ovse/generate-qr:
    post:
      summary: Generate QR
      tags:
      - UIDAI OVSE
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    request_id: 58d60dd7-db2f-47c9-ac76-9f8ea1da5f4c
                    transaction_id: 9b4f99cd-b633-4cbc-860e-091530ce1c3d
                    status: 200
                    data:
                      code: '1000'
                      scan_uri: https://maadhaar.com/getIntent?value=XXXXXXX
                      transaction_id: 9b4f99cd-b633-4cbc-860e-091530ce1c3d
                      expires_at: 1772090413107
                    timestamp: 1772090353196
                    path: /uidai-api/ovse/generate-qr
                required:
                - request_id
                - transaction_id
                - status
                - timestamp
                - path
                properties:
                  request_id:
                    type: string
                  transaction_id:
                    type: string
                  status:
                    type: integer
                  data:
                    type: object
                    required:
                    - code
                    properties:
                      code:
                        type: string
                      scan_uri:
                        type: string
                      transaction_id:
                        type: string
                      expires_at:
                        type: integer
                  timestamp:
                    type: integer
                  path:
                    type: string
              examples:
                '1000':
                  value:
                    request_id: 58d60dd7-db2f-47c9-ac76-9f8ea1da5f4c
                    transaction_id: 9b4f99cd-b633-4cbc-860e-091530ce1c3d
                    status: 200
                    data:
                      code: '1000'
                      scan_uri: https://maadhaar.com/getIntent?value=XXXXXXX
                      transaction_id: 9b4f99cd-b633-4cbc-860e-091530ce1c3d
                      expires_at: 1772090413107
                    timestamp: 1772090353196
                    path: /uidai-api/ovse/generate-qr
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    request_id: e03baf1b-b860-4671-8360-ce0d7ffafa45
                    transaction_id: d7801a96-a520-48fa-940c-675cd993c2b1
                    status: 400
                    error:
                      code: BAD_REQUEST
                      message: Bad request.
                      type: https://gridlines.stoplight.io/#:~:text=400-,BAD_REQUEST,-Bad%20request.%20When
                      metadata:
                        fields:
                        - field: template_id
                          message: Template Id cannot be blank.
                    timestamp: 1772090462910
                    path: /uidai-api/ovse/generate-qr
                required:
                - request_id
                - transaction_id
                - status
                - timestamp
                - path
                properties:
                  request_id:
                    type: string
                  transaction_id:
                    type: string
                  status:
                    type: integer
                  error:
                    type: object
                    required:
                    - code
                    - message
                    - type
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      type:
                        type: string
                      metadata:
                        type: object
                        properties:
                          fields:
                            type: array
                            items:
                              type: object
                              properties:
                                field:
                                  type: string
                                message:
                                  type: string
                  timestamp:
                    type: integer
                  path:
                    type: string
              examples:
                TEMPLATE_ID_BLANK:
                  value:
                    request_id: b38fd8db-2bd5-4d0d-aa35-85029e0c3988
                    transaction_id: 861a15be-d9c7-4036-8cd2-56f1b0054cea
                    status: 400
                    error:
                      code: BAD_REQUEST
                      message: Bad request.
                      type: https://gridlines.stoplight.io/#:~:text=400-,BAD_REQUEST,-Bad%20request.%20When
                      metadata:
                        fields:
                        - field: template_id
                          message: Template Id cannot be blank.
                        - field: template_id
                          message: Invalid Template id.
                    timestamp: 1774242390533
                    path: /uidai-api/ovse/generate-qr
                INVALID_TEMPLATE_ID:
                  value:
                    request_id: a4b9a205-62ad-488b-8580-5331835b4ce8
                    transaction_id: 16f2d9aa-4e0d-49f0-8844-2d41ea655608
                    status: 400
                    error:
                      code: BAD_REQUEST
                      message: Bad request.
                      type: https://gridlines.stoplight.io/#:~:text=400-,BAD_REQUEST,-Bad%20request.%20When
                      metadata:
                        fields:
                        - field: template_id
                          message: Invalid Template id.
                    timestamp: 1774242374230
                    path: /uidai-api/ovse/generate-qr
                INVALID_EXPIRY_TIME_RANGE:
                  value:
                    request_id: 36b2f287-32d4-4cc6-9b2d-35a5f4080667
                    transaction_id: 98272569-a3d4-4d01-b9db-9e5901431d0b
                    status: 400
                    error:
                      code: BAD_REQUEST
                      message: Bad request.
                      type: https://gridlines.stoplight.io/#:~:text=400-,BAD_REQUEST,-Bad%20request.%20When
                      metadata:
                        fields:
                        - field: expiry_time_in_seconds
                          message: Invalid expiry time. Allowed range is 60 to 3600 seconds.
                    timestamp: 1774242421065
                    path: /uidai-api/ovse/generate-qr
                CONSENT_NOT_GIVEN:
                  value:
                    request_id: a192f5b0-0bae-4f92-b20b-803b491e3eee
                    transaction_id: b232e727-8720-4a2d-a00f-299a97b01377
                    status: 400
                    error:
                      code: CONSENT_NOT_GIVEN
                      message: Consent not provided.
                      type: https://gridlines.stoplight.io/#:~:text=400-,CONSENT_NOT_GIVEN,-Consent%20not%20provided
                    timestamp: 1772090565286
                    path: /uidai-api/ovse/generate-qr
      operationId: post-uidai-api-ovse-generate-qr
      x-stoplight:
        id: 30l8qo8ydpb0z
      requestBody:
        content:
          application/json:
            schema:
              type: object
              x-examples:
                Example 1:
                  template_id: '1'
                  expiry_time_in_seconds: 60
                  consent: Y
              required:
              - template_id
              - consent
              properties:
                template_id:
                  type: string
                  description: Each template ID maps specific Aadhaar data fields. Template ID “1” provides all fields. If you need specific fields only, contact the team to configure and share the relevant template ID.
                expiry_time_in_seconds:
                  type: integer
                  description: It is the expiry time of the QR intent. The default value is 300 seconds, and the allowed range is 60 to 3600 seconds.
                consent:
                  description: The consent of the client should also be provided as a string, "Y" for an YES and "N" for NO.
                  enum:
                  - Y
                  - N
            examples:
              Example 1:
                value:
                  template_id: '1'
                  expiry_time_in_seconds: 300
                  consent: Y
      parameters:
      - schema:
          type: string
          default: API-Key
        in: header
        name: X-Auth-Type
        description: API-Key
        required: true
      - schema:
          type: string
        in: header
        name: X-Reference-ID
        description: Reference ID
      x-internal: false
      security:
      - X-API-Key: []
      description: 'This API is the first step in the two-step process for extracting a client’s Aadhaar data from UIDAI. It accepts a `template_id` and generates a `transaction_id` and `scan_uri`. The `scan_uri` is used to generate a QR code for scanning via the Aadhaar app.


        The `scan_uri` field in the response contains the data needed to create a QR code. Use any QR code generator or library (eg: https://qrcode.tec-it.com/en) to convert this value into a QR code. The user can then scan the QR code to continue the verification process.


        Response Codes:


        | Sl | Status | Code | Description

        | ---- | -------|-------------------------------| -------------

        | 1 | 200 | 1000 | QR intent generated.'
  /uidai-api/ovse/status:
    get:
      summary: Fetch Status
      tags:
      - UIDAI OVSE
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  transaction_id:
                    type: string
                  status:
                    type: integer
                  data:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                  timestamp:
                    type: integer
                  path:
                    type: string
                x-examples:
                  Example 1:
                    request_id: 2585d15f-357e-4659-a9e4-aab528ce8863
                    transaction_id: ac1051bc-d856-4a26-ac01-58a979e73de7
                    status: 200
                    data:
                      code: '1005'
                      message: Face liveness verification failed after 3 attempts.
                    timestamp: 1778588059561
                    path: /uidai-api/ovse/status
              examples:
                '1001':
                  value:
                    request_id: 4168694d-2f07-46a2-9bea-f0d65fe2c987
                    transaction_id: d7ee1da2-f538-4adc-8206-e94bfb7e59c8
                    status: 200
                    data:
                      code: '1001'
                      message: Callback has been received successfully.
                      ovse_data:
                        resident_image: <base64-data>
                        resident_name: R**** A*****
                        local_resident_name: आर**** अ*****
                        care_of: 'S/O: R**** A*****'
                        local_care_of: 'XXX: R**** A*****'
                        dob: 19XX-05-XX
                        gender: MALE
                        address: 'S/O: R**** A*****'
                        regional_address: R******, U***** P*****
                        building: XX/XXX
                        street: N/A
                        locality: K****
                        landmark: N/A
                        vtc: R******
                        sub_district: R******
                        district: D******
                        state: U***** P*****
                        pincode: 2XXXXX
                        local_building: XX/XXX
                        local_street: N/A
                        local_locality: क****
                        local_landmark: N/A
                        local_vtc: र******
                        local_sub_district: र******
                        local_district: द******
                        local_state: उ***** प*****
                        local_po_name: र******
                        mobile: 70XXXXXX57
                        masked_mobile: XXXXXX57
                        email: r****@XXXXX.com
                        masked_email: r****@e*****.com
                        age_above18: 'Yes'
                        age_above50: 'No'
                        age_above60: 'No'
                        age_above75: 'No'
                        is_nri: 'No'
                        po_name: R******
                        enrolment_number: 29XXXXXXXXXXXX67
                        enrolment_date: 2023-XX-XXTXX:XX:XX
                        credential_issuing_date: 2026-XX-XXTXX:XX:XX
                    timestamp: 1772108858031
                    path: /uidai-api/ovse/status
                '1002':
                  value:
                    request_id: 240bde7f-214d-4839-8c95-a316af8940d8
                    transaction_id: d24ccb4b-296f-42ac-bc08-c861b88678f5
                    status: 200
                    data:
                      code: '1002'
                      message: Callback has not been received yet.
                    timestamp: 1772172149117
                    path: /uidai-api/ovse/status
                '1004':
                  value:
                    request_id: 2585d15f-357e-4659-a9e4-aab528ce8863
                    transaction_id: ac1051bc-d856-4a26-ac01-58a979e73de7
                    status: 200
                    data:
                      code: '1004'
                      message: User denied consent to share Aadhaar details.
                    timestamp: 1778588059561
                    path: /uidai-api/ovse/status
                '1005':
                  value:
                    request_id: 2585d15f-357e-4659-a9e4-aab528ce8863
                    transaction_id: ac1051bc-d856-4a26-ac01-58a979e73de7
                    status: 200
                    data:
                      code: '1005'
                      message: Face liveness verification failed after 3 attempts.
                    timestamp: 1778588059561
                    path: /uidai-api/ovse/status
                '1006':
                  value:
                    request_id: 2585d15f-357e-4659-a9e4-aab528ce8863
                    transaction_id: ac1051bc-d856-4a26-ac01-58a979e73de7
                    status: 200
                    data:
                      code: '1006'
                      message: Authentication process aborted by user.
                    timestamp: 1778588059561
                    path: /uidai-api/ovse/status
                '1007':
                  value:
                    request_id: 2585d15f-357e-4659-a9e4-aab528ce8863
                    transaction_id: ac1051bc-d856-4a26-ac01-58a979e73de7
                    status: 200
                    data:
                      code: '1007'
                      message: Face authentication failed due to mismatch with Aadhaar records..
                    timestamp: 1778588059561
                    path: /uidai-api/ovse/status
                '1008':
                  value:
                    request_id: 2585d15f-357e-4659-a9e4-aab528ce8863
                    transaction_id: ac1051bc-d856-4a26-ac01-58a979e73de7
                    status: 200
                    data:
                      code: '1008'
                      message: Biometric authentication is locked for this user.
                    timestamp: 1778588059561
                    path: /uidai-api/ovse/status
          headers: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    request_id: 8156e05b-67a0-43e3-a0a9-325e747ae289
                    transaction_id: d7ee1da2-f538-4adc-8206-e94bfb7e59c8
                    status: 400
                    error:
                      code: TRANSACTION_ALREADY_COMPLETED
                      message: Transaction already completed. Cannot do further operation on this transaction.
                      type: https://gridlines.stoplight.io/#:~:text=TRANSACTION_ALREADY_COMPLETED
                    timestamp: 1772172472617
                    path: /uidai-api/ovse/callback
                required:
                - request_id
                - transaction_id
                - status
                - timestamp
                properties:
                  request_id:
                    type: string
                  transaction_id:
                    type: string
                  status:
                    type: integer
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      type:
                        type: string
                  timestamp:
                    type: integer
                  path:
                    type: string
              examples:
                TRANSACTION_ALREADY_COMPLETED:
                  value:
                    request_id: 8156e05b-67a0-43e3-a0a9-325e747ae289
                    transaction_id: d7ee1da2-f538-4adc-8206-e94bfb7e59c8
                    status: 400
                    error:
                      code: TRANSACTION_ALREADY_COMPLETED
                      message: Transaction already completed. Cannot do further operation on this transaction.
                      type: https://gridlines.stoplight.io/#:~:text=TRANSACTION_ALREADY_COMPLETED
                    timestamp: 1772172472617
                    path: /uidai-api/ovse/callback
      operationId: get-uidai-api-ovse-status
      x-stoplight:
        id: iz8pipcxc1txd
      parameters:
      - schema:
          type: string
          default: API-Key
        in: header
        name: X-Auth-Type
        required: true
        description: API-Key
      - schema:
          type: string
        in: header
        name: X-Transaction-ID
        description: transaction_id
        required: true
      - schema:
          type: string
        in: header
        name: X-Reference-ID
        description: Reference ID
      requestBody:
        content: {}
      description: 'After the QR code is generated, the user must scan it using the Aadhaar app and provide consent to share their data. Once consent is given through the Aadhaar app, this API returns the Aadhaar data from UIDAI.


        Response Codes:


        | Sl | Status | Code | Description

        | ---- | -------|-------------------------------| -------------

        | 1 | 200 | 1001 | Callback received from UIDAI along with the data.

        | 2 | 200 | 1002 | Callback not yet received from UIDAI.

        | 3 | 200 | 1004 | User denied consent to share Aadhaar details.

        | 4 | 200 | 1005 | Face liveness verification failed after 3 attempts.

        | 5 | 200 | 1006 | Authentication process aborted by user.

        | 6 | 200 | 1007 | Face authentication failed due to mismatch with Aadhaar records.

        | 7 | 200 | 1008 | Biometric authentication is locked for this user.'
      x-internal: false
      security:
      - X-API-Key: []
components:
  securitySchemes:
    X-API-Key:
      name: X-API-Key
      type: apiKey
      in: header
x-stoplight:
  id: 8dcce5c38d8ec
x-internal: false