Get Policy Documents

Endpoint Overview

GET /api/v1/pmfby/policy/get-policy-document

Description

The PMFBY Policy Document Retrieval API enables retrieval of insurance policy certificates for farmers enrolled under the Pradhan Mantri Fasal Bima Yojana (PMFBY) scheme. This endpoint provides secure access to policy documents organized by crop season (Kharif/Rabi) and year, along with pre-signed URLs for direct document download.

This API is designed for agricultural insurance platforms, government portals, and financial institutions that need to provide farmers with instant access to their crop insurance documentation. The endpoint returns comprehensive policy information including farmer details, policy IDs, and time-limited secure document links.

Key Benefits

Instant Document Access: Retrieve all policy documents for a farmer in a single API call

Organized by Season: Documents are categorized by crop season (Kharif/Rabi) and year for easy navigation

Secure Downloads: Pre-signed S3 URLs with 10-minute expiration ensure secure document access

Multi-Policy Support: Handle multiple policies across different seasons and years simultaneously

Use Cases

Agricultural Insurance

Government Services

Financial Services

Farmers accessing their crop insurance certificates through mobile apps or web portals

Insurance agents retrieving policy documents during field visits or customer service interactions

Verification of active insurance coverage before claim filing

Bulk document retrieval for policy renewal processes

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.app

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication (JWT format)
Content-Type	Yes	Must be set to `application/json`

Query Parameters

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier for the PMFBY policy holder (e.g., `pmfby_policy_blYs`)

Example Request

Note: This is a GET request with no request body required. The client_id is passed as a query parameter.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object for all policy document information
data.client_id	String	Unique identifier for the policy holder
data.mobile_number	String	Registered mobile number of the farmer
data.status	String	Status of the request (e.g., "success")
data.details	Object	Detailed information about the farmer and their policies
data.details.farmer_name	String	Name of the farmer/policy holder
data.details.farmer_category	String	Category of farmer (e.g., "owner", "tenant")
data.details.policy_document_details	Array	Array of policy documents grouped by crop season and year
policy_document_details[].crop_name	String	Crop season name (e.g., "kharif", "rabi")
policy_document_details[].year	String	Policy year
policy_document_details[].policy_documents	Array	Array of individual policy documents
policy_documents[].policy_id	String	Unique policy identification number
policy_documents[].document_link	String	Pre-signed S3 URL for document download (valid for 600 seconds)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable response message
message_code	String	Machine-readable message code

Example Successful Response

{
    "data": {
        "client_id": "pmfby_policy_blYs",
        "mobile_number": "9900000000",
        "status": "success",
        "details": {
            "farmer_name": "Krishna",
            "farmer_category": "owner",
            "policy_document_details": [
                {
                    "crop_name": "kharif",
                    "year": "2025",
                    "policy_documents": [
                        {
                            "policy_id": "0401092510601234567",
                            "document_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/pmfby_policy_document/pmfby_policy_blYspigeEFSqEotjorOb/0401092510604219918/policy_certificate-2025-12-30-082738842029.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20251230%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251230T082742Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=172d66061fc7b7f4e7c33aee9e38909e1f43cafa5c1464474add3a8b2f578f1c"
                        }
                    ]
                },
                {
                    "crop_name": "rabi",
                    "year": "2025",
                    "policy_documents": [
                        {
                            "policy_id": "0402092510602512345",
                            "document_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/pmfby_policy_document/pmfby_policy_blYspigeEFSqEotjorOb/0402092510602541821/policy_certificate-2025-12-30-082739858630.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20251230%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251230T082742Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=a2e5723c67f8b25734ed9e085d746881502fbe46c09b352c76d37fa891ed73f0"
                        }
                    ]
                }
            ]
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

Missing Parameters

{
    "data": null,
    "status_code": 404,
    "success": false,
    "message": "Policy not found for the provided client_id",
    "message_code": "not_found"
}

This error occurs when the provided client_id does not exist in the system or is invalid.

Integration Best Practices

Security Recommendations

Token Management: Store JWT tokens securely and implement automatic token refresh mechanisms before expiration

URL Expiration Handling: Document links expire after 600 seconds (10 minutes). Download or cache documents immediately after retrieval

HTTPS Only: Always use HTTPS for API calls to ensure encrypted data transmission

Client ID Protection: Treat client_id as sensitive information and never expose it in client-side code or logs

Rate Limiting: Implement exponential backoff for retry logic to handle rate limiting gracefully

User Experience Guidelines

Progress Indicators: Display loading states when fetching documents, as the API may retrieve multiple large PDF files

Document Preview: Provide thumbnail previews or document summaries to help users identify the correct policy

Season Organization: Group documents by crop season (Kharif/Rabi) in the UI to match the API response structure

Download Management: Inform users about the 10-minute validity of download links and provide re-fetch options

Offline Access: Consider caching downloaded documents locally for offline viewing when network connectivity is limited

Multi-language Support: Display crop season names in local languages alongside English terms

Code Samples

cURL

Python

Node.js

Java

Compliance and Legal Considerations

This API handles sensitive farmer data and official government insurance documents. Ensure compliance with the following:

Data Privacy: Comply with India's Digital Personal Data Protection Act (DPDP) and applicable state regulations when storing or processing farmer information

PMFBY Guidelines: Adhere to operational guidelines issued by the Department of Agriculture and Farmers Welfare for handling policy documents

Document Retention: Maintain policy documents as per insurance regulatory requirements, typically 5-7 years from policy expiration

Access Control: Implement role-based access control to ensure only authorized personnel can retrieve policy documents

Audit Trails: Maintain logs of all document access requests for compliance and dispute resolution purposes

Consent Management: Ensure proper farmer consent is obtained before sharing policy documents with third parties

URL Security: Document links expire after 10 minutes for security. Do not store or share these URLs beyond their validity period

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "pmfby_policy_blYs", "mobile_number": "9900000000", "status": "success", "details": { "farmer_name": "Krishna", "farmer_category": "owner", "policy_document_details": [ { "crop_name": "kharib", "year": "2025", "policy_documents": [ { "policy_id": "0401092510601234567", "document_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/pmfby_policy_document/pmfby_policy_blYspigeEFSqEotjorOb/0401092510604219918/policy_certificate-2025-12-30-082738842029.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20251230%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251230T082742Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=172d66061fc7b7f4e7c33aee9e38909e1f43cafa5c1464474add3a8b2f578f1c" } ] }, { "crop_name": "rabi", "year": "2025", "policy_documents": [ { "policy_id": "0402092510602512345", "document_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/pmfby_policy_document/pmfby_policy_blYspigeEFSqEotjorOb/0402092510602541821/policy_certificate-2025-12-30-082739858630.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20251230%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251230T082742Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=a2e5723c67f8b25734ed9e085d746881502fbe46c09b352c76d37fa891ed73f0" } ] } ] } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses