API Documentation • Main API + Balance API

Base URL

https://api.example.com

Authentication

Query param api

Responses

JSON (UTF‑8)

Main API

GET

Send a request with your key and input parameters. Credits are deducted only on successful upstream response.

Endpoint

GET https://api.example.com/seba/api/paid_api?key=YOUR_KEY&num=NID&dob=DOB

Query Parameters

Name	Type	Required	Description
`key`	string	Yes	Your API key.
`num`	string	Yes	Target NID (or number as per your integration).
`dob`	string	Yes	DOB or content required by the upstream.

Notes

All inputs are URL‑encoded.
If the key is expired or balance is 0, you’ll get an error JSON.
On success, balance is decremented according to your configured cost.

Response Samples

200 OK Success

{
  "status": "success",
  "message": "Request completed",
  "cost_applied": 5,
  "remaining_credits": 10,
  "total_used": 8,
  "last_used_at": "2025-10-03 13:55:33",
  "data_response": {
    "ok": true,
    "source": {
      "requested_nid": "9164397557",
      "requested_dob": "1985-10-17"
    },
    "fields": {
      "nid": "9164397557",
      "pin": "19851591904000321",
      "voter_number": "151739000126",
      "voter_area": "ওয়াপদা কলোনী",
      "name_bn": "ববিতা রানী সরকার",
      "name_en": "BABITA RANI SARKAR",
      "dob": "1985-10-17",
      "father": "স্বদেশ চন্দ্র সরকার",
      "mother": "মলিনা রানী সরকার",
      "spouse": "উৎপল সরকার",
      "gender": "female",
      "education": "উচ্চ মাধ্যমিক বা সমতুল্য",
      "blood_group": "O+",
      "birth_place": "কুমিল্লা",
      "religion": "Hindu"
    },
    "addresses": {
      "present_address": "বাসা/হোল্ডিংঃ পানি উন্নয়ন বোর্ড, এ - ৬, \n গ্রাম/রাস্তাঃ ওয়াপদা কলোনী,\n মৌজা/মহল্লাঃ চান্দগাঁও,\n \n ইউনিয়ন/ওয়ার্ডঃ ওয়ার্ড নং-০৪,\n পোষ্ট অফিসঃ চান্দগাঁও, \n পোষ্ট কোডঃ ৪২১২,\n উপজেলাঃ চাঁদগাও, \n জেলাঃ চট্টগ্রাম,\n অঞ্চলঃ চট্টগ্রাম, \n বিভাগঃ চট্টগ্রাম।",
      "permanent_address": "বাসা/হোল্ডিংঃ কাসেড্ডা,\n গ্রাম/রাস্তাঃ কাসেড্ডা,\n মৌজা/মহল্লাঃ ,\n \n ইউনিয়ন/ওয়ার্ডঃ ওয়ার্ড নং-০৭,\n \n পোষ্ট অফিসঃ বড়ুরা,\n পোষ্ট কোডঃ ৩৫৬০,\n উপজেলাঃ বরুড়া, \n জেলাঃ কুমিল্লা,\n অঞ্চলঃ কুমিল্লা,\n বিভাগঃ চট্টগ্রাম।"
    },
    "images": {
      "user_photo": {
        "url": "https://prportal.nidw.gov.bd/file-63/3/6/4/0951a950-a32f-4211-92f5-91f1dd4ea739/Photo-0951a950-a32f-4211-92f5-91f1dd4ea739.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=fileobj%2F20251003%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20251003T075506Z&X-Amz-Expires=120&X-Amz-SignedHeaders=host&X-Amz-Signature=4fa94fe75e5bc0bff25a512ae41a6d2c0401c84c79d35aefef4c726b841f74e8",
        "expires_at_utc": "2025-10-03T07:57:06Z"
      }
    }
  }
}

404 / 422 Wrong input / not found

{"ok":false,"error":"No data found for the provided NID/DOB.",
"source":{"requested_nid":"9164337557","requested_dob":"1985-10-17"}}

502 / 503 Upstream error

{"ok":false,"error":"Upstream HTTP 302","raw":"\r\n"}

cURL

curl -G \
  "https://api.example.com/api/send" \
  --data-urlencode "api=YOUR_KEY" \
  --data-urlencode "num=9164397557" \
  --data-urlencode "dob=1985-10-17"

PHP


$url = "https://api.example.com/seba/api/paid_api?key=YOUR_KEY&num=9164397557&dob=1985-10-17";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
curl_close($ch);
echo $res;

Check Balance API

GET

Quickly retrieve the current state of a specific API key.

Endpoint

GET https://api.example.com/seba/api/check_balance.php?format=json&api_key=YOUR_KEY

Query Parameters

Name	Type	Required	Description
`api_key`	string	Yes	API key to inspect.
`format`	string	No	Use `json` to get a JSON response.

Response (OK)

{
  "ok": true,
  "key": {
    "api_key": "sk-******",
    "status": "Active",
    "remaining": 120,
    "used": 8,
    "last_used_at": "2025-10-01 18:22:40",
    "expires_at": 1767225600,
    "expires_at_human": "2025-12-31 00:00:00"
  }
}

Response (Invalid Key)

{"ok":false,"error":"Invalid API key"}

cURL


curl "https://api.example.com/seba/api/check_balance.php?format=json&api_key=YOUR_KEY"

PHP


$url = "https://api.example.com/seba/api/check_balance.php?format=json&api_key=YOUR_KEY";
echo file_get_contents($url);

JavaScript (fetch)


fetch("https://api.example.com/seba/api/check_balance.php?format=json&api_key=YOUR_KEY")
  .then(r => r.json())
  .then(console.log)
  .catch(console.error);

Common Errors & Policies

HTTP Status Mapping

Status	When
200	Successful request.
401/403	Missing/invalid key or expired key.
404/422	Wrong input / Not found.
429	Rate limit exceeded (if configured).
5xx	Upstream or server error.

Best Practices

Always URL‑encode query parameters.
Retry on 5xx with exponential backoff; don’t retry on 4xx.
Cache successful responses if your use‑case allows.
Protect your API key; avoid client‑side exposure.

Security: Keep keys confidential. Rotate compromised keys from the admin panel.