Verify a person with one hosted flow.

Create a secure identity-verification link, send it to your customer or tenant, and receive a structured decision through the API and signed webhooks.

Quickstart

Complete one end-to-end Sandbox verification before writing production logic. REST API delivery is authenticated JSON and signed webhook events; it does not create a downloadable client PDF report. For a reusable link, dashboard case and PDF report without coding, use No-Code Integration in the Client Dashboard.

Authentication

Every API request requires your environment’s secret key in the X-API-Key header. TEST keys create simulated, zero-cost requests; LIVE keys create billable real verifications.

What does “Authorize 🔒” do?

The Authorize padlock exists only in the interactive API reference. Entering a TEST key there makes the page add X-API-Key automatically when you select “Try it out.” It does not enable your account, create a key, or affect calls made from your own code. If you use curl, Postman, or your backend, send the header yourself.

X-API-Key: sk_test_your_secret_key

Choose a product

Additional government ID is conditional. It is requested when initial identity, name, facial, or confidence checks need remediation—not for every subject.

Create a verification

curl --request POST \
  --url https://api-cp.onmero.com/api/v1/hosted-verifications \
  --header "Content-Type: application/json" \
  --header "X-API-Key: sk_test_your_secret_key" \
  --header "Idempotency-Key: hv_customer_4f29a8c7" \
  --data '{
    "productCode": "KYC_STANDARD",
    "externalReference": "customer_4f29a8c7",
    "subject": {
      "firstName": "Ada",
      "middleName": "Ifeoma",
      "lastName": "Okafor",
      "email": "ada@example.com",
      "phone": "+2348012345678"
    },
    "delivery": { "email": false },
    "redirectUrl": "https://app.example.com/verification/complete",
    "metadata": { "customerId": "cus_123" }
  }'

Request fields

TEST response

{
  "success": true,
  "data": {
  "id": "hv_123",
  "externalReference": "customer_4f29a8c7",
  "environment": "TEST",
  "productCode": "KYC_STANDARD",
  "status": "CREATED",
  "hostedUrl": "https://cp.onmero.com/hosted-verification/...",
  "verificationUrl": "https://cp.onmero.com/hosted-verification/...",
  "qrCodeUrl": "https://api-cp.onmero.com/api/v1/.../qr.svg",
  "expiresAt": "2026-10-28T12:00:00.000Z",
  "billing": { "currency": "NGN", "amountCharged": 0, "pricingSource": "SANDBOX" }
  }
}

LIVE response

{
  "success": true,
  "data": {
    "id": "hv_live_123",
    "externalReference": "customer_live_001",
    "environment": "LIVE",
    "status": "CREATED",
    "hostedUrl": "https://kyc.onmero.com/verify?token=...",
    "verificationUrl": "https://kyc.onmero.com/verify?token=...",
    "expiresAt": "2026-11-02T12:00:00.000Z",
    "billing": { "currency": "NGN", "amountCharged": 5000, "pricingSource": "API_SERVICE_PRICE", "walletTransactionId": "txn_123" }
  }
}

Send the hosted journey

Local development

TEST_REDIRECT_URL=http://localhost:3000/onmero/identity-verification/return
PUBLIC_REDIRECT_URL=https://your-tunnel.ngrok-free.app/onmero/identity-verification/return
WEBHOOK_URL=https://your-tunnel.ngrok-free.app/onmero/webhooks/events

Read the result

Example: straight-through verification

No additional identity document was needed. Liveness is shown as an outcome rather than a numeric score; the numeric value belongs to the facial comparison.

{
  "status": "COMPLETED",
  "result": {
    "schemaVersion": "2026-10-21",
    "decision": "VERIFIED",
    "identity": {
      "overallScore": 94,
      "name": {
        "firstName": { "matched": true, "score": 100 },
        "lastName": { "matched": true, "score": 100 }
      },
      "facial": {
        "matched": true,
        "score": 96
      },
      "liveness": {
        "required": false,
        "completed": false,
        "status": "NOT_REQUIRED"
      },
      "additionalIdentityDocument": {
        "requested": false,
        "received": false,
        "ocrCompleted": false,
        "evidence": {
          "frontReceived": false,
          "backReceived": false,
          "ocrDocumentReceived": false
        }
      }
    },
    "proofOfAddress": { "status": "ACCEPTED", "received": true },
    "references": [],
    "reportId": "report_123"
  }
}

Example: additional ID and address review

The initial confidence or facial result required remediation. An additional government ID was received and OCR-processed, while proof of address still requires authorised review.

