Onfido

Supergood | Onfido API

Alex Klarfeld

Alex Klarfeld

— 6 min read
Supergood | Onfido API

Programmatically access Onfido identity verification data (applicants, checks, reports) and workflow events with a stable REST API. Supergood builds and operates production-grade, unofficial Onfido integrations so your team can automate KYC/AML, right-to-work, and audit workflows without heavy custom engineering.

Plain English: Onfido is identity verification software used to confirm a person’s identity by analyzing government IDs, selfies/liveness, and screening against watchlists and sanctions. An unofficial API lets you programmatically create applicants, upload documents and face captures, start verification checks, retrieve report results (document, facial similarity, AML/watchlist, right-to-work), and normalize outcomes for compliance.

For a GRC or regtech startup integrating with Onfido, this means you can push applicant profiles and consent into verification flows, pull check statuses and risk outcomes into case management, flag watchlist hits for enhanced due diligence, archive audit artifacts, and trigger follow-ups or escalations. You can also stream real-time verification events to your compliance system, enrich customer onboarding with identity checks, and maintain consistent records across CRM, ERP, analytics, and regulatory audit systems.

What is Onfido?

Onfido (https://onfido.com/) is a cloud platform for digital identity verification and compliance that helps organizations onboard customers and employees securely. Teams use Onfido to capture and validate identity documents, perform facial similarity and liveness checks, run watchlist/sanctions (AML/KYC) screenings, and determine eligibility for right-to-work/right-to-rent—powered by SDKs, orchestration workflows, and machine learning with optional human review.

Core product areas include:

  • Identity Verification (Document Capture & Validation, Facial Similarity, Liveness)
  • AML/KYC Screening (Sanctions, PEP, Adverse Media, Watchlists)
  • Employment & Tenant Compliance (Right to Work, Right to Rent)
  • Workflow Orchestration (Multi-step verification flows, decisioning)
  • Fraud Prevention (Repeat attempt detection, device signals, tamper checks)
  • Developer Tooling (SDKs, webhooks, sandbox/testing, artifact downloads)

Common data entities:

  • Applicants (PII, contact info, consent, metadata)
  • Checks (grouping of reports executed for an applicant)
  • Reports (document, facial_similarity, watchlist_aml, right_to_work)
  • Artifacts (document images, selfie/video captures, signed URLs)
  • Decisions and Risk Scoring (statuses, recommendations, manual review)
  • Workflow Runs and Events (step outcomes, transitions, webhooks)

The Onfido Integration Challenge

Compliance teams rely on Onfido daily, but turning portal- and SDK-driven flows into headless automation requires careful handling:

  • PII stewardship: Sensitive identity data and artifacts must be accessed with least privilege and audited
  • Asynchronous report lifecycles: Checks return in stages with partial results, retries, and manual review
  • Variant logic by region: Document types, sanctions lists, and right-to-work rules vary by country and program
  • Workflow-first UX: Capture flows and step sequencing are optimized for front-end SDKs, not backend jobs
  • Authentication complexity: SSO/MFA and short-lived URLs complicate durable integrations
  • Event reliability: Webhook ordering, deduplication, and replays impact downstream compliance SLAs

How Supergood Creates Onfido APIs

Supergood reverse-engineers authenticated browser flows and network interactions to deliver a resilient API endpoint layer for your Onfido tenant.

  • Handles username/password, SSO/OAuth, and MFA (SMS, email, TOTP) securely
  • Maintains session continuity with automated refresh and change detection
  • Normalizes responses so you can integrate once and rely on consistent objects across modules
  • Aligns with customer entitlements, data retention policies, and role-based permissions to ensure compliant access
  • Streams verification events and artifacts with durable delivery and redaction options

Use Cases

GRC & Audit Data Sync

  • Mirror applicants, checks, and report outcomes into your case management or GRC system
  • Maintain audit trails with timestamps, decisions, reviewer notes, and linked artifacts
  • Normalize statuses (clear/consider/rejected) and risk scores for dashboards and SLA tracking

KYC/AML Automation

  • Automatically initiate document + facial + watchlist checks when a new customer signs up
  • Trigger enhanced due diligence on sanctions or PEP matches and route to analysts
  • Push final decisions back to CRM/ERP while maintaining evidence and consent logs

Right to Work / HR Compliance

  • Launch right-to-work checks during onboarding with region-specific rules
  • Store determinations and expiry dates to drive renewal reminders
  • Attach HR records and update employee systems with compliance outcomes

Risk Analytics & Fraud Prevention

  • Aggregate device and repeat-attempt signals to detect potential fraud patterns
  • Enrich identity risk scoring in your platform with Onfido report details
  • Drive adaptive workflows (e.g., escalate to liveness video on high-risk signals)

Available Endpoints

Authentication

POST /sessions: Establish a session using credentials. Supergood manages MFA (SMS, email, TOTP) and SSO/OAuth when enabled. Returns a short-lived auth token maintained by the platform.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/sessions \
  --header 'Authorization: Basic <Base64 encoded token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "[email protected]",
    "password": "<password>",
    "mfa": { "type": "totp", "code": "123456" }
  }'

Example response

{
  "authToken": "eyJhbGciOi...",
  "expiresIn": 3600,
  "user": {
    "id": "u_onf_28f9c2",
    "name": "Compliance Analyst",
    "entitlements": ["applicants", "checks", "reports", "artifacts"]
  }
}

Applicants

