> ## Documentation Index
> Fetch the complete documentation index at: https://doc.youverify.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Onboard a Customer You Only Know by Email
> Create an entity with just an email, receive an instant AML risk score, and progressively enrich the record as more customer data arrives — no duplicate records.
Payment processors and PSPs regularly onboard merchants or end-users who share nothing more than an email address at sign-up. Youverify's entity model is built for exactly this case: you create the entity with minimal data, the platform scores it immediately against AML databases, and you enrich the record progressively as more information becomes available — all without ever creating a duplicate record.
The email-only creation path is reserved for **downstream entities** — merchants, fintechs, or end-users that belong to a platform customer rather than directly to your organisation. Set `isSubjectConsent: true` on every request to confirm the subject has consented to verification.
## Prerequisites
* A Youverify account at [cowork.youverify.co](https://cowork.youverify.co)
* Your API secret key (retrieve it from the dashboard under **Settings → API Keys**)
* Webhooks configured to receive enrichment and signal events (recommended)
***
## Steps
### Create the entity with just an email
Send a `POST /v2/api/entities` request with only `entityType`, `isSubjectConsent`, and `email`. The platform creates the entity, runs an automatic AML screen (sanctions, PEP, watchlist, adverse media) against whatever data is present, and returns a **Created** entity with an initial risk score.
```bash cURL theme={null}
curl -X POST "https://api.youverify.co/v2/api/entities" \
-H "token: $YV_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"entityType": "individual",
"isSubjectConsent": true,
"email": "jane@example.com"
}'
```
```javascript Node.js theme={null}
const response = await fetch('https://api.youverify.co/v2/api/entities', {
method: 'POST',
headers: {
'token': process.env.YV_SECRET_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
entityType: 'individual',
isSubjectConsent: true,
email: 'jane@example.com',
}),
});
const { data } = await response.json();
const entityId = data.id; // save this — it's your permanent handle
```
```python Python theme={null}
import os, requests
resp = requests.post(
'https://api.youverify.co/v2/api/entities',
headers={
'token': os.environ['YV_SECRET_KEY'],
'Content-Type': 'application/json',
},
json={
'entityType': 'individual',
'isSubjectConsent': True,
'email': 'jane@example.com',
},
)
entity_id = resp.json()['data']['id']
```
The response confirms the entity was created and returns its stable `ent_…` identifier:
```json Response theme={null}
{
"success": true,
"status_code": 201,
"message": "Entity created successfully.",
"data": {
"id": "ent_684f5cc5a47a3926763b83a7",
"businessId": "61d880f1e8e15aaf24558f1a",
"createdBy": {
"firstName": "Timothy",
"lastName": "Akinyelu",
"middleName": "",
"id": "61f162ec1fd251c3a63f31c2"
}
},
"links": []
}
```
Store the returned `id` (`ent_…`) in your database alongside your own customer record. Every subsequent call — enrichment, KYC, AML screening, transaction posting — references this single identifier. **Create once, reference forever.**
### Monitor immediately via webhooks
The moment the entity is created, Youverify runs an automatic AML screen in the background. You don't need to trigger it. Subscribe to the `entity.created` and `entity.risk_score_updated` webhook events so your system receives the initial risk score and any subsequent changes as soon as they are computed.
Configure your webhook endpoint in the dashboard under **Settings → Webhooks**, then listen for the following payload shape:
```json Webhook — entity.risk_score_updated theme={null}
{
"event": "entity.risk_score_updated",
"data": {
"entityId": "ent_684f5cc5a47a3926763b83a7",
"riskScore": 24,
"riskLevel": "low",
"triggers": ["aml_screen_complete"]
}
}
```
At creation the risk score reflects AML data only. There is no behavioural history yet — Fraud Insight enriches the score over time as the entity transacts and generates signals.
### Enrich over time as data becomes available
When the customer provides additional details — name, phone number, date of birth, or a government ID — patch the same entity rather than creating a new one. Each enrichment re-evaluates the risk score against the fuller profile.
```bash cURL theme={null}
curl -X PATCH "https://api.youverify.co/v2/api/entities/ent_684f5cc5a47a3926763b83a7" \
-H "token: $YV_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Jane",
"lastName": "Doe",
"phone": "+2348012345678",
"dateOfBirth": "1990-06-15"
}'
```
```bash cURL theme={null}
curl -X PATCH "https://api.youverify.co/v2/api/entities/ent_684f5cc5a47a3926763b83a7" \
-H "token: $YV_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"nationality": "NG"
}'
```
### Trigger KYC when you have enough data
Once you hold a government ID number, run a KYC verification directly on the entity. The result — match status, returned PII, and any fraud signals — attaches to the entity's 360 record rather than living as an orphaned report.
```bash cURL theme={null}
curl -X POST "https://api.youverify.co/v2/api/entities/ent_684f5cc5a47a3926763b83a7/verify/kyc" \
-H "token: $YV_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"entityType": "individual",
"isSubjectConsent": true,
"identity": {
"id": "22222222222",
"countryCode": "NG",
"idType": "nin"
},
"validations": {
"data": {
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "1990-06-15"
}
}
}'
```
A successful KYC match returns `"status": "found"` with the PII fields retrieved from the authoritative source. A name or date-of-birth mismatch raises a fraud signal automatically.
```json Response — KYC match theme={null}
{
"success": true,
"status_code": 200,
"message": "Identity check successful!",
"data": {
"id": "ent_684f5cc5a47a3926763b83a7",
"entity": {
"entityId": "ent_684f5cc5a47a3926763b83a7",
"isNew": false,
"message": ""
},
"identityCheck": {
"status": "found",
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "1990-06-15",
"phone": "08012345678",
"gender": "Female",
"type": "nin",
"nationality": "NG",
"idNumber": "22222222222",
"verificationId": "69da8ae76398f3a575c950e0"
}
},
"links": []
}
```
***
## Key concepts
Must always be `true`. It certifies that your customer has explicitly consented to identity verification. Omitting it or passing `false` will return a validation error.
Every verification, update, and transaction on the same `ent_…` ID tightens the risk score. You never need to recreate an entity as more data arrives.
Youverify runs sanctions, PEP, watchlist, and adverse-media checks automatically at creation — and again after significant enrichment events. You don't need to trigger these manually.
Entity creation always returns a **Created** status. Approval and rejection are driven by a separate AI-agent workflow that you configure in the dashboard.
***
## What's next
* Set up [webhooks](/webhooks/overview) to receive real-time enrichment and signal events
* Run [AML screening](/api-reference/entities/verify-entity-aml) on the entity at any point in its lifecycle
* Open a [case](/api-reference/cases/create-case) if a signal warrants investigation
* Read the [Entity 360](/concepts/entity-360) to understand what the full entity record contains