Ration Card Verification

Endpoint Overview

POST /api/v1/ration-card/verify

Description

This API endpoint allows you to verify ration card details across various states in India. It retrieves comprehensive information about the ration card including state details, district information, Fair Price Shop (FPS) identifier, scheme name, and details of all members associated with the ration card. The verification helps confirm the authenticity of the ration card and provides visibility into the beneficiaries linked to it.

Key Benefits

Instant verification of ration card validity across multiple states

Access to complete household member details associated with the ration card

Verification of scheme type and Fair Price Shop allocation

Identification of duplicate UID status for compliance checks

Use Cases

Financial Services

Government Services

Social Impact

KYC verification for loan applications from rural and semi-urban customers

Income and address verification for bank account opening

Subsidy eligibility verification for financial inclusion programs

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	Bearer token for authentication (JWT)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	The ration card number to be verified
state_portal	String	Conditional	State name for verification. Required only for Karnataka state (value: "karnataka"). For all other states, use "central" or omit this parameter

Example Request

{
    "id_number": "10140100006004000000",
    "state_portal": "central"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all the verification details
data.client_id	String	Unique identifier for the client request
data.id_number	String	The ration card number that was verified
data.state_portal	String	The state portal used for verification
data.state_name	String	Name of the state the ration card belongs to
data.district_name	String	Name of the district the ration card belongs to
data.fps_id	String	Fair Price Shop identifier associated with the ration card
data.scheme_name	String	Name of the scheme (e.g., PHH, AAY)
data.dup_uid_status	String	Status indicating if duplicate UIDs exist
data.member_details_list	Array	List of members associated with the ration card
data.member_details_list[].member_id	String	Unique identifier for each member
data.member_details_list[].member_name	String	Name of the member
data.member_details_list[].uid_status	Boolean	UID status of the member
data.member_details_list[].masked_aadhaar	String	Masked Aadhaar number (if available)
data.member_details_list[].relationship_name	String	Relationship to the ration card holder
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code representing the response message

Example Successful Response

{
    "data": {
        "client_id": "ration_card_LqcwSxyPrnrKsnJjRwaD",
        "id_number": "10140100006004000005",
        "state_portal": "central",
        "state_name": "BIHAR",
        "district_name": "MUZAFFARPUR",
        "fps_id": "121600100663",
        "scheme_name": "PHH",
        "dup_uid_status": "No",
        "member_details_list": [
            {
                "member_id": "1014010000600400000501",
                "member_name": "JAVANTI DEVI",
                "uid_status": true,
                "masked_aadhaar": null,
                "relationship_name": "SELF"
            },
            {
                "member_id": "1014010000600400000502",
                "member_name": "RAMLAKSHAN RAI",
                "uid_status": true,
                "masked_aadhaar": null,
                "relationship_name": "NOT AVAILABLE"
            },
            {
                "member_id": "1014010000600400000504",
                "member_name": "SAJAN KUMAR",
                "uid_status": true,
                "masked_aadhaar": null,
                "relationship_name": "SON"
            },
            {
                "member_id": "1014010000600400000505",
                "member_name": "VIRSAN KUMAR",
                "uid_status": true,
                "masked_aadhaar": null,
                "relationship_name": "SON"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Ration Card

Authentication Error

State Portal Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid ration card number",
    "message_code": "invalid_ration_card"
}

Returned when the provided ration card number is invalid or not found in the system.

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

Validate and sanitize all input parameters before sending to the API

Implement proper error handling to manage API failures gracefully

User Experience Guidelines

Provide clear instructions for users to enter the correct ration card format

Implement state-specific validation rules for ration card numbers

Display member details in a structured, easy-to-read format

Include tooltips explaining scheme names and other technical terms

Code Samples

cURL

Python

Node.js

Related APIs

PAN Card Verification: Verify PAN card details for identity verification

Aadhaar Verification: Verify Aadhaar card details for identity verification

Voter ID Verification: Verify voter ID details for identity verification

Address Verification: Verify address details using various government IDs

Compliance and Legal Considerations

This API provides access to sensitive personal information and is subject to data protection regulations. Ensure you have proper consent from users before verifying their ration card details. The data should be used only for the specific purpose for which consent was obtained and should be stored securely. Usage of this API may be subject to regulations under the Information Technology Act, 2000 and various state-specific PDS regulations.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ration-card/verify' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "10140100006004000000", "state_portal": "central" }'

{ "data": { "client_id": "ration_card_LqcwSxyPrnrKsnJjRwaD", "id_number": "10140100006004000005", "state_portal": "central", "state_name": "BIHAR", "district_name": "MUZAFFARPUR", "fps_id": "121600100663", "scheme_name": "PHH", "dup_uid_status": "No", "member_details_list": [ { "member_id": "1014010000600400000501", "member_name": "JAVANTI DEVI", "uid_status": true, "masked_aadhaar": null, "relationship_name": "SELF" }, { "member_id": "1014010000600400000502", "member_name": "RAMLAKSHAN RAI", "uid_status": true, "masked_aadhaar": null, "relationship_name": "NOT AVAILABLE" }, { "member_id": "1014010000600400000504", "member_name": "SAJAN KUMAR", "uid_status": true, "masked_aadhaar": null, "relationship_name": "SON" }, { "member_id": "1014010000600400000505", "member_name": "VIRSAN KUMAR", "uid_status": true, "masked_aadhaar": null, "relationship_name": "SON" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Ration Card Verification

Ration Card Verification#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Ration Card Verification

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples