Get Parameter List

Endpoint Overview

GET /api/v1/digilocker/pull/parameters/{org_id}/{doc_type}

Description

This API endpoint retrieves the list of parameters required for a specific document type from DigiLocker for a given organization. It allows developers to dynamically fetch the necessary input parameters that must be provided when requesting document extraction from DigiLocker, ensuring that all required fields are collected before making a document pull request.

Key Benefits

Dynamically discover required parameters for different document types

Reduce failed document pull requests by ensuring all required fields are collected

Streamline integration with DigiLocker's document verification system

Enable building dynamic forms that adapt to different document requirements

Use Cases

Financial Services

Government Services

Education

Retrieve required parameters for PAN card verification during customer onboarding

Fetch necessary fields for income tax returns verification for loan applications

Get parameters needed for bank statement verification for credit assessment

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: `Bearer <your_token>`
Content-Type	Yes	Must be set to `application/json`

Path Parameters

Parameter	Type	Required	Description
org_id	String	Yes	The organization ID for which parameters are being retrieved
doc_type	String	Yes	The type of document for which parameters are needed (e.g., "PANCR", "ADHAR")

Request Body

This endpoint does not require a request body.

Process Response

Response Parameters

Parameter	Type	Description
data	Array	List of input parameter objects
data[].label	String	Label of the field (e.g., Aadhaar Number, PAN Number)
data[].paramname	String	Name of the parameter used in the request
data[].valuelist	String	Comma-separated sample list of possible values
data[].example	String	Example value for the input field
success	Boolean	Indicates if the API request was successful
status_code	Number	HTTP status code
message	String	Response message
message_code	String	Code representing the response message

Example Successful Response

{
  "data": [
    {
      "label": "Aadhaar Number",
      "paramname": "aadhaar_no",
      "valuelist": "123412341234,234523452345",
      "example": "123412341234"
    },
    {
      "label": "PAN Number",
      "paramname": "pan_no",
      "valuelist": "ABCDE1234F,FGHIJ5678K",
      "example": "ABCDE1234F"
    }
  ],
  "success": true,
  "status_code": 200,
  "message": "Success",
  "message_code": "success",
}

Possible Error Responses

Authentication Error

Invalid Parameters

Service Unavailable

{
  "success": false,
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or expired token provided"
}

This error occurs when the JWT token is invalid, expired, or not provided.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Use the display_name field to show user-friendly labels in your forms

Dynamically build input forms based on the returned parameters

Provide clear validation messages based on parameter requirements

Implement progressive disclosure to simplify complex forms

Code Samples

cURL

Python

Node.js

Related APIs

DigiLocker Document Pull API - Initiates document extraction using parameters obtained from this API

DigiLocker Document Status API - Checks the status of a document pull request

DigiLocker Document List API - Retrieves a list of available document types for an organization

Compliance and Legal Considerations

When collecting and processing document information through DigiLocker, ensure compliance with the Information Technology Act, 2000 and the Digital Locker Authority guidelines. User consent must be obtained before accessing their DigiLocker documents, and all data must be handled in accordance with privacy laws and regulations.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Get parameter List

Get Parameter List#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Request Body#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses