API de contrôle de l'âge

Estimez à partir d'un selfie si une personne est majeure, avec un repli sur la date de naissance figurant sur une pièce d'identité lorsque l'estimation est trop proche du seuil.

POST /api/v1/kyc/age-estimation estime l'âge apparent du visage sur un selfie et le compare à un âge minimum. Il s'agit du même contrôle que l'option Contrôle de l'âge des formulaires (voir Contrôle de l'âge), mais disponible seul.

Le résultat est une estimation à partir d'une photo, et non une preuve d'âge. Chaque réponse le précise (isEstimate, disclaimer). À proximité de votre seuil, la réponse est inconclusive par conception : basculez sur une vérification de pièce d'identité.

Authentifiez-vous avec une clé d'API (Authorization: Bearer ck_live_…) dotée de la portée kyc:write. Voir Authentification. La photo est traitée en mémoire et n'est jamais conservée.

Requête

Envoyez soit du multipart/form-data, soit du JSON.

curl -X POST https://app.certivant.com/api/v1/kyc/age-estimation \
  -H "Authorization: Bearer $CERTIVANT_API_KEY" \
  -H "Idempotency-Key: signup-8841" \
  -F image=@selfie.jpg \
  -F minAge=18 \
  -F buffer=5

{
  "imageBase64": "/9j/4AAQSkZJRg…",
  "minAge": 18,
  "buffer": 5,
  "dateOfBirth": "1990-02-03"
}

Champ	Type	Remarques
`image` / `imageBase64`	fichier / chaîne	Un selfie de face avec un seul visage. JPEG, PNG, WebP ou HEIC, jusqu'à 10 Mo. Une URL `data:` est acceptée
`minAge`	entier de 1 à 120, facultatif	Par défaut, le paramètre de votre organisation (Paramètres → Prévention de la fraude), 18 à l'origine
`buffer`	entier de 0 à 30, facultatif	Nombre d'années de part et d'autre de `minAge` dans lequel l'estimation n'est pas jugée fiable. Par défaut, le paramètre de votre organisation, 5 à l'origine
`dateOfBirth`	`YYYY-MM-DD`, facultatif	La date de naissance figurant sur une pièce d'identité déjà vérifiée. Utilisée lorsque l'estimation n'est pas concluante

Envoyez un en-tête Idempotency-Key pour rendre une nouvelle tentative sans frais : la même clé n'est facturée qu'une fois.

Réponse

{
  "data": {
    "result": "pass",
    "method": "estimate",
    "minAge": 18,
    "buffer": 5,
    "isEstimate": true,
    "estimatedAge": 31.4,
    "estimateSpread": 3.2,
    "estimateConfidence": "high",
    "disclaimer": "An estimate from a photo, not proof of age.",
    "chargedCents": 7
  }
}

Champ	Remarques
`result`	`pass`, `fail` ou `inconclusive`
`method`	`estimate` : le selfie a tranché ; `id_document` : `dateOfBirth` a tranché ; `none` : rien n'a pu trancher
`isEstimate`	`true` lorsque l'estimation à partir du selfie fait partie de la réponse
`estimatedAge`, `estimateSpread`, `estimateConfidence`	L'estimation en années, son degré d'incertitude, et `high` ou `low`. Présents lorsqu'une estimation a été faite
`idAge`	Âge en années entières calculé à partir de `dateOfBirth`, lorsqu'il a été utilisé
`fallbackReason`	Raison pour laquelle la pièce d'identité était nécessaire : `near_limit`, `low_confidence`, `no_estimate` ou `estimate_mismatch`
`mismatch`	Une estimation fiable et la pièce d'identité sont en désaccord. À traiter comme un cas d'examen manuel
`idCheckRequired`	`true` lorsque le résultat est `inconclusive` et que vous n'avez pas envoyé de `dateOfBirth` : effectuez une vérification de pièce d'identité puis rappelez l'API avec la date de naissance, ou orientez la personne vers une vérification
`disclaimer`	Toujours présent. Affichez-le partout où vous présentez l'estimation
`chargedCents`	Coût de cet appel

Comment la décision est prise

Estimation supérieure ou égale à minAge + buffer → pass.
Estimation inférieure à minAge − buffer → fail.
Entre les deux, ou lorsque le modèle doute de son estimation → c'est dateOfBirth qui tranche, si vous en avez envoyé une. Sans elle, le résultat est inconclusive.
Lorsque vous envoyez un dateOfBirth qui contredit clairement l'estimation, mismatch vaut true : une estimation très supérieure au seuil combinée à une date de naissance indiquant un mineur donne fail (la date de naissance l'emporte) ; une estimation très inférieure au seuil combinée à une date de naissance indiquant un adulte donne inconclusive, afin qu'une personne examine le cas.

Erreurs

Statut	Quand
`400`	Image, `minAge`, `buffer` ou `dateOfBirth` absent ou invalide
`402`	Crédit insuffisant pour effectuer le contrôle
`403`	L'estimation de l'âge n'est pas incluse dans votre forfait
`413`	Image supérieure à 10 Mo
`415`	Type d'image non pris en charge
`422`	Aucun visage exploitable n'a été trouvé (et aucun `dateOfBirth` pour se replier)
`502`	Le service d'estimation est indisponible. Réessayez avec la même `Idempotency-Key`

Lorsqu'aucun visage n'est trouvé mais que vous avez envoyé un dateOfBirth, l'appel répond tout de même à partir de la pièce d'identité (method: "id_document").

Facturation

L'estimation de l'âge est une fonctionnalité de forfait, avec un quota mensuel inclus et un prix à l'utilisation par contrôle, prélevé sur votre solde de crédits. Un appel qui renvoie 402 ou 403 n'est pas facturé. Chaque contrôle est enregistré dans votre journal d'audit (age_estimation.checked) avec le résultat et la méthode, jamais la photo ni la date de naissance.

Sur une vérification

Lorsqu'un formulaire active le contrôle de l'âge, la vérification elle-même porte le résultat : ses déclencheurs de révision ou ses causes de disqualification peuvent contenir age_requirement_not_met ou age_check_inconclusive, et les politiques et workflows peuvent tester age.checked, age.result, age.method, age.estimatedAge, age.minimum, age.meetsMinimum et age.mismatch.