{
  "status": "REVIEW_REQUIRED",
  "result": {
    "decision": "REVIEW_REQUIRED",
    "identity": {
      "overallScore": 68,
      "facial": { "matched": false, "score": 72 },
      "liveness": {
        "required": true,
        "completed": true,
        "status": "COMPLETED"
      },
      "additionalIdentityDocument": {
        "requested": true,
        "received": true,
        "ocrCompleted": true,
        "evidence": {
          "frontReceived": true,
          "backReceived": true,
          "ocrDocumentReceived": true
        }
      }
    },
    "proofOfAddress": {
      "status": "REVIEW_REQUIRED",
      "documentType": "UTILITY_BILL",
      "received": true,
      "confirmedAt": null,
      "reviewReason": "The address evidence requires staff review."
    },
    "references": [],
    "reportId": null
  }
}

Example: Enhanced verification with a reference

KYC Enhanced and KYT can return referee statements, recommendations, identity checks, live-presence outcome and referee face-match score.

{
  "status": "COMPLETED",
  "result": {
    "decision": "VERIFIED",
    "proofOfAddress": {
      "status": "ACCEPTED",
      "documentType": "BANK_STATEMENT",
      "received": true,
      "confirmedAt": "2026-10-21T12:00:00.000Z",
      "reviewReason": null
    },
    "references": [{
      "type": "CHARACTER",
      "status": "ACCEPTED",
      "relationship": "Professional referee",
      "response": "I have known the subject for five years.",
      "recommendation": "RECOMMENDED",
      "identityNameMatched": true,
      "ninVerified": true,
      "facial": {
        "livePresenceStatus": "CONFIRMED",
        "facialComparisonStatus": "CONFIRMED",
        "faceMatchScore": 93
      }
    }],
    "reportId": "report_123"
  }
}

Conditional result sections

Handle webhooks

Configure an HTTPS URL in API Integration. ONMERO sends verification.created, verification.updated, verification.review_required, verification.completed, and verification.failed.

Test scenarios

Use a TEST request and choose each Sandbox result at least once.

Errors

Insufficient-funds response

{
  "statusCode": 402,
  "error": "Payment Required",
  "code": "INSUFFICIENT_WALLET_BALANCE",
  "message": "Insufficient wallet balance."
}

Go live

Open interactive API reference →

Sample integration code

This Node.js Quick Start creates a hosted verification from your server. Use a TEST key first. The dashboard also provides copyable examples for Python, PHP, Java, .NET, Go, Ruby, Rust, Kotlin and React backend-call flows.

import crypto from "node:crypto";

const externalReference = `customer_${crypto.randomUUID()}`;
const response = await fetch("https://api-cp.onmero.com/api/v1/hosted-verifications", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ONMERO_API_KEY,
    "Idempotency-Key": `create_${externalReference}`,
  },
  body: JSON.stringify({
    productCode: "KYC_ENHANCED",
    externalReference,
    subject: { firstName: "Ada", lastName: "Okafor", email: "ada@example.com" },
    redirectUrl: "http://localhost:3000/onmero/identity-verification/return",
    delivery: { email: false },
  }),
});

const body = await response.json();
if (response.status === 402) throw new Error("Fund the LIVE wallet, then use a new reference.");
if (response.status !== 201) throw new Error(body.message ?? "Unable to create verification.");
const data = body.data ?? body;
// Save data.id, then redirect the browser to data.hostedUrl. Never log that URL.

Production-ready code

Production integrations should add timeouts, structured error handling, trusted-host validation, idempotency, minimal logging, authenticated status retrieval and verified webhook signatures.

const BASE_URL = "https://api-cp.onmero.com";
const TRUSTED_HOSTS = new Set(["cp.onmero.com", "kyc.onmero.com"]);

export async function getVerification(id) {
  const response = await fetch(
    `${BASE_URL}/api/v1/hosted-verifications/${encodeURIComponent(id)}`,
    { headers: { "X-API-Key": process.env.ONMERO_API_KEY },
      signal: AbortSignal.timeout(20_000) },
  );
  if (!response.ok) throw new Error("Unable to retrieve verification status.");
  const body = await response.json();
  const data = body.data ?? body;
  return {
    ...data,
    verified: data.status === "COMPLETED" && data.result?.decision === "VERIFIED",
  };
}

// Before redirecting, require HTTPS and an ONMERO trusted hostname.
// Verify webhook signatures over the raw request body.
// A redirect back to your portal is never proof of successful verification.

Open all language examples →