Introduction #

Aptlab is a REST API for verifying that a piece of data is well-formed. It covers 29 types across identity documents, business registrations, financial instruments, contact details and web data. Every type is validated with its real structural rules and, where one exists, its actual check digit.

The API has a small surface. Base URL for all requests:

https://api.aptlab.dev/v1

Requests and responses are JSON. Every response carries a top-level ok boolean and an X-Request-Id header you can quote in support threads.

Quickstart #

Verify a GSTIN. Substitute your key for $APTLAB_KEY.

curl -X POST https://api.aptlab.dev/v1/verify/gstin \
  -H "Authorization: Bearer $APTLAB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "29AAECS1234K1Z9"}'

A GET works too, which is handy for a quick check from a shell:

curl "https://api.aptlab.dev/v1/verify/ifsc?value=HDFC0000123" \
  -H "Authorization: Bearer $APTLAB_KEY"

Authentication #

Pass your key as a bearer token:

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

An X-API-Key header is accepted as an alternative. Keys are hashed at rest — the plaintext is shown once, at creation, and cannot be recovered afterwards. Rotate rather than recover.

Key scoping #

A key can be restricted to a subset of types with allowedTypes. Use this to keep high-sensitivity types away from keys that ship anywhere near a client. Requests outside a key's scope return 403 type_not_permitted.

{
  "name": "web-signup-form",
  "plan": "growth",
  "allowedTypes": ["email", "phone", "pincode"]
}

Result envelope #

Every verification returns the same shape regardless of type, so client code branches once and works for all 29.

On null checks #

A check set to null was not evaluated — either the option was off, or a network lookup timed out. It is never a failure. Treat null as "unknown" and decide for yourself whether to escalate.

On confidence #

Confidence reflects how hard the value would be to fake by accident. An IBAN scores 0.95 — MOD 97-10 catches essentially every transposition. An Indian bank account number scores 0.5, because no checksum exists to run. Gate expensive downstream verification on this number rather than treating every pass as equal.

Verify by type #

Body parameters

Example

{
  "value": "[email protected]",
  "options": { "checkMx": true }
}

Verify with detection #

Omit the type and Aptlab infers it, verifies against the best match, and tells you what else it considered. Useful for a single "paste anything" field.

{
  "ok": true,
  "detected": {
    "type": "cin",
    "confidence": "inferred",
    "alternatives": []
  },
  "result": { /* standard envelope */ }
}

Pass type explicitly when you already know it. Detection is a convenience, not a substitute for a typed schema — an ambiguous 12-digit number could be an Aadhaar, a UAN or a card.

Detect type #

Returns the ranked candidates without verifying anything.

{
  "ok": true,
  "value": "29AAECS1234K1Z9",
  "candidates": [
    { "type": "gstin", "label": "GSTIN", "category": "Business" }
  ]
}

Batch verify #

Verify a whole record in one round trip. Items are independent — each may set its own type and options, and one bad item never fails the request. Every item counts as one verification against your quota.

{
  "items": [
    { "id": "pan_field",   "type": "pan",  "value": "ABCPD1234E" },
    { "id": "gst_field",   "type": "gstin", "value": "29AAECS1234K1Z9" },
    { "id": "email_field", "value": "[email protected]" }
  ]
}

{
  "ok": true,
  "summary": {
    "submitted": 3,
    "valid": 3,
    "invalid": 0,
    "errored": 0,
    "validRate": 1
  },
  "results": [
    { "id": "pan_field", "ok": true, "detected": false,
      "result": { /* standard envelope */ } }
  ]
}

Per-plan batch ceilings: 25 (Sandbox), 250 (Growth), 1,000 (Scale). Exceeding one returns 400 batch_limit_exceeded with the limit in error.details.

Metadata #

Unauthenticated and unmetered. Useful for building a dynamic form.

/v1/whoami echoes back which key you presented, its plan, its scope and its month-to-date usage — the fastest way to confirm a deploy picked up the right credential.

Key management #

These endpoints require your admin key, not a regular API key.

{
  "ok": true,
  "key": {
    "id": "key_8f2c1ab90d3e4c77",
    "name": "web-signup-form",
    "plan": "growth",
    "keyPrefix": "pk_live_a9Kd...",
    "allowedTypes": ["email", "phone"],
    "active": true
  },
  "secret": "pk_live_a9Kd…",
  "warning": "Store this secret now. It cannot be retrieved again."
}

Revoking is immediate and irreversible. Requests with a revoked key return 403 api_key_revoked.

Type reference #

All supported types, their options, and what each one can actually prove. Click a row to open it in the playground.

Reason codes #

reasons is a stable, machine-readable list. Match on these strings rather than on human-readable text.

Errors #

Errors share one shape:

{
  "ok": false,
  "requestId": "req_9c41a7f2b8d3e05a",
  "error": {
    "code": "unsupported_type",
    "message": "Unsupported verification type \"passport_uk\".",
    "details": { "supported": ["email", "phone"] }
  }
}

Rate limits #

Every metered response carries the current window state:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1785312000
Retry-After: 41          # only on 429

Retry 429 with exponential backoff, honouring Retry-After. Monthly quotas reset at 00:00 UTC on the 1st.

Data handling #

Verification is stateless. Values are held in memory for the life of the request and are not written to durable storage.

Redacted types

For aadhaar, card, bank_account and password, the response input is replaced with [redacted] and meta carries a masked form instead. These values never appear in request logs.

What each type can prove