POST /applicants: Create an applicant profile with PII, consent, and metadata.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/applicants \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "firstName": "Alex",
    "lastName": "Rivera",
    "dob": "1993-07-14",
    "email": "[email protected]",
    "phone": "+1-415-555-0134",
    "address": {
      "line1": "455 Market St",
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US"
    },
    "identifiers": {
      "nationalIdNumber": "***-**-6789",
      "passportNumber": null
    },
    "consent": {
      "privacyNoticeAcceptedAt": "2026-01-20T13:42:05Z",
      "termsAcceptedAt": "2026-01-20T13:42:05Z"
    },
    "metadata": {
      "referenceId": "case-7842",
      "segment": "retail_banking"
    }
  }'

Example response

{
  "applicantId": "app_6df0b3",
  "status": "active",
  "createdAt": "2026-01-21T10:09:01Z"
}

Checks

POST /checks: Create a verification check for an applicant with specified report types and optional attachments.

curl --request POST \
  --url https://api.supergood.ai/integrations/<integration_id>/checks \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "applicantId": "app_6df0b3",
    "reportTypes": ["document", "facial_similarity", "watchlist_aml"],
    "documentAttachments": [
      {"type": "passport", "side": "front", "uploadToken": "upl_doc_0ac7e1"}
    ],
    "faceCapture": {"mode": "selfie", "uploadToken": "upl_face_48a221"},
    "options": {
      "manualReview": true,
      "watchlistLevels": ["sanctions", "pep", "adverse_media"],
      "region": "US"
    },
    "externalReference": "onboarding-7842",
    "notify": true
  }'

Example response

{
  "checkId": "chk_91a4c7",
  "status": "in_progress",
  "expectedReports": [
    {"type": "document", "reportId": null},
    {"type": "facial_similarity", "reportId": null},
    {"type": "watchlist_aml", "reportId": null}
  ],
  "createdAt": "2026-01-21T10:12:37Z"
}

Check Summary

GET /checks/{checkId}/summary: Retrieve a consolidated summary of report outcomes, risk scores, and audit metadata.

Query parameters

  • includeArtifacts: boolean (default false)

Example response

{
  "checkId": "chk_91a4c7",
  "applicantId": "app_6df0b3",
  "overallStatus": "consider",
  "riskScore": 63.2,
  "reports": [
    {
      "type": "document",
      "status": "clear",
      "documentType": "passport",
      "issuerCountry": "US",
      "expiryDate": "2032-05-11",
      "quality": {"mrzValid": true, "tamperSignals": []}
    },
    {
      "type": "facial_similarity",
      "status": "clear",
      "similarityScore": 0.97,
      "liveness": {"mode": "selfie", "signals": ["texture", "depth"]}
    },
    {
      "type": "watchlist_aml",
      "status": "consider",
      "matches": [
        {
          "list": "PEP",
          "name": "A. Rivera",
          "matchScore": 0.82,
          "jurisdiction": "US"
        }
      ]
    }
  ],
  "compliance": {
    "reviewRequired": true,
    "manualReviewer": null,
    "nextAction": "enhanced_due_diligence",
    "dataRetention": {"scheduledDeletionAt": "2027-01-21T10:12:37Z"}
  },
  "artifacts": {
    "documentFrontUrl": null,
    "selfieUrl": null
  },
  "timestamps": {
    "createdAt": "2026-01-21T10:12:37Z",
    "completedAt": "2026-01-21T10:16:55Z"
  }
}

Get full API Specs →

Technical Specifications

  • Authentication: Username/password with MFA (SMS, email, TOTP) and SSO/OAuth where enabled; supports service accounts or customer-managed credentials
  • Response format: JSON with consistent resource schemas and pagination across modules
  • Rate limits: Tuned for enterprise throughput while honoring customer entitlements and usage controls
  • Session management: Automatic reauth and cookie/session rotation with health checks
  • Data freshness: Near real-time retrieval of applicants, checks, reports, and artifacts
  • Security: Encrypted transport, scoped tokens, and audit logging; respects Onfido role-based permissions and data retention
  • Webhooks: Optional asynchronous delivery for long-running workflows (e.g., check.completed, report.updated)

Performance Characteristics

  • Latency: Sub-second responses for list/detail queries under normal load
  • Throughput: Designed for high-volume verification creation and report data sync
  • Reliability: Retry logic, backoff, and idempotency keys minimize duplicate actions
  • Adaptation: Continuous monitoring for UI/API changes with rapid adapter updates

Getting Started

  1. Schedule Integration Assessment

Book a 30-minute session to confirm your modules, licensing, and authentication model.

  1. Supergood Builds and Validates Your API

We deliver a hardened Onfido adapter tailored to your workflows and entitlements.

  1. Deploy with Monitoring

Go live with continuous monitoring and automatic adjustments as Onfido evolves.

Schedule Integration Call →

Frequently Asked Questions

Q: Which Onfido modules can this integration cover?

Supergood supports workflows across commonly used areas such as Identity Verification (Document, Facial Similarity, Liveness), AML/KYC Screening (Sanctions, PEP, Adverse Media), Employment Compliance (Right to Work/Right to Rent), and Webhooks/Artifacts, subject to your licensing and entitlements. We scope coverage during integration assessment.

Q: How are MFA and SSO handled for automation?

We support username/password + MFA (SMS, email, TOTP) and can operate behind SSO/OAuth when enabled. Sessions are refreshed automatically with secure challenge handling.

Q: Can you sync verification results to our compliance or case management system?

Yes. We normalize check outcomes, report details, and artifacts to match your GRC schema and deliver updates via webhooks or polling while complying with rate, retention, and permission constraints.

Yes. We model consent timestamps explicitly and support configurable retention windows, redaction, and expiring artifact URLs to help you meet regulatory requirements.

Ready to automate your Onfido workflows?

Supergood can have your Onfido integration live in days with no ongoing engineering maintenance.

Get Started →

Read more