Citizen Basic Info API | Smart Services ICPS

Request fields

Field	Description	Required
`nid_number`	Required string. Use the citizen NID number stored in the system.	Yes

Get basic information

POST /api/v1/citizen/basic-info

Example request

curl -X POST "https://www.mosarofhosen.top/api/v1/citizen/basic-info" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-API-SECRET: your_api_secret" \
  -d '{"nid_number":"1234567890"}'

Success response · HTTP 200

{
    "success": true,
    "message": "তথ্য পাওয়া গেছে",
    "package_used": "citizen_basic_info",
    "endpoint_key": "citizen_basic_info",
    "charged": 3.79999999999999982236431605997495353221893310546875,
    "balance": 996.200000000000045474735088646411895751953125,
    "data": {
        "nid_number": "1234567890",
        "name_bn": "নমুনা নাগরিক",
        "name_en": "Sample Citizen",
        "date_of_birth": "1990-01-01T00:00:00.000000Z",
        "gender": "male",
        "present_division": "Dhaka",
        "present_district": "Dhaka",
        "present_upozila": "Dhanmondi",
        "permanent_division": "Dhaka",
        "permanent_district": "Dhaka",
        "permanent_upozila": "Dhanmondi",
        "status_checked": true,
        "afis_status": "MATCHED",
        "lock_flag": "0",
        "voter_area": "Sample Voter Area",
        "voter_at": "Sample Center"
    }
}

Common error responses

The API returns JSON with the matching HTTP status. The message can vary according to the exact package, balance, citizen or file condition.

HTTP 401 Missing credentials

{
    "success": false,
    "message": "X-API-KEY and X-API-SECRET headers are required."
}

HTTP 403 IP not allowed

{
    "success": false,
    "message": "This server IP is not allowed for the API client."
}

HTTP 404 Citizen or file not found

{
    "success": false,
    "message": "সিটিজেন পাওয়া যায়নি"
}

HTTP 422 Package, balance or configuration error

{
    "success": false,
    "message": "No active API package was found. Purchase a package before using this service."
}

HTTP 429 Minute rate limit exceeded

{
    "success": false,
    "message": "Per-minute request limit exceeded.",
    "limit_type": "minute",
    "limit": 30,
    "used": 30,
    "remaining": 0,
    "retry_after_seconds": 42
}

Data protection: Citizen information must only be accessed and processed with proper authorization, consent and legal basis.