KYC Onboarding and Identity Verification with FraudEG

Know Your Customer (KYC) onboarding is the process of collecting and verifying a user’s identity before granting them access to regulated or high-risk features. It is a legal requirement for most financial services and an important risk control for any platform where real money moves. FraudEG’s identity verification APIs let you submit user data, trigger document and liveness checks, and screen against global sanctions and watchlists — all through a single integration.

When to use KYC onboarding

KYC verification is appropriate at any of the following onboarding milestones:

Regulated fintech products — lending, money transmission, brokerage, or payment account creation where AML obligations apply
High-value account creation — accounts with elevated spending, transfer, or withdrawal limits
Marketplace seller onboarding — verifying sellers before they can list products or receive payouts
Crypto exchange registration — meeting FATF travel rule and VASP obligations at account creation

Verification flow overview

The KYC flow has both synchronous and asynchronous phases. When you submit an identity verification request, FraudEG returns an immediate decision for cases it can resolve instantly (e.g., clear data matches or obvious failures). For cases that require document analysis or liveness review, FraudEG returns a pending status and delivers the final result asynchronously via the identity.verification_completed webhook.

Submit identity data
        │
        ▼
POST /v1/identity/verify
        │
        ├── verified  → proceed to onboarding
        ├── pending   → wait for webhook, then act
        ├── failed    → reject; prompt user to correct data or try again
        └── flagged   → watchlist match; route to manual review

Integration guide

Collect user identity data in your onboarding form

Gather the required fields before making the API call: legal name, date of birth, residential address, and a government-issued document (passport, national ID, or driver’s license). For document verification, collect the document type, number, issuing country, and expiry date. If you are collecting document images for visual verification, upload them to your secure storage and pass the file references in the API request.

Submit to POST /v1/identity/verify

Send the full identity payload to the verification endpoint. The request body below covers an individual identity check with a passport document.

{
  "user_id": "usr_8f3k2p",
  "type": "individual",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1990-04-15",
  "address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "document": {
    "type": "passport",
    "number": "X1234567",
    "issuing_country": "US",
    "expiry_date": "2030-08-01"
  }
}

cURL

curl -X POST https://api.fraudeg.com/v1/identity/verify \
  -H "Authorization: Bearer $FRAUDEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_8f3k2p",
    "type": "individual",
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1990-04-15",
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "document": {
      "type": "passport",
      "number": "X1234567",
      "issuing_country": "US",
      "expiry_date": "2030-08-01"
    }
  }'

Handle the synchronous response

The API responds immediately with a status field that tells you how to proceed:

{
  "verification_id": "ver_2kx9pz7r",
  "user_id": "usr_8f3k2p",
  "status": "pending",
  "checks": [
    { "type": "document_validity", "result": "in_progress" },
    { "type": "liveness", "result": "in_progress" },
    { "type": "watchlist", "result": "clear" }
  ],
  "created_at": "2024-11-14T10:23:00Z"
}

Branch on the status value:

verified — all checks passed. Allow the user to proceed through onboarding.
pending — document or liveness review is still in progress. Block the user from transacting and listen for the identity.verification_completed webhook (see next step).
failed — one or more checks did not pass. Reject the application. You may prompt the user to re-submit with corrected or higher-quality document images, subject to your retry policy.
flagged — the user matched one or more entries on a sanctions list, PEP list, or adverse media database. Route the case to manual compliance review before taking any action.

Handle async results via webhook

For pending verifications, FraudEG delivers the final result to your registered webhook endpoint as an identity.verification_completed event. Parse the event payload and update the user’s onboarding status in your system.

{
  "event_type": "identity.verification_completed",
  "event_id": "evt_5nq3wr8m",
  "created_at": "2024-11-14T10:24:15Z",
  "data": {
    "verification_id": "ver_2kx9pz7r",
    "user_id": "usr_8f3k2p",
    "status": "verified",
    "checks": [
      { "type": "document_validity", "result": "pass" },
      { "type": "liveness", "result": "pass" },
      { "type": "watchlist", "result": "clear" }
    ]
  }
}

Run watchlist screening

After a verified or flagged result, you can also query the watchlist endpoint directly to retrieve the full screening detail for a user. This is useful for compliance records and periodic re-screening.

cURL

curl -G https://api.fraudeg.com/v1/identity/watchlist \
  -H "Authorization: Bearer $FRAUDEG_API_KEY" \
  --data-urlencode "user_id=usr_8f3k2p"

The response includes match details, list names (OFAC, UN, EU, PEP), match score, and matched fields.

Store the verification_id for compliance records

Persist the verification_id in your user record immediately after receiving it. You will need this identifier to retrieve verification evidence during audits, regulatory examinations, or dispute resolution. All verification records, check results, and watchlist screening outcomes are linked to this ID.

KYB: verifying businesses

The same POST /v1/identity/verify endpoint handles business (KYB) verification. Set "type": "business" and include company-specific fields alongside the registered address and beneficial owner information.

{
  "user_id": "biz_3p7xk1",
  "type": "business",
  "legal_name": "Acme Payments LLC",
  "registration_number": "DE-7734892",
  "incorporation_country": "US",
  "address": {
    "line1": "800 Market St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "beneficial_owners": [
    {
      "first_name": "John",
      "last_name": "Smith",
      "ownership_percentage": 51,
      "date_of_birth": "1978-06-20"
    }
  ]
}

FraudEG retains all verification records — check results, document metadata, watchlist screening outcomes, and audit logs — in accordance with applicable data retention regulations. For US customers, records are stored for a minimum of five years. For EU customers, retention follows applicable AML directive requirements. You can retrieve a full verification audit trail at any time using the verification_id.

Never allow a user with a failed or flagged verification status to transact, withdraw funds, or access regulated features without completing a manual compliance review first. Automated approval of flagged users may constitute a sanctions violation. Always route flagged cases to your compliance team and document the review outcome before taking any action.

The FraudEG sandbox includes a set of test identities that simulate each possible verification outcome. Use date_of_birth: "1990-01-01" to trigger verified, date_of_birth: "1990-01-02" to trigger pending, date_of_birth: "1990-01-03" to trigger failed, and date_of_birth: "1990-01-04" to trigger flagged. This lets you build and test every branch of your onboarding flow without submitting real identity data.

Get Started

Core Concepts

Guides

Platform

KYC Onboarding and Identity Verification with FraudEG

When to use KYC onboarding

Verification flow overview

Integration guide

KYB: verifying businesses

​When to use KYC onboarding

​Verification flow overview

​Integration guide

​KYB: verifying businesses

When to use KYC onboarding

Verification flow overview

Integration guide

KYB: verifying businesses