> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudeg.com/llms.txt
> Use this file to discover all available pages before exploring further.
# KYC Onboarding and Identity Verification with FraudEG
> Run identity verification and watchlist screening for new users at onboarding using FraudEG KYC APIs. Covers document checks, liveness, and AML screening.
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.
```text theme={null}
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
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.
Send the full identity payload to the verification endpoint. The request body below covers an individual identity check with a passport document.
```json theme={null}
{
"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"
}
}
```
```bash cURL theme={null}
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"
}
}'
```
The API responds immediately with a `status` field that tells you how to proceed:
```json theme={null}
{
"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.
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.
```json theme={null}
{
"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" }
]
}
}
```
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.
```bash cURL theme={null}
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.
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.
```json theme={null}
{
"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.