# DigiLocker (e-Aadhaar)

Use this endpoint to verify an Indian applicant with e-Aadhaar from DigiLocker. The applicant does not need to upload a document.
**How it works**
1. You send `form_id` and, optionally, `applicant_id`. Our system returns `confirmation_url`, `applicant_id`, and `verification_id`.
2. You redirect the applicant to `confirmation_url`. The applicant signs in to DigiLocker and gives consent to share e-Aadhaar.
3. DigiLocker returns the applicant to our system. Our system gets e-Aadhaar and adds this data to the applicant:
  - profile: first name, last name, date of birth, gender, and residence country `IN`;
  - address;
  - document of the `GOVERNMENT_ID` type with the masked Aadhaar number and the photo.
4. Our system creates a verification with `verification_id` from step 1. The verification uses the verification types of the form.
5. Our system redirects the applicant to the redirect URL of the form and sends the verification result to the callback URL of the form.

The applicant must complete the DigiLocker steps in 1 hour.
When you send `applicant_id`, our system updates the profile of this applicant and deletes the identity documents of the applicant that are not used in verifications. When you do not send `applicant_id`, our system creates a new applicant.
Our system charges the verification by the verification types of the form. The DigiLocker check is not charged separately.
To get the result, use the verification callback or `GET /verifications/{verification_id}`.

Endpoint: POST /services/in/digilocker/start
Version: 1.0
Security: API-Key

## Security:

  - `API-Key` (unknown)
    apiKey in header API-Key

## Request fields (application/json):

  - `form_id` (string, required)
    ID of the form. The form sets the verification types, the callback URL, and the redirect URL
    Example: a3f5c7e9b1d34f6a08b2c4d6e8f0a1b2c3d4

  - `applicant_id` (string)
    ID of an existing applicant. Optional. When it is not sent, our system creates a new applicant
    Example: 9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d

## Request examples:

  - `New applicant` (unknown)

  - `Existing applicant` (unknown)

## Response 200:

  - `200` (unknown)
    **OK**
The request was successful, and our system returned an expected response.
When `data` is `null`, our system could not start the DigiLocker session. Try again later.

## Response 200 fields (application/json):

  - `status` (string | integer)
    Result of the session start. `201` or `ok` — the session is started. Any other value — the session is not started, and `data` is `null`
    Example: 201

  - `data` (object | null)

  - `data.applicant_id` (string)
    ID of the applicant. When you did not send `applicant_id`, this is the ID of the new applicant. Our system creates the applicant after the applicant completes the DigiLocker steps
    Example: 9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d

  - `data.verification_id` (string)
    ID of the verification. Our system creates the verification after the applicant completes the DigiLocker steps
    Example: 5b4a3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f

  - `data.confirmation_url` (string)
    URL of the DigiLocker page. Redirect the applicant to this URL
    Example: https://digilocker.example.com/authorize?state=1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

## Response 403:

  - `403` (unknown)
    **Forbidden**
Service API is not available for your account.

## Response 403 fields (application/json):

  - `type` (string)
    Example: forbidden

  - `errors` (array)
    Example: []

## Response 404:

  - `404` (unknown)
    **Not Found**
The form or the applicant is not found.

## Response 404 fields (application/json):

  - `status` (string)
    Example: error

  - `errors` (array)

  - `errors.parameter` (string)
    Example: form_id

  - `errors.message` (string)
    Example: Form was not found

  - `type` (string)
    Example: not_found

## Response 422:

  - `422` (unknown)
    **Unprocessable Content**
The request parameters have an incorrect format.

## Response 422 fields (application/json):

  - `type` (string)
    Example: validation

  - `errors` (array)

  - `errors.parameter` (string)
    Example: form_id

  - `errors.message` (string)
    Example: Form ID is not valid

## Response 500:

  - `500` (unknown)
    **Internal Server Error**
This response indicates that our system encountered an unexpected condition that prevented it from fulfilling the request.

## Response 500 fields (application/json):

  - `type` (string)
    Example: internal_server

  - `errors` (array)

## Response 200 examples:

  - `Session is started` (unknown)

  - `Session is not started` (unknown)