KYC API Integration in PHP, Node.js & Python
Working code to call a verification API in the three most common backend languages — plus error handling and production tips.
Every BILAPI verification API follows the same pattern: an HTTPS POST with your API key in a header and a small JSON body, returning JSON. Learn it once and you can call PAN, GST, bank, vehicle or Aadhaar checks the same way. The examples below verify a PAN using the PAN Plus endpoint.
Before you start
- Create an account and copy your API key from the console.
- Keep the key on your server in an environment variable — never in browser or mobile-app code.
- Test in the sandbox first; the request shape is the same in production.
The request
POST https://api.bilapi.com/v1/pan-plus-v2
X-Bilapi-Api-Key: <your_api_key>
Content-Type: application/json
{ "id_number": "ABCPS1234K" }PHP (cURL)
<?php
$ch = curl_init('https://api.bilapi.com/v1/pan-plus-v2');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'X-Bilapi-Api-Key: ' . getenv('BILAPI_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['id_number' => 'ABCPS1234K']),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$res = json_decode((string) $body, true);
if ($status === 200 && !empty($res['success'])) {
echo $res['data']['pan_details']['full_name'];
} else {
error_log('Verification failed: ' . ($res['message'] ?? "HTTP $status"));
}Node.js (fetch, Node 18+)
const res = await fetch('https://api.bilapi.com/v1/pan-plus-v2', {
method: 'POST',
headers: {
'X-Bilapi-Api-Key': process.env.BILAPI_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ id_number: 'ABCPS1234K' }),
signal: AbortSignal.timeout(30000),
});
const data = await res.json();
if (res.ok && data.success) {
console.log(data.data.pan_details.full_name);
} else {
console.error('Verification failed:', data.message || res.status);
}Python (requests)
import os
import requests
r = requests.post(
'https://api.bilapi.com/v1/pan-plus-v2',
headers={'X-Bilapi-Api-Key': os.environ['BILAPI_KEY']},
json={'id_number': 'ABCPS1234K'},
timeout=30,
)
data = r.json()
if r.ok and data.get('success'):
print(data['data']['pan_details']['full_name'])
else:
print('Verification failed:', data.get('message') or r.status_code)Handling responses and errors
- 200 with success: true — the verification succeeded; read the fields from data.
- 400 — the input is missing or malformed; fix it before retrying.
- 401 — the API key is missing or invalid.
- 402 — the wallet balance is too low; add funds.
- 422 / "no record found" — the request was valid but no matching record exists.
- 5xx or a timeout — a temporary problem; retry with backoff.
Production checklist
- Call the API from your backend only, so the key is never exposed.
- Set a timeout (around 30 seconds) and retry only on 5xx or timeouts — not on 4xx.
- Validate the input format before calling, so malformed values never cost a request.
- Log the request and response (with sensitive fields masked) for your audit trail.
- Capture the customer's consent where the check requires it.
