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

# Comparaison faciale

> Comparez deux images de visage pour déterminer si elles appartiennent à la même personne.

L'endpoint de comparaison faciale utilise l'analyse biométrique pour comparer deux images de visage et renvoie un score de confiance indiquant si elles représentent le même individu. Utilisez-le pour la vérification d'identité lors de l'intégration ou de l'approbation de transaction.

Avant de comparer, le fournisseur exécute une vérification anti-spoofing sur `selfie_url` ; si cette vérification échoue, aucune comparaison n'est tentée et la réponse l'indique explicitement — voir [200 OK — rejeté par la vérification anti-spoofing](#200-ok-rejeté-par-la-vérification-anti-spoofing-aucune-comparaison-effectuée) ci-dessous.

## Endpoint

```
POST /api/onboarding/biometrics/face/comparison
```

## 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                                                                   |
| ------------ | ------ | ------ | ----------------------------------------------------------------------------- |
| `image_url`  | string | Oui    | URL de la photo d'identité de référence ou image de visage de base de données |
| `selfie_url` | string | Oui    | URL du selfie en direct à comparer avec la référence                          |

### Exemple

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://adhere-api.smartcomply.com/api/onboarding/biometrics/face/comparison" \
    -H "x-access-token: YOUR_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "image_url": "https://example.com/id_photo.jpg",
      "selfie_url": "https://example.com/selfie.jpg"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://adhere-api.smartcomply.com/api/onboarding/biometrics/face/comparison",
    {
      method: "POST",
      headers: {
        "x-access-token": "YOUR_SECRET_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        image_url: "https://example.com/id_photo.jpg",
        selfie_url: "https://example.com/selfie.jpg",
      }),
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://adhere-api.smartcomply.com/api/onboarding/biometrics/face/comparison",
      headers={
          "x-access-token": "YOUR_SECRET_KEY",
          "Content-Type": "application/json",
      },
      json={
          "image_url": "https://example.com/id_photo.jpg",
          "selfie_url": "https://example.com/selfie.jpg",
      },
  )
  data = response.json()
  ```
</CodeGroup>

## Réponse

### 200 OK

| Champ                | Type    | Description                                         |
| -------------------- | ------- | --------------------------------------------------- |
| `data.status`        | boolean | `true` si les visages correspondent, `false` sinon  |
| `data.response_code` | string  | `"00"` indique une comparaison réussie              |
| `data.message`       | string  | Résultat de correspondance lisible par l'homme      |
| `data.confidence`    | integer | Pourcentage de confiance de correspondance (0–100)  |
| `data.record_id`     | number  | ID d'enregistrement interne pour cette vérification |

```json theme={null}
{
  "status": "success",
  "data": {
    "status": true,
    "response_code": "00",
    "message": "Face Match",
    "confidence": 100,
    "record_id": 76981
  },
  "message": "Comparaison faciale effectuée avec succès"
}
```

Un `data.status` à `false` indique que les visages ne correspondent pas. Utilisez `data.confidence` pour appliquer votre propre seuil d'acceptation (ex: exigez `>= 80` pour une correspondance positive).

### 200 OK — rejeté par la vérification anti-spoofing (aucune comparaison effectuée)

Avant de comparer les deux images, le fournisseur exécute sa propre vérification anti-spoofing sur `selfie_url` — cela détecte une photo de photo, une relecture d'écran ou toute autre soumission falsifiée. Si `selfie_url` échoue à cette vérification, la comparaison elle-même ne s'exécute jamais, et la réponse explique pourquoi dans `data.message` plutôt que de simplement dire que les visages ne correspondent pas. `data.confidence` est à `0` dans ce cas puisqu'aucun score de correspondance n'a été produit.

<Note>
  Cette vérification s'exécute même si `selfie_url` est une image fixe, et non une vidéo — le texte du message ci-dessous fait toujours référence à "la vidéo soumise" car il est partagé avec le libellé interne de l'endpoint de vérification de vivacité faciale. Traitez cette réponse de la même manière, que vous ayez soumis une photo ou une vidéo en tant que selfie.
</Note>

```json theme={null}
{
  "status": "failed",
  "data": {
    "status": false,
    "response_code": "01",
    "message": "Liveness check failed — the submitted video did not pass the liveness/anti-spoofing check, so no face comparison was performed.",
    "confidence": 0
  },
  "message": "Liveness check failed — the submitted video did not pass the liveness/anti-spoofing check, so no face comparison was performed."
}
```

Demandez à l'utilisateur un selfie plus clair (meilleur éclairage, pas d'écran/photo dans le cadre) et soumettez à nouveau — ce n'est pas la même erreur qu'une véritable inadéquation faciale, et réessayer avec un selfie de meilleure qualité de la même personne est la bonne étape suivante.

### 400 Bad Request

Renvoyé lorsque l'une ou les deux URL d'image sont manquantes, inaccessibles ou ne contiennent pas de visage détectable.

```json theme={null}
{
  "status": "failed",
  "data": [],
  "message": "Could not process one or both images"
}
```

### 401 Unauthorized

```json theme={null}
{
  "status": "failed",
  "message": "Authentication credentials were not provided."
}
```


## OpenAPI

````yaml POST /api/onboarding/biometrics/face/comparison
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/comparison:
    post:
      tags:
        - Biometrics
      summary: Face Comparison
      operationId: faceComparison
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
                - selfie_url
              properties:
                image_url:
                  type: string
                  description: URL of the reference ID photo
                selfie_url:
                  type: string
                  description: URL of the selfie image
      responses:
        '200':
          description: >-
            Comparison ran to completion. This includes the anti-spoofing
            rejection case below — the provider still returns HTTP 200 with
            status "failed" when selfie_url fails its own liveness check before
            any comparison is attempted.
          content:
            application/json:
              examples:
                facesMatch:
                  summary: Faces match
                  value:
                    status: success
                    data:
                      status: true
                      response_code: '00'
                      message: Face Match
                      confidence: 100
                      record_id: 76981
                    message: Face comparison completed successfully
                facesDoNotMatch:
                  summary: Faces do not match
                  value:
                    status: failed
                    data:
                      status: false
                      response_code: '01'
                      message: Face Mismatch
                      confidence: 42
                      record_id: 76982
                    message: Face comparison failed — faces do not match
                antiSpoofingRejected:
                  summary: Rejected by anti-spoofing check (no comparison performed)
                  value:
                    status: failed
                    data:
                      status: false
                      response_code: '01'
                      message: >-
                        Liveness check failed — the submitted video did not pass
                        the liveness/anti-spoofing check, so no face comparison
                        was performed.
                      confidence: 0
                    message: >-
                      Liveness check failed — the submitted video did not pass
                      the liveness/anti-spoofing check, so no face comparison
                      was performed.
        '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

````