Connexolve API — Documentation

Quickstart

Every endpoint follows the same pattern: POST JSON, get a verification envelope back.

1 Get a key

Email api@connexolve.in for a sandbox key (cnx_test_…). No setup, no card.

2 Call the sandbox

Hit sandbox.connexolve.in with your key. Responses are instant and deterministic — perfect for building.

3 Go live

Swap to api.connexolve.in and a cnx_live_… key. Top up your prepaid wallet and you're billing real verifications.

4 Track usage

Call GET /v1/usage any time for per-endpoint spend. Every call is logged with a verificationId.

cURL — sanctions screening (sandbox)

# Magic value "CLEAN PERSON" → clean; "SANCTIONED PERSON" → 3 matches
curl -X POST https://sandbox.connexolve.in/v1/screen/negative-diligence \
  -H "Authorization: Bearer cnx_test_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"CLEAN PERSON"}'

200 OK — universal response envelope

{
  "success": true,
  "verificationId": "cnxv_01KSPRP2H6RMMKQCMRENST5DHF",
  "endpoint": "screen.negative-diligence",
  "status": "completed",
  "data": { "clean": true, "matchCount": 0 },
  "billing": { "charged": false, "amount": 0, "currency": "INR" },
  "meta": { "environment": "test", "latencyMs": 12 }
}

Authentication

Bearer token on every request. Keys are environment-scoped and can't cross environments.

Key prefixes

cnx_test_… works only on sandbox. cnx_live_… works only on production. Using one on the wrong host returns CNX_KEY_ENVIRONMENT_MISMATCH.

Header

Authorization: Bearer cnx_live_…

Billing & the wallet

Prepaid, in paise, never a surprise. You only pay for conclusive results.

Prepaid wallet

Top up in advance. Each live call holds the price, then commits on success or releases on a retryable failure. Sandbox calls are always free.

What's billable

A successful verification is billed. A conclusive CNX_NO_RECORD_FOUND (422) is billed — it's a real answer. Transient errors (5xx, rate limits) are never billed.

Idempotency

Send Idempotency-Key to safely retry. A replayed key returns the original result and is never double-charged.

Insufficient balance

If your wallet can't cover a call you get 402 CNX_INSUFFICIENT_BALANCE before any provider is contacted — no partial charges.

Sandbox test values

The sandbox returns deterministic results for these inputs, so you can build and test every code path before going live — free.

Screening

name: "CLEAN PERSON" → clean.
name: "SANCTIONED PERSON" → 3 matches across sanctions lists.

PAN

pan: "AAAAA0000A" → success.
pan: "AAAAA9999A" → no-record (billable on live).

Forced source-down

Any field set to "ZZZZZ0000Z" → CNX_SOURCE_UNAVAILABLE (retryable, never billed). Test your retry logic.

Mobile

mobile: "9000000001" → MNRL revocation hit. Other numbers → not found.

Error codes

Every error returns the same envelope with a stable error.code. Retryable errors are never billed.

Client errors (4xx)

CNX_INVALID_INPUT (400) · CNX_INVALID_IDENTIFIER (400) · CNX_AUTH_INVALID (401) · CNX_KEY_ENVIRONMENT_MISMATCH (401) · CNX_INSUFFICIENT_BALANCE (402)

No record (422)

CNX_NO_RECORD_FOUND — a conclusive answer that the record doesn't exist. This is billed on live, because it's a real result.

Retryable (5xx / 429)

CNX_RATE_LIMITED (429) · CNX_SOURCE_UNAVAILABLE (503) · CNX_SOURCE_TIMEOUT (504). Safe to retry; never billed.

Idempotent retries

Add an Idempotency-Key header so a retry returns the original result instead of charging twice.