Developer APIs

Welcome to the National Farmer ID Registry (NFD) developer integration documents. Our simple APIs allow external clients and mobile integrations (Android/iOS) to log users in securely and generate smart, bilingual high-resolution PDF or JPEG farmer identification cards.

Authentication Scheme: Secure session identifiers cookie-based verification (`PHPSESSID`). Upon calling the user login API, the response returns a `session_id`. For subsequent restricted endpoints (such as card data generation), you must pass the session cookie back in the headers.

User Authentication API

Logs a registered farmer in using their mobile number and password credentials. Starts a secure PHP session and returns the session token identifier alongside the user profile details.

POST /api/login.php

Request Parameters

Accepts both standard JSON payloads and form POST parameters.

Parameter	Type	Status	Description
mobile	string	Required	The farmer's registered 10-digit mobile number.
password	string	Required	The plain-text account password.

Request Example (JSON)

{
  "mobile": "9876543210",
  "password": "farmer_secure_pass123"
}

Response Example (200 OK)

{
  "success": true,
  "message": "Login successful",
  "session_id": "o12k4m8n3b5v9c1x7z0l3k4j5h",
  "user": {
    "id": 48,
    "fullname": "Ramesh Kumar",
    "mobile": "9876543210",
    "state": "Uttar Pradesh",
    "wallet_balance": 250.00
  }
}

Error Response Example (401 Unauthorized)

{
  "success": false,
  "error": "Invalid mobile number or password."
}

Card Generation API

Generates high-resolution smart card graphics (front and back templates). Draws user details, photo, and dynamic QR Code in both Devanagari (local state languages) and English. If fetching a new card, it accesses the external portal and deducts balance from the user's wallet. Otherwise, it retrieves the cached response for free if a `download_id` is supplied.

POST /api/generate_card.php

Authorization Required: Requires the active session cookie inside request headers: Cookie: PHPSESSID=your_session_id.

Request Parameters

Accepts JSON payload or form variables. State Name and Aadhaar are required only when doing a fresh fetch (i.e. without download_id).

Parameter	Type	Status	Description
download_id	integer	Optional	Retrieve an existing card download record from history for free (No balance deducted).
state_name	string	Optional*	State Farmer registry to target (e.g. `"Uttar Pradesh"`, `"Maharashtra"`). Required for new fetches.
aadhar	string	Optional*	12-digit Aadhaar Card number of the farmer. Required for new fetches.

Request Example: Fresh Card Fetch (JSON)

{
  "state_name": "Uttar Pradesh",
  "aadhar": "123456789012"
}

Request Example: From History (JSON)

{
  "download_id": 124
}

Response Example (200 OK)

{
  "success": true,
  "farmerID": "UP-FARM-998811",
  "front_card_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
  "back_card_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
  "farmer_data": {
    "farmerID": "UP-FARM-998811",
    "name_en": "Ramesh Kumar",
    "name_local": "रमेश कुमार",
    "gender": "MALE",
    "dob": "15/08/1984",
    "mobile": "9876543210",
    "aadhar": "XXXX-XXXX-1234",
    "state": "Uttar Pradesh",
    "address": "Village Kalan, District Meerut, Uttar Pradesh",
    "land_details": [
      {
        "district": "Meerut",
        "subDist": "Meerut",
        "village": "Kalan",
        "sno": "123",
        "area": "1.250",
        "khata": "123",
        "khasra": "456"
      }
    ]
  }
}

Error Response Example (401 Unauthorized)

{
  "success": false,
  "error": "Unauthorized. Please log in first."
}

Verify Card Details API

Retrieves the exact raw API verification response of the farmer ID card directly from the external registry. If it is a first-time fetch, it charges the user's wallet. If it's a re-download/lookup, the balance is not deducted.

POST /api/verify_card_details_for_api.php

Authorization Required: Requires the active session cookie inside request headers: Cookie: PHPSESSID=your_session_id.

Request Parameters

Accepts both standard form variables and JSON payload parameters.

Parameter	Type	Status	Description
state_name	string	Required	State Farmer registry to target (e.g. `"Uttar Pradesh"`, `"Maharashtra"`).
aadhar	string	Required	12-digit Aadhaar Card number of the farmer.

Request Example (JSON)

{
  "state_name": "Uttar Pradesh",
  "aadhar": "123456789012"
}

Response Example (200 OK)

{
  "data": {
    "farmerDetails": {
      "aadhaarNameMatchScore": 98,
      "aadharVerified": false,
      "centralId": "72307033213",
      "farmerDob": "1976-12-31T18:30:00.000Z",
      "farmerNameEn": "Parmar Amarsinh Shakrabhai",
      "farmerNameLocal": "પરમાર અમરસિંહ શકરાભાઇ",
      "farmerMobileNumber": "9723242847",
      "farmerAadharMask": "**** **** 4003",
      "farmerExtendedRegistry": {
        "ferFarmerPhotograph": "/9j/4AAQSkZJRgAB..."
      }
    },
    "farmerLandOwnerShips": [
      {
        "extentAssignedAreaInHectare": 0.2627,
        "khataNumber": "486",
        "surveyNumber": "708",
        "ownerNamePerRor": "અમરસિંહ શકરાભાઈ ૫રમાર"
      }
    ]
  }
}

Error Response Example (401 Unauthorized)

{
  "success": false,
  "error": "Unauthorized. Please log in first."
}