Build with SenseAI.

Explore the request patterns below. Contact Adept Sense for API credentials, SDK packages, and the current integration specification for your account.

The SenseAI API provides identity verification services including ID card OCR, face match, liveness verification, transliteration, and gender estimation. Requests use JSON or multipart form data, depending on the endpoint. Responses use JSON.

Authentication

All protected API requests require your custom API key passed in the x-api-key HTTP header:

x-api-key: YOUR_API_KEY

Contact Adept Sense for API access. Keep your keys secure — do not commit them to version control or expose them client-side.

Quickstart

Get from zero to your first successful API call in under 5 minutes.

import fs from 'node:fs/promises'
import FormData from 'form-data'

const form = new FormData()
form.append('front', await fs.readFile('./front.jpg'), 'front.jpg')
form.append('back', await fs.readFile('./back.jpg'), 'back.jpg')

const res = await fetch('https://api.adeptsense.tech/api/v1/ocr/nid', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.ADEPT_KEY
  },
  body: form
})

const result = await res.json()
console.log(result.ok) // true

Sandbox Environment

Use the sandbox base URL for all testing and development:

https://api-sandbox.adeptsense.tech/v1

Sandbox responses return realistic mock data with the same schema as production. Switch to the live URL when you're ready to go live.

Cookbook by vertical

Pick the vertical you're building for — the right endpoints, sample payloads, and order of operations for each integration pattern.

POST /api/v1/ocr/nid

SenseAI NID OCR supports Bangla and English cards, front/back extraction, PDF417 and TD1 MRZ reading, parent-name transliteration, father/spouse identification, configurable normalization, and cached results. Recognition can be trained for recurring errors in worn or photocopied cards. Explore the OCR workflow.

Extract structured identity fields from any government-issued ID card image — Bangladesh NID, passport, driver's license, voter ID, and more. The endpoint is named /ocr/nid for historical reasons but accepts any ID card format.

Request Body

Response — Success Example

{
  "ok":              true,
  "txId":            "TX_1773843146096_646FF71CAA17",
  "username":        "alice",
  "tokensRemaining": 99601,
  "tokensUsed":      2,
  "data": {
    "fields": {
      "name_bn": "রাজা আহমেদ",
      "name_en": "RAZA AHMED",
      "nid_number": "2025001221",
      "dob_en": "01 Sep 1980",
      "address_bn": "বাসা/হোল্ডিং: ১৩, গ্রাম/রাস্তা: আবাসিক কলোনী...",
      "father_or_husband_bn": "মোহাম্মদ আলী",
      "father_or_husband_en": "Mohammad Ali"
    },
    "normalized": {
      "dob_iso": "1981-01-01"
    }
  }
}

POST /api/v1/match/face/submit

Face Match evaluates facial structure and overall appearance. Reference-image recovery runs before comparison to address low-resolution, compressed government images. Appearance changes can still require review. Explore the matching workflow.

Submit a face matching task to compare reference and selfie images asynchronously.

Response — Submit Response

{
  "ok": true,
  "data": {
    "taskId": "5190bb5e-0839-49ad-9027-c66d03e64d6f",
    "status": "queued"
  }
}

GET /api/v1/match/face/result

Poll this endpoint with taskId to fetch the async face comparison results.

POST /api/v1/liveness/create

The SDK performs configured tasks and on-device capture checks, then sends a five-second video and its findings for a server verdict. Tasks, workflow and decision policies are controlled from the backend; tagged review examples support training. Explore the two-part liveness workflow.

Create a one-time liveness session.

Response — Hosted URL Creation

{
  "ok": true,
  "data": {
    "sessionId": "7995664a-b950-4aed-b4d1-76dc12c779c2",
    "url": "https://api.adeptsense.tech/liveness?token=eyJzaWQiOiI3..."
  }
}

GET /api/v1/liveness/result

Fetch the stored session results using sessionId query parameter.

