Home / Guides / Guides
Guides

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.

BILAPI20 Nov 20267 min read

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.
The same pattern works for all 160+ BILAPI endpoints — change the URL path and the JSON body, and keep the rest of your code.

Frequently asked questions

How do I call a KYC API from PHP?

Send an HTTPS POST with cURL: put your API key in the X-Bilapi-Api-Key header, send a JSON body, and decode the JSON response.

Can I use the KYC API from Node.js?

Yes — use fetch (built into Node 18+) or any HTTP client to POST JSON with your API key in the header.

Can I call the API from the browser or a mobile app?

No — keep your API key on your server and call the API from your backend, so the key is never exposed to users.

What should I do on a timeout?

Retry with backoff on timeouts and 5xx errors. Do not retry 4xx errors such as invalid input or a low balance — fix the cause first.

Related APIs

More guides

Build with BILAPI

One key, a free sandbox and a predictable JSON envelope across every endpoint.

Get your API key