PAN Verification AI Agent / LLM
Identity and SecurityEverything an AI coding assistant needs to write a working PAN Verification integration without opening another page: endpoint, authentication, parameters, a real request, both response shapes and the platform rules it cannot infer from a single example. Copy the brief below and paste it into Claude, Cursor, GitHub Copilot, ChatGPT or any other agent.
Machine-readable spec — Markdown
# PAN Verification API — Way2API®
- **Endpoint:** `POST https://app.way2api.com/api/v1/pan/verify`
- **Auth:** `Authorization: Bearer YOUR_API_KEY` (or `X-API-Key: YOUR_API_KEY`)
- **Content-Type:** `application/json`
- **Category:** Identity and Security
- **Availability:** Available in India
- **Docs:** https://app.way2api.com/documentation/pan
## What it does
PAN Verification API — Verify a 10-character Permanent Account Number (PAN) issued by the Indian Income Tax Department. Essential for financial KYC, income tax compliance, and onboarding workflows in the banking, insurance, and lending sectors. Returns the PAN holder's full name, PAN status (Existing and Valid, Deactivated, etc.), category (Individual, Company, HUF, Trust, etc.), Aadhaar seeding status, and other detailed information. Validates the PAN format and checks it against official government records.
## Request body (application/json)
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `pan_number` | string | yes | 10-character PAN — format: [A-Z]{5}[0-9]{4}[A-Z] (e.g. ABCDE1234F) |
## Example request
```bash
curl -X POST https://app.way2api.com/api/v1/pan/verify \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pan_number":"ABCDE1234F"}'
```
## Success response — 200
```json
{
"status": "SUCCESS",
"status_code": 200,
"charged": true,
"success": true,
"message": "",
"message_code": "OK",
"order_id": "W2A1739512345abcdef01",
"data": {
"order_id": "W2A1739512345abcdef01",
"result": {
"pan_number": "ABCDE1234F",
"full_name": "ANANYA SHARMA",
"title": "",
"full_name_split": [
"",
"",
"ANANYA SHARMA"
],
"pan_status": "E",
"pan_status_desc": "EXISTING AND VALID",
"aadhaar_seeding_status": "Y",
"aadhaar_seeding_status_desc": "Seeded",
"pan_modified_date": null,
"category": "individual",
"client_id": "pan_advanced_v2_xxxxxxxxxxxxxxxxxxxx"
}
}
}
```
## Error response — 422
```json
{
"status": "SUCCESS",
"status_code": 422,
"charged": true,
"success": false,
"message": "Invalid PAN",
"message_code": "VERIFICATION_FAILED",
"order_id": "W2A1739512345abcdef01",
"data": {
"order_id": "W2A1739512345abcdef01",
"error_code": "VERIFICATION_FAILED",
"result": {
"pan_number": "ABCDE12340",
"full_name": "",
"title": "",
"full_name_split": [],
"pan_status": "",
"pan_status_desc": "",
"aadhaar_seeding_status": "",
"aadhaar_seeding_status_desc": "",
"pan_modified_date": null,
"category": "company"
}
}
}
```
## Integration rules
- Every response is JSON carrying `status`, `status_code`, `charged`, `success`, `message`, `message_code` and (once a call reaches the provider) `order_id`. The verification payload is under `data.result`.
- `charged` (boolean) is the authority on billing. Do NOT infer it from the HTTP status: `422` is returned both for input we rejected (not charged) and for a lookup the provider ran and billed us for that returned a negative result (charged).
- `message_code` is a fixed vocabulary — branch on it instead of parsing `message`. Values: `OK`, `ACCEPTED`, `PROVIDER_NO_RESPONSE`, `VERIFICATION_FAILED`, `NO_RECORD_FOUND`, `INVALID_INPUT`, `REQUEST_FAILED`, `MISSING_API_KEY`, `INVALID_API_KEY`, `INSUFFICIENT_BALANCE`, `NO_API_ACCESS`, `NOT_FOUND`, `RATE_LIMITED`, `INTERNAL_ERROR`, `PROVIDER_UNAVAILABLE`.
- `success` reports the verification outcome; `status` reports the ORDER lifecycle (`SUCCESS`/`PENDING`/`FAILED`). They differ on a charged negative result: the order completed and was billed while the verification did not pass.
- A failed verification is still a successful HTTP call — the outcome lives in the response body, so do not treat `200` as "verified".
- Status codes: `200` result returned, `202` pending or provider did not respond (both charged — quote the `order_id`), `401` missing/invalid key, `402` insufficient balance, `403` no access to this service, `422` see `charged`, `429` rate limited (honour the `Retry-After` header), `503` temporarily unavailable.
- Rate limits are per API key, per service, on a 1-minute sliding window.
- Load the API key from an environment variable or secret store. Never hard-code it, never commit it, and never ship it in client-side code — calls must be made from your backend.
Prompts to pair it with
- Write a production-ready PAN Verification integration in PHP using this spec, with error handling and retries.
- Given this spec, generate typed request/response models and a client class.
- Review my existing PAN Verification integration against this spec and list what I handle incorrectly.
⚠ Before you paste generated code
Never let an assistant hard-code your API key — load it from an environment variable or a
secret store, and call this endpoint from your backend only. A failed verification is still a
successful HTTP call, so check the success field in the body
rather than treating 200 as verified.