POST /api/v1/name/translate

Convert a Bangla name to its English transliteration or vice versa for cross-system database matching.

POST /api/v1/name/gender

Predict gender and confidence levels from a given name in a specified language.

Interpreting verification results

Face matching and liveness are separate signals. Retrieve the completed result for each task and apply your configured review policy. A face match alone does not establish liveness.

Agree on thresholds and handling for uncertain or incomplete results with your team. Do not use a single example score as a universal acceptance rule.

Error Codes

Tier 1 — HTTP Status Codes (always available)

Tier 2 — Structured Error Codes (enhanced)

Webhooks

For asynchronous liveness results, SenseAI can POST a callback to your server when the result is ready.

{
  "event":      "verification.completed",
  "session_id": "ses_a1b2c3",
  "result": {
    "verified":       true,
    "liveness_score": 0.97
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "signature": "sha256=abc123..."
}

Verify the signature header using your webhook secret. Retries use exponential backoff (1s, 5s, 30s, 5m).

WebView Flow Integration

If you're using our hosted verification UI (/liveness?token=...) inside mobile or web applications, you can receive completion events natively via WebView and JavaScript bridges.

A) Web (iframe + postMessage)

Listen for liveness completion event payload using standard browser message handler:

const livenessUrl = "https://api.adeptsense.tech/liveness?token=YOUR_TOKEN";
document.getElementById("lvFrame").src = livenessUrl;

window.addEventListener("message", async (event) => {
  if (event.origin !== "https://api.adeptsense.tech") return;
  const msg = event.data || {};
  if (msg.type !== "liveness.result") return;

  const sessionId = msg.sessionId;
  // Fetch result securely from your backend -> /api/v1/liveness/result?sessionId=...
  console.log("Session complete:", sessionId);
});

B) Flutter (flutter_inappwebview)

Register Javascript handler name livenessResult in the controller:

final String livenessUrl = "https://api.adeptsense.tech/liveness?token=YOUR_TOKEN";

InAppWebView(
  initialUrlRequest: URLRequest(url: WebUri(livenessUrl)),
  onWebViewCreated: (controller) {
    controller.addJavaScriptHandler(
      handlerName: "livenessResult",
      callback: (args) async {
        final payload = args.isNotEmpty ? args[0] : null;
        final sessionId = payload?["sessionId"];
        // Call your backend proxy -> /api/v1/liveness/result?sessionId=...
      },
    );
  },
);

C) iOS (Swift + WKWebView)

Observe the userContentController with script handler name livenessResult:

import WebKit

config.userContentController.add(self, name: "livenessResult")
webView.load(URLRequest(url: URL(string: "https://api.adeptsense.tech/liveness?token=YOUR_TOKEN")!))

func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
  guard message.name == "livenessResult" else { return }
  if let payload = message.body as? [String: Any],
     let sessionId = payload["sessionId"] as? String {
       // Call your backend to verify -> /api/v1/liveness/result?sessionId=...
  }
}

D) Android (Java/Kotlin + WebView)

Create a JavaScript interface class bound as AndroidLiveness:

class LivenessBridge {
    @android.webkit.JavascriptInterface
    fun postMessage(payloadJson: String) {
        // Parse JSON -> extract sessionId -> retrieve results via backend
    }
}

webView.settings.javaScriptEnabled = true
webView.addJavascriptInterface(LivenessBridge(), "AndroidLiveness")
webView.loadUrl("https://api.adeptsense.tech/liveness?token=YOUR_TOKEN")

Liveness SDK integration

Bring guided liveness capture into your application. Contact Adept Sense for current packages, supported versions, and platform-specific setup instructions.

Integration resources

Request the current API specification and available Postman resources for your account.

Rate limits & file specifications

Confirm request limits, supported file formats, image dimensions, and timeouts for your account before going live. Use bounded retries for transient failures and handle unsuccessful responses in your integration.