API Documentation & Quickstart | FinHub by Habilelabs

Documentation

A REST API for KYC, bank, GST and identity verification. JSON in, JSON out, two auth headers — most teams make their first call in under 30 minutes.

Book Demo

Browse the APIs

api · POST /v1/kyc/verify

POST /v1/kyc/verify

Authorization: Bearer sk_live_••••

{ "pan": "XXXXX1234F", "consent_artifact": "ca_9f2c…" }

Quickstart

From signup to first verification in four steps

Every FinHub API shares the same authentication, request shape and response envelope — integrate once, then adding the next API is just a new endpoint path.

Get your credentials

Sign up and generate an api_key and api_secret from the customer dashboard. One credential pair works across every verification API on the platform.

Authenticate your requests

Send the api_key and api_secret headers with every call. There are no OAuth flows or token refreshes — two headers and you're authenticated.

Call your first API

POST a JSON body to a /v1 endpoint such as bank-penny-drop. You'll get a structured JSON envelope back with the verification result in the data field.

Go live

Validate your flows against test cases, load production credits, and switch to live credentials. Most teams make their first production call in under 30 minutes.

Authentication

Two headers on every request

Every request to the FinHub API carries two headers: api_key, a distinct 10-digit number that identifies your account, and api_secret, a 256-bit hash that proves the request is yours. Both are issued from the customer dashboard, where you can also rotate them.

Treat the api_secret like a password: keep it server-side, never ship it in mobile or browser code, and rotate it immediately if you suspect exposure.

Base URL & Conventions

Plain REST, predictable envelope

The API is RESTful and uses standard HTTP methods. All requests and responses are JSON (UTF-8), and endpoints live under versioned /v1 paths.

Every response arrives in the same envelope: data (the result), status (SUCCESS, ERROR or FAILED), errdata, message, plus requestid and sequenceId for tracing calls across logs and support tickets.

# Illustrative example — values are placeholders
curl -X POST https://api-tejas.finhub.habilelabs.io/v1/bank-penny-drop \
  -H "api_key: 1234567890" \
  -H "api_secret: <your-256-bit-secret>" \
  -H "Content-Type: application/json" \
  -d '{ "accNumber": "50100123456789", "ifscNumber": "HDFC0001234" }'

# Trimmed success response
{
  "data": {
    "accountExists": true,
    "nameAtBank": "RAHUL SHARMA"
  },
  "status": "SUCCESS",
  "errdata": null,
  "message": "Account verified",
  "requestid": "9f2c1e7a-41b8",
  "sequenceId": "104"
}

Illustrative penny-drop verification call. Field values are placeholders — your portal reference documents the exact schema per API.

Errors & Limits

HTTP status codes and rate limits

The API uses conventional HTTP status codes; anything beyond the transport result is described in the response envelope.

Code	Name	When you'll see it
200	OK	The request succeeded. Check the `status` field in the envelope — `SUCCESS`, `ERROR` or `FAILED` — for the verification outcome.
400	Bad Request	The JSON body is malformed or a required field (for example accNumber or ifscNumber) is missing or invalid.
401	Unauthorized	The `api_key` or `api_secret` header is missing or incorrect. Regenerate credentials from the dashboard.
403	Forbidden	Your credentials are valid but this API isn't enabled for your account, or your credit balance is exhausted.
404	Not Found	The endpoint path or version doesn’t exist. Check the /v1 path against the reference in your portal.
500	Internal Server Error	Something failed on FinHub's side. Retry with backoff, and share the `requestid` with support if it persists.

HTTP status codes returned by the FinHub API.

Rate limits & credits. There is no fixed request-per-second limit. Usage is governed by the credits allocated to your account — each verification call consumes credits, and your live balance is visible in the dashboard. Top up credits to scale throughput; a 403 signals an exhausted balance.

Looking for the full reference? Per-endpoint schemas, sandbox credentials and SDKs live in the customer portal once you're provisioned — book a demo and our team will set you up with access.

Keep Exploring