API reference — BusinessKYC.Com

Authentication

Every request carries a personal access token as a bearer credential. Tokens are shown once at creation — store them in your secret manager, not in source control.

curl https://businesskyc.com/api/v1/me \
  -H "Authorization: Bearer bkyc_your_token_here" \
  -H "Accept: application/json"

Check your balance

GET /api/v1/me

Returns the authenticated account and its current credit balance.

{
  "data": {
    "id": 12,
    "name": "Ananya Raghavan",
    "email": "ananya@example.com",
    "company_name": "Sample Traders Pvt Ltd",
    "credits_balance": 480
  }
}

List available checks

GET /api/v1/services

Returns every active check with its credit cost and the fields it expects, so you can build request payloads dynamically.

{
  "data": [
    {
      "code": "gstin_verify",
      "name": "GSTIN verification",
      "group": "business",
      "credit_cost": 2,
      "fields": [
        { "key": "gstin", "label": "GSTIN", "rules": "required|string|size:15" }
      ]
    }
  ]
}

Run a check

POST /api/v1/verify/{code}

Charges the credit cost, calls the source and returns the normalised result. The token needs the "verify" ability.

curl -X POST https://businesskyc.com/api/v1/verify/gstin_verify \
  -H "Authorization: Bearer bkyc_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"gstin":"33AABCS1429B1ZP"}'

Return filing history

POST /api/v1/verify/gst_return_filing

Every return filed by a taxpayer in one financial year, plus the monthly or quarterly (QRMP) election behind them — due dates differ between the two, so lateness cannot be judged without it. One check, one charge. "filing_frequency_source" is "registry" when the election came from GSTN and "inferred" when it was read off the periods actually filed.

curl -X POST https://businesskyc.com/api/v1/verify/gst_return_filing \
  -H "Authorization: Bearer bkyc_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"gstin":"33AABCS1429B1ZP","financial_year":"2024-25"}'

{
  "data": {
    "reference": "BK-3C7A9F2B1D",
    "service": "gst_return_filing",
    "status": "success",
    "credits_charged": 2,
    "result": {
      "gstin": "33AABCS1429B1ZP",
      "financial_year": "2024-25",
      "returns_found": 24,
      "returns_filed": 22,
      "filing_frequency": "Monthly",
      "filing_frequency_code": "M",
      "filing_frequency_source": "registry",
      "returns": [
        {
          "type": "GSTR3B",
          "period": "2025-03",
          "period_label": "Mar 2025",
          "filed_on": "2025-04-18",
          "status": "Filed",
          "is_filed": true,
          "arn": "AA330325000001Z"
        }
      ]
    }
  }
}

Registry change feed

GET /api/v1/gst/cancelled

Every registration change published for one state on one date — cancellations, amendments and new registrations. Not a per-taxpayer check, so it is not billed and needs only the "read" ability. Compare "returned_count" against "total_count", or read "complete": a short page otherwise looks exactly like a quiet day.

curl "https://businesskyc.com/api/v1/gst/cancelled?state=33&date=2025-06-02" \
  -H "Authorization: Bearer bkyc_your_token_here" \
  -H "Accept: application/json"

{
  "data": {
    "state": "33",
    "date": "2025-06-02",
    "total_count": 412,
    "returned_count": 412,
    "complete": true,
    "cancelled_count": 118,
    "changes": [
      {
        "gstin": "33AABCS1429B1ZP",
        "change_type": "C",
        "changed_on": "2025-06-02",
        "is_cancellation": true,
        "is_new_registration": false
      }
    ]
  }
}

Successful response

credits_balance reflects the balance after this call, so you never need a second request to track spend.

{
  "data": {
    "reference": "BK-8F2A1C4D9E",
    "service": "gstin_verify",
    "status": "success",
    "credits_charged": 2,
    "credits_balance": 478,
    "input": { "gstin": "33AABCS1429B1ZP" },
    "result": {
      "gstin": "33AABCS1429B1ZP",
      "legal_name": "Sample Traders Private Limited",
      "status": "Active",
      "state": "Tamil Nadu",
      "registration_date": "2019-07-12"
    },
    "error": null,
    "duration_ms": 184,
    "created_at": "2026-08-12T10:41:07+05:30"
  }
}

Errors

Standard HTTP status codes. A failed check still returns its reference so you can reconcile it later.

Status	Meaning	Credits charged
`401`	Missing, revoked or malformed token	No
`403`	Token lacks the "verify" ability, or the account is suspended	No
`402`	Insufficient credits — top up and retry	No
`422`	Validation failed, or the check returned no record	Only for "no record"
`429`	Rate limit exceeded (60 requests per minute)	No
`500`	Upstream provider error — credits are refunded automatically	Refunded

Ready to build?

Create an account

Run checks over HTTP