> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartcomply.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Vérification de vivacité faciale
> Vérifiez qu'une image faciale soumise appartient à une personne vivante, et non à une photographie ou une vidéo préenregistrée.
L'endpoint de vérification de vivacité faciale analyse un selfie soumis — recommandé sous forme de courte vidéo, bien qu'une photo unique soit également acceptée — pour confirmer qu'il montre une personne vivante, et non une relecture falsifiée (une photo d'une photo, un enregistrement d'écran, etc.). Il note directement la vivacité ; il ne compare pas la soumission à une autre image.
Une vidéo et une photo fixe sont toutes deux authentiquement notées pour la vivacité, donc une image fixe fonctionne également — mais une courte vidéo est la soumission recommandée, car le mouvement donne plus d'informations à la vérification de vivacité. L'endpoint détecte ce qui a été soumis à partir du fichier lui-même.
## Endpoint
```
POST /api/onboarding/biometrics/face/liveliness_check/
```
## Requête
### En-têtes
| En-tête | Valeur | Requis |
| ---------------- | --------------------- | ------ |
| `x-access-token` | Votre clé secrète API | Oui |
| `Content-Type` | `application/json` | Oui |
### Paramètres de corps
| Paramètre | Type | Requis | Description |
| ------------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `live_media` | string | Oui | URL de la courte vidéo selfie à vérifier pour la vivacité (recommandé). Formats vidéo : `.mp4`, `.mov`, `.webm`, `.avi`, `.m4v` — tout autre format est traité comme une image fixe, ce qui est également accepté. |
### Exemple
```bash cURL theme={null}
curl -X POST "https://adhere-api.smartcomply.com/api/onboarding/biometrics/face/liveliness_check/" \
-H "x-access-token: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"live_media": "https://example.com/selfie_liveness.mp4"}'
```
## Réponse
Le statut HTTP est `200` chaque fois que la vérification s'est déroulée jusqu'au bout, **indépendamment du fait que la vivacité ait été validée ou non** — une tentative de vivacité échouée est un résultat de vérification normal et réussi, pas une erreur. Lisez `status`/`data.status` dans le corps pour obtenir le verdict réel ; un `400` signifie que la requête elle-même n'a pas pu être traitée (champ manquant, fichier illisible, problème d'authentification), pas que la vivacité a échoué.
### 200 OK — vivacité validée
| Champ | Type | Description |
| ------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `data.status` | boolean | `true` si la vivacité a été détectée, `false` sinon |
| `data.detail` | string | Résultat lisible par l'homme |
| `data.response_code` | string | `"00"` en cas de réussite, `"01"` en cas d'échec |
| `data.confidence` | number | Score de confiance brut (0–1) |
| `data.confidence_in_percentage` | number | Confiance en pourcentage (0–100) |
| `data.liveness_passed` | boolean | Le verdict de réussite/échec sous-jacent — la valeur dont `data.status` est dérivé |
| `data.verification.status` | string | `"VERIFIED"` ou `"NOT_VERIFIED"` |
| `data.verification.reference` | number | ID d'enregistrement interne pour cette vérification |
```json theme={null}
{
"status": "success",
"data": {
"status": true,
"detail": "Liveliness Detected",
"response_code": "00",
"confidence": 0.968,
"confidence_in_percentage": 96.8,
"liveness_passed": true,
"verification": {
"status": "VERIFIED",
"reference": 76981
},
"widget_info": {},
"session": {}
},
"message": "Vivacité faciale réussie"
}
```
### 200 OK — vivacité échouée (toujours une vérification réussie)
```json theme={null}
{
"status": "failed",
"data": {
"status": false,
"detail": "Liveliness Not Detected",
"response_code": "01",
"confidence": 0.452,
"confidence_in_percentage": 45.2,
"liveness_passed": false,
"verification": {
"status": "NOT_VERIFIED",
"reference": 76982
},
"widget_info": {},
"session": {}
},
"message": "Échec de la vérification de vivacité"
}
```
### 400 Bad Request
Renvoyé lorsque la requête elle-même n'a pas pu être traitée — un champ `live_media` manquant, une URL inaccessible/illisible, ou une erreur inattendue de la vérification sous-jacente.
```json theme={null}
{
"status": "failed",
"data": [],
"message": "live_media is required — provide the URL of the live selfie video or photo."
}
```
### 401 Unauthorized
```json theme={null}
{
"status": "failed",
"message": "Authentication credentials were not provided."
}
```
## OpenAPI
````yaml POST /api/onboarding/biometrics/face/liveliness_check/
openapi: 3.0.3
info:
title: Adhere API
description: >-
Identity verification, credit checks, transaction monitoring, and loan fraud
detection across Africa.
version: 3.0.0
servers:
- url: https://adhere-api.smartcomply.com
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Nigeria KYC
- name: Kenya KYC
- name: Ghana KYC
- name: Rwanda KYC
- name: Uganda KYC
- name: Document Verification
- name: Biometrics
- name: Individual Credit
- name: Business Credit
- name: Transaction Monitoring
- name: Transaction Screening
- name: Transaction KYC
- name: Loan Fraud
- name: User Journey
paths:
/api/onboarding/biometrics/face/liveliness_check/:
post:
tags:
- Biometrics
summary: Face Liveness Check
operationId: faceLiveness
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- live_media
properties:
live_media:
type: string
description: >-
URL of the short selfie video to check for liveness
(recommended — supported formats .mp4, .mov, .webm, .avi,
.m4v). A still selfie photo is also accepted — anything that
isn't one of those video formats is treated as a still
image. Both a video and a still photo are genuinely scored
for liveness; the endpoint detects which was submitted from
the file itself.
responses:
'200':
description: >-
Liveness check ran to completion. Returned for both a pass and a
fail — a failed liveness attempt is a normal, successful check
outcome, not an error. Read data.status / data.liveness_passed for
the real verdict.
content:
application/json:
examples:
livenessPassed:
summary: Liveness passed
value:
status: success
data:
status: true
detail: Liveliness Detected
response_code: '00'
confidence: 0.968
confidence_in_percentage: 96.8
liveness_passed: true
verification:
status: VERIFIED
reference: 76981
widget_info: {}
session: {}
message: Face Liveliness successful
livenessFailed:
summary: Liveness failed (still HTTP 200)
value:
status: failed
data:
status: false
detail: Liveliness Not Detected
response_code: '01'
confidence: 0.452
confidence_in_percentage: 45.2
liveness_passed: false
verification:
status: NOT_VERIFIED
reference: 76982
widget_info: {}
session: {}
message: Liveness check failed
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
components:
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: failed
data:
type: array
items: {}
message:
type: string
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: failed
message:
type: string
example: Authentication credentials were not provided.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-access-token
description: Your Adhere API secret key
````