> ## 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.

# Intégrer un client que vous ne connaissez que par e-mail

> Créez une entité avec un simple e-mail, recevez instantanément un score de risque AML et enrichissez progressivement le dossier à mesure que de nouvelles données client arrivent, sans doublons.

Les processeurs de paiement et les PSP intègrent régulièrement des marchands ou des utilisateurs finaux qui ne communiquent rien de plus qu'une adresse e-mail lors de l'inscription. Le modèle d'entité de Youverify est conçu précisément pour ce cas : vous créez l'entité avec un minimum de données, la plateforme la contrôle immédiatement par rapport aux bases AML, puis vous enrichissez le dossier progressivement à mesure que des informations deviennent disponibles, sans jamais créer de doublon.

> [!NOTE]
>
> Le parcours de création par e-mail seul est réservé aux **entités en aval** : marchands, fintechs ou utilisateurs finaux qui appartiennent à un client de la plateforme plutôt que directement à votre organisation. Définissez `isSubjectConsent: true` dans chaque requête pour confirmer que la personne concernée a consenti à la vérification.

## Prérequis

* Un compte Youverify sur [cowork.youverify.co](https://cowork.youverify.co)
* Votre clé secrète d'API (à récupérer dans le tableau de bord sous **Settings → API Keys**)
* Des webhooks configurés pour recevoir les événements d'enrichissement et de signaux (recommandé)

***

## Étapes

### Créer l'entité avec un simple e-mail

Envoyez une requête `POST /v2/api/entities` contenant uniquement `entityType`, `isSubjectConsent` et `email`. La plateforme crée l'entité, exécute automatiquement un contrôle AML (sanctions, PEP, listes de surveillance, médias défavorables) sur les données disponibles, et renvoie une entité au statut **Created** avec un score de risque initial.

```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']
```

La réponse confirme la création de l'entité et renvoie son identifiant stable `ent_…` :

```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": []
}
```

> [!TIP]
>
> Stockez l'`id` renvoyé (`ent_…`) dans votre base de données, à côté de votre propre fiche client. Tous les appels suivants (enrichissement, KYC, contrôle AML, enregistrement de transactions) référencent cet identifiant unique. **Créez une fois, référencez toujours.**

### Surveiller immédiatement via les webhooks

Dès que l'entité est créée, Youverify exécute automatiquement en arrière-plan un contrôle AML. Vous n'avez pas besoin de le déclencher. Abonnez-vous aux événements webhook `entity.created` et `entity.risk_score_updated` afin que votre système reçoive le score de risque initial, ainsi que ses évolutions, dès qu'ils sont calculés.

Configurez votre point de terminaison webhook dans le tableau de bord sous **Settings → Webhooks**, puis écoutez la structure de charge utile suivante :

```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"]
  }
}
```

> [!NOTE]
>
> À la création, le score de risque ne reflète que les données AML. Il n'existe pas encore d'historique comportemental : Fraud Insight enrichit le score au fil du temps, à mesure que l'entité effectue des transactions et génère des signaux.

### Enrichir au fil du temps à mesure que les données arrivent

Lorsque le client fournit des informations supplémentaires (nom, numéro de téléphone, date de naissance ou pièce d'identité officielle), mettez à jour la même entité au lieu d'en créer une nouvelle. Chaque enrichissement réévalue le score de risque sur la base du profil plus complet.

**Ajouter le nom et le téléphone**

```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"
  }'
```

**Ajouter la nationalité**

```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"
  }'
```

### Déclencher le KYC lorsque vous disposez de suffisamment de données

Dès que vous détenez un numéro de pièce d'identité officielle, lancez une vérification KYC directement sur l'entité. Le résultat (statut de correspondance, données personnelles renvoyées et éventuels signaux de fraude) est rattaché au dossier 360 de l'entité au lieu de rester un rapport orphelin.

```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"
      }
    }
  }'
```

Une correspondance KYC réussie renvoie `"status": "found"` avec les champs de données personnelles récupérés depuis la source faisant autorité. Une discordance sur le nom ou la date de naissance déclenche automatiquement un signal de fraude.

```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": []
}
```

***

## Concepts clés

> **isSubjectConsent**
>
> Doit toujours être `true`. Ce champ certifie que votre client a explicitement consenti à la vérification d'identité. L'omettre ou transmettre `false` renvoie une erreur de validation.

> **Enrichissement progressif**
>
> Chaque vérification, mise à jour et transaction associée au même identifiant `ent_…` affine le score de risque. Vous n'avez jamais besoin de recréer une entité lorsque de nouvelles données arrivent.

> **Contrôle AML automatique**
>
> Youverify exécute automatiquement des contrôles de sanctions, PEP, listes de surveillance et médias défavorables à la création, puis de nouveau après les événements d'enrichissement significatifs. Vous n'avez pas besoin de les déclencher manuellement.

> **Created, et non approuvé**
>
> La création d'une entité renvoie toujours le statut **Created**. L'approbation et le rejet relèvent d'un workflow distinct d'agents IA que vous configurez dans le tableau de bord.

***

## Et ensuite

* Configurez les [webhooks](https://doc.youverify.co/fr/webhooks/overview.md) pour recevoir en temps réel les événements d'enrichissement et de signaux
* Lancez un [contrôle AML](https://doc.youverify.co/api-reference/entities/verify-entity-aml) sur l'entité à n'importe quel moment de son cycle de vie
* Ouvrez un [dossier](https://doc.youverify.co/api-reference/cases/create-case) si un signal justifie une investigation
* Consultez l'[Entity 360](https://doc.youverify.co/fr/concepts/entity-360.md) pour comprendre ce que contient le dossier complet d'une entité


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.