Skip to main content

​
How it works

  1. Render the widget (ID Verify) in your form using a Publishable Key.
  2. End-user captures photos (front, back, selfie – optional) or uploads images/PDF.
  3. Widget POSTs to /api/v1/embedded/actions with:
    • publishableKey
    • actionType id_verification
    • opaque actionToken (encrypted file bundle)
    • developer-supplied metadata (userId, loanAppId, …)
  4. OmniAI checks document authenticity, runs OCR + facial match (if selfie), and parses the ID fields.
  5. Your backend receives a webhook / REST callback with normalized ID data, validation results, raw OCR, and any errors.
id-verification-embedded.png

​
Quick start

<!-- ❶ Load the library -->
<script src="https://cdn.getomni.ai/embedded/v1/omni-embedded.js"></script>

<!-- ❷ Container -->
<div id="omni-id-widget"></div>

<!-- ❸ Mount -->
<script>
  OmniEmbedded.mount('#omni-id-widget', {
    publishableKey: 'pk_live_abc123', // REQUIRED
    action:         'id',             // ID-verification widget
    requireSelfie:  true,             // optional
    metadata: {
      userId:    'usr_789',
      loanAppId: 'loan_456'
    },

    onChange:   e => console.log('[ID] change',  e), // fires on every event
    onComplete: r => console.log('[ID] accepted', r), // OmniAI accepted bundle
    onExit:     x => console.warn ('[ID] exited',  x) // user closed widget
  });
</script>

​
Widget configuration (OmniEmbedded.mount)

OptionType / ExampleDefaultDescription
action"id"—Required. Renders the ID-verification UI.
publishableKey"pk_live_…"—Required.
requireSelfietrue | falsefalseCapture a selfie and perform face-match when true.
documentTypes["license","passport"]["license","passport","state_id"]Restrict acceptable ID types.
metadata{ userId: "usr_123", … }{}Echoed back in webhook (≤ 2 KB).
environment"sandbox" | "live""live"Route calls to sandbox or production.
onCompletefunction(result){ … }—Fires when OmniAI accepts the action ({ actionId, type }).
onExitfunction(info){ … }—Fires if the user closes the widget.
onChangefunction(event){ … }nullStreams every interaction (stage, detail, timestamp).

​
Webhook / REST callback – ID Verification payload

{
  /* ── Core identifiers ─────────────────────────── */
  "actionId": "act_ab12cd",
  "type":     "id_verification",
  "status":   "completed",               // accepted | processing | completed | errored
  "metadata": {
    "userId":    "usr_789",
    "loanAppId": "loan_456"
  },

  /* ── Parsed ID fields ─────────────────────────── */
  "document": {
    "documentId":    "doc_55e",
    "type":          "driver_license",   // driver_license | passport | state_id
    "issuingCountry":"US",
    "issuingState":  "CA",
    "number":        "D1234567",
    "firstName":     "ALEX",
    "lastName":      "SMITH",
    "dob":           "1993-07-02",
    "expiration":    "2031-07-02",
    "address": {
      "street":  "1234 Market St",
      "city":    "San Francisco",
      "state":   "CA",
      "postal":  "94103",
      "country": "US"
    },
    "validated":         true,           // ✅ authenticity & expiry passed
    "validationMessage": ""
  },

  /* ── Selfie / Face-match (optional) ───────────── */
  "biometrics": {                        // omitted if requireSelfie=false
    "faceMatchScore": 0.92,              // 0-1 (≥ 0.80 = match)
    "livenessCheck":  "passed"           // passed | failed | unavailable
  },

  /* ── Raw artifacts ───────────────────────────── */
  "images": {
    "frontUrl":  "https://files.getomni.ai/ids/doc_55e_front.jpg",
    "backUrl":   "https://files.getomni.ai/ids/doc_55e_back.jpg",
    "selfieUrl": "https://files.getomni.ai/ids/doc_55e_selfie.jpg"
  },
  "rawOcr": { /* full unredacted OCR blocks */ },

  /* ── Error collection ─────────────────────────── */
  "errors": [
    {
      "code":    "ID_EXPIRED",
      "message": "Document expired on 2023-07-02",
      "field":   "document.expiration"
    }
  ],

  /* ── Timestamps ──────────────────────────────── */
  "createdAt":  "2025-06-22T23:19:04Z",
  "completedAt":"2025-06-22T23:19:22Z"
}

​
Validation logic

CheckDefault rule
AuthenticityHologram, MRZ, barcode integrity & tamper detection
ExpirationDocument must be valid on processing date
Face match (optional)faceMatchScore ≥ 0.80 and liveness passed
Jurisdiction block-listConfigure in Dashboard → ID Verify → Rules

​
Error handling

ScenariostatusExample errors[0].codeNext step
ID photo too blurrycompletedID_IMAGE_BLURRYRe-prompt user to recapture
Document expiredcompletedID_EXPIREDAsk for a valid ID
Face mismatch (selfie vs ID)erroredFACE_MISMATCHRetry capture or send to manual review
User cancels captureaccepted—No retry unless user reopens the widget