API documentation

What this is for

Your mobile / web app (a NIV2FA project) needs to prove a user really controls a phone number. Use NIV2FA instead of SMS OTP for:

• register — new account signup
• login — passwordless or step-up login
• forgot_password — reset only after identity match
• confirm_order — high-risk checkout / COD confirm
• Any other flow — pass your own purpose string

Activate (one-time setup)

1. Create an account → open Dashboard.
2. Create a Project (e.g. “Ecommerce Shop”, “Agent App”) — each project gets a 7-day trial.
3. Set the project webhook URL (your backend, or the demo inbox while testing).
4. Create an API key (niv_live_…).
5. Top up wallet / subscribe to a plan after trial when required.

Runtime flow (mobile app)

1. User enters phone in your app (register / login / forgot / order).
2. Your backend calls POST /secure-api/v1/verifications with that phone + purpose + returnUrl.
3. API returns sessionId, verifyUrl (same as pairUrl), and qrUrl / qrValue.
4. Same device: open verifyUrl in WebView / Custom Tabs / SFSafariViewController / in-app browser.
5. SIM on another phone: show qrUrl (or encode qrValue) so the other phone’s camera opens the link.
6. Verify page auto-confirms (~0.5s) — matches SIM1 or SIM2 (if present) on the device that opened the QR/link. No re-typing, no codes.
7. Browser redirects to your returnUrl?sessionId=&status=completed&matched=true.
8. Your project webhook receives identity.verified — use that to activate the user / unlock login / confirm the order.

Base URL

https://takteksoft.com

Health: GET https://takteksoft.com/secure-api/health

Authentication

Authorization: Bearer niv_live_YOUR_KEY
Content-Type: application/json

1 · Start verification

POST /secure-api/v1/verifications

{
  "phone": "9647XXXXXXXXX",
  "projectId": "proj_…",
  "purpose": "register",
  "clientUserId": "user_123_in_your_db",
  "referenceId": "optional-order-or-ticket-id",
  "returnUrl": "myapp://nif/result",
  "cancelUrl": "myapp://nif/cancel",
  "currency": "IQD"
}

purpose examples: register · login · forgot_password · confirm_order

Response highlights

{
  "success": true,
  "data": {
    "sessionId": "sess_…",
    "phone": "9647XXXXXXXXX",
    "status": "waiting",
    "matched": false,
    "purpose": "register",
    "verifyUrl": "https://takteksoft.com/verify/sess_…",
    "pairUrl": "https://takteksoft.com/verify/sess_…",
    "qrUrl": "https://api.qrserver.com/…",
    "qrValue": "https://takteksoft.com/verify/sess_…",
    "returnUrl": "myapp://nif/result",
    "expiresAt": "…"
  }
}

2 · Poll (optional)

GET /secure-api/v1/verifications/:sessionId

Useful if the user stays in your app UI while another phone scans the QR. When done: status: "completed", matched: true.

3 · Webhook (source of truth for your backend)

Configure on the project. On success we POST:

{
  "event": "identity.verified",
  "sessionId": "sess_…",
  "projectId": "proj_…",
  "phone": "9647XXXXXXXXX",
  "matched": true,
  "matchedSlot": "sim2",
  "status": "completed",
  "purpose": "register",
  "clientUserId": "user_123_in_your_db",
  "referenceId": null,
  "verifiedAt": "…",
  "session": { /* full public session object */ }
}

Your app should: verify matched === true, optionally check matchedSlot (sim1 / sim2), match clientUserId / phone / purpose, then complete register / login / reset / order confirmation. No OTP field exists.

4 · returnUrl (client UX)

After success the verify page redirects like a payment gateway:

myapp://nif/result?sessionId=sess_…&status=completed&matched=true

Works with HTTPS pages, PWAs, Flutter, Ionic, Capacitor, Cordova, React Native, native iOS/Android deep links. Still treat the webhook (or a server-side poll) as authoritative before granting access.

Example · Register

curl -X POST "https://takteksoft.com/secure-api/v1/verifications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone":"9647XXXXXXXXX",
  "projectId":"proj_…",
  "purpose":"register",
  "clientUserId":"pending_user_88",
  "returnUrl":"myapp://auth/register/done",
  "cancelUrl":"myapp://auth/register",
  "currency":"IQD"
}'

Example · Login / Forgot password / Confirm order

# login
{ "purpose":"login", "clientUserId":"user_88", "phone":"9647…", "returnUrl":"myapp://auth/login/done" }

# forgot_password
{ "purpose":"forgot_password", "clientUserId":"user_88", "phone":"9647…", "returnUrl":"myapp://auth/reset/done" }

# confirm_order
{ "purpose":"confirm_order", "referenceId":"order_90210", "clientUserId":"user_88", "phone":"9647…", "returnUrl":"myapp://orders/90210/confirmed" }

Cancel

POST /secure-api/v1/verifications/:sessionId/cancel

Demo / testing

Return URL
https://takteksoft.com/demo/result

Webhook URL
https://takteksoft.com/secure-api/demo/webhook

Open webhook inbox

curl -X POST "https://takteksoft.com/secure-api/v1/verifications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone":"9647XXXXXXXXX",
  "projectId":"proj_…",
  "purpose":"register",
  "currency":"IQD",
  "returnUrl":"https://takteksoft.com/demo/result",
  "cancelUrl":"https://takteksoft.com/demo/result?status=cancelled"
}'

Not this product

• No OTP / SMS / WhatsApp / Telegram codes
• No agent tokens on end-user screens
• /device/pair/… is admin gateway fleet pairing only — not for customer register/login

Mobile SDK & plugins

Embed verification inside Flutter, Ionic, Capacitor, Cordova, React Native, Android, or iOS — install from GitHub, open verifyUrl in-app, match SIM1/SIM2 (Android).

SDK install & methods GitHub

Billing

Projects get a 7-day trial, then plans by project count (3 / 7 / 15 / Enterprise). Not a per-OTP marketplace.