Contrôle eID

Un contrôle eID prouve qu’un client qui n’est pas devant vous est bien la personne figurant sur sa pièce d’identité. Le client reçoit un courriel avec un PIN et un lien, scanne une pièce d’identité et prend un selfie dans l’application du fournisseur eID. Trois endpoints couvrent le parcours. Scope pour les trois : kyc:eid. Dans cette version, le moteur n’accepte que les clients canadiens pour l’eID. Les exemples de cette page utilisent donc le pays CA, contrairement aux autres guides, qui utilisent MA.

Endpoint	Fonction
`POST /v1/kyc/eid`	Démarre le contrôle. Le fournisseur envoie aussitôt un courriel au client. Renvoie HTTP 201 et une `key`.
`GET /v1/kyc/eid/{key}`	Où en est le contrôle, ce qu’il a prouvé, et ses contrôles.
`GET /v1/kyc/eid/{key}/report`	Le rapport PDF du fournisseur sur le contrôle.

Avant de commencer

Condition	Si elle n’est pas remplie
Le client est canadien : `country` vaut `CA` ou `CAN`.	422 `identity verification is available for Canadian clients only`
Votre espace de travail a son propre compte chez le fournisseur eID. Sahl le configure.	404 `identity verification is not set up for this tenant`
La clé a le scope `kyc:eid` et l’espace de travail est activé pour l’API Partner.	403

environment ne change pas le fournisseur. Une requête faite avec environment: "sandbox" envoie quand même un courriel au client et appelle quand même le fournisseur. environment choisit seulement le dossier sur lequel la requête est classée. Utilisez une adresse courriel que vous contrôlez pour vos tests.

Démarrer un contrôle

{
  "reference": "client-0001",
  "first_name": "Test",
  "last_name": "Client",
  "email": "test.client@example.com",
  "country": "CA",
  "language": "en",
  "documents": 1,
  "environment": "sandbox"
}

Champ	Type	Par défaut	Règle
`reference`	string	obligatoire	De 1 à 64 caractères parmi `A-Z a-z 0-9 _ . : -`. Votre identifiant du client.
`first_name`	string	obligatoire	De 1 à 100 caractères.
`last_name`	string	obligatoire	De 1 à 100 caractères.
`email`	string	obligatoire	Un courriel valide. Le PIN et le lien y sont envoyés.
`country`	string	obligatoire	2 ou 3 caractères. Seuls `CA` ou `CAN` sont acceptés.
`language`	string	`en`	`en` ou `fr`.
`documents`	entier	`1`	`1` ou `2` : combien de pièces d’identité le client doit scanner.
`environment`	string	`sandbox`	`sandbox` ou `production`. Choisit le dossier.

La réponse :

{ "key": 123456, "reference": "client-0001" }

key est l’identifiant avec lequel vous interrogez. Le PIN est envoyé au client uniquement et ne vous est jamais renvoyé. La requête est classée comme pending sur le dossier de (espace de travail, environnement, reference). Une nouvelle requête pour la même référence et le même environnement remplace l’enregistrement, car vous avez recommencé la vérification du client. Le fournisseur stocke la requête sous un identifiant client composé de votre espace de travail et de votre référence, ce qui empêche un autre espace de travail de la lire.

curl -X POST https://app.sahlfinancial.com/api/v1/kyc/eid \
  -H "Authorization: Bearer $SAHL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference":"client-0001","first_name":"Test","last_name":"Client","email":"test.client@example.com","country":"CA","language":"en","documents":1,"environment":"sandbox"}'

const res = await fetch("https://app.sahlfinancial.com/api/v1/kyc/eid", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAHL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference: "client-0001",
    first_name: "Test",
    last_name: "Client",
    email: "test.client@example.com",
    country: "CA",
    language: "en",
    documents: 1,
    environment: "sandbox",
  }),
});
if (res.status !== 201) throw new Error(`${res.status} ${await res.text()}`);
const { key } = await res.json();

import os, requests

res = requests.post(
    "https://app.sahlfinancial.com/api/v1/kyc/eid",
    headers={"Authorization": f"Bearer {os.environ['SAHL_API_KEY']}"},
    json={
        "reference": "client-0001",
        "first_name": "Test",
        "last_name": "Client",
        "email": "test.client@example.com",
        "country": "CA",
        "language": "en",
        "documents": 1,
        "environment": "sandbox",
    },
    timeout=60,
)
assert res.status_code == 201, res.text
key = res.json()["key"]

États

Le fournisseur n’envoie aucun rappel. Vous interrogez GET /v1/kyc/eid/{key}. Sahl déduit l’état de l’interrogation.

État	`complete`	`passed`	Ce que vous faites
`pending`	false	false	Continuez d’interroger. Le contrôle `eid:completed` dit `the client has not completed the verification yet`.
`passed`	true	true	Utilisez-le. Téléchargez le rapport.
`failed`	true	false	Regardez quel contrôle `eid:` a échoué. Démarrez une nouvelle requête pour réessayer.
`archived`	false	false	La requête a été archivée sans contrôle terminé. `eid:completed` dit `the request was archived without a completed verification`. Démarrez une nouvelle requête.

pending, passed, failed et archived sont aussi le statut que Sahl enregistre sur le dossier. Seul passed satisfait l’exigence eID d’une politique.

Interroger

GET /v1/kyc/eid/{key} a un seul paramètre de requête facultatif, environment (sandbox par défaut). Il ne sert qu’à situer une requête démarrée avant que Sahl ne conserve l’enregistrement eID. Une requête faite via POST /v1/kyc/eid garde son propre environnement. Sahl ne fixe aucun intervalle d’interrogation. Le seul plafond est de 100 requêtes par minute et par IP. Un rythme raisonnable : toutes les 30 secondes pendant les 10 premières minutes, puis toutes les 5 minutes. Le client doit ouvrir le courriel, donc des minutes ou des heures sont normales. Un contrôle terminé (complete ou archived) est le moment où Sahl enregistre le résultat sur le dossier, et la première interrogation qui le voit envoie le webhook kyc.eid_completed. Les interrogations suivantes restent silencieuses.

Réponse une fois terminé

{
  "key": 123456,
  "complete": true,
  "passed": true,
  "identity": {
    "documentType": "PASSPORT",
    "documentNumber": "P1234567",
    "expiryDate": "2030-05-01",
    "birthDate": "1988-04-12",
    "firstName": "Test",
    "lastName": "Client"
  },
  "checks": [
    { "id": "eid:liveness", "label": "Selfie passed the liveness check", "severity": "critical", "passed": true, "detail": "" },
    { "id": "eid:face_match", "label": "Face on the ID matches the selfie (score 3 or more)", "severity": "critical", "passed": true, "detail": "score 4 of 4, confidence 97%" },
    { "id": "eid:name_match", "label": "Name on the ID matches the name on the request", "severity": "critical", "passed": true, "detail": "" }
  ],
  "completed_date": "2026-10-07T12:00:00Z"
}

Les valeurs sont fictives, produites par la même fonction que celle de l’API.

Clé	Signification
`key`	L’identifiant de la requête.
`complete`	Vrai dès que le client a scanné un document.
`passed`	Vrai quand `complete` et qu’aucun contrôle de sévérité `critical` n’a échoué.
`identity`	Ce que le contrôle a prouvé. Clés possibles : `documentType`, `documentNumber`, `expiryDate`, `birthDate`, `firstName`, `lastName`, `address`. Présentes seulement pour les valeurs que le fournisseur détient. Vide tant que ce n’est pas terminé.
`checks`	Les contrôles eID, dans la même forme que les contrôles de vérification.
`completed_date`	Heure de fin telle que le fournisseur la rapporte, ou null.

Les contrôles

Id	Sévérité	Réussi quand
`eid:completed`	critical	Présent seulement jusqu’à ce que le client termine. Toujours échoué.
`eid:liveness`	critical	Le selfie a passé le contrôle de vivacité.
`eid:face_match`	critical	Le score de correspondance du visage est de 3 ou plus (le détail montre `score N of 4` et la confiance).
`eid:name_match`	critical	Le nom sur la pièce d’identité correspond au nom de votre requête. C’est pourquoi le prénom et le nom que vous envoyez doivent être exacts.
`eid:message:N`	critical ou warning	Le fournisseur a renvoyé un message. Toujours échoué. Voir ci-dessous.

Messages du fournisseur et leur sévérité :

Message	Sévérité
`The machine readable values of one or more fields do not match.`	critical
`Document is past expiry date.`	critical
`Name entered on request does not match name on document.`	critical
`Low face match score.`	critical
`No machine readable data found on document.`	warning
tout autre message	warning

Rapport

GET /v1/kyc/eid/{key}/report renvoie le rapport du fournisseur en application/pdf avec Content-Disposition: attachment; filename="eid-<key>.pdf". Il est destiné au dossier du client.

curl -o eid-123456.pdf https://app.sahlfinancial.com/api/v1/kyc/eid/123456/report \
  -H "Authorization: Bearer $SAHL_API_KEY"

Conserver le résultat

Récupérez le résultat et le PDF dans les sept jours environ qui suivent le contrôle. Passé ce délai, le fournisseur supprime les données personnelles. Sahl enregistre le résultat (statut, heure de fin) sur votre dossier quand une interrogation voit pour la première fois l’état final, mais le bloc identity et le PDF viennent du fournisseur, donc conservez ce dont vous avez besoin.

Satisfaire l’exigence eID d’une politique

Une politique d’espace de travail peut exiger un contrôle eID à distance pour une personne non rencontrée en face à face (eid_required_non_face_to_face). /verify et /assess ajoutent alors un contrôle critical policy:eid_non_face_to_face :

Situation	Contrôle
Une requête avec cette `reference` et cet `environment` a été faite via `POST /v1/kyc/eid` et son statut enregistré est `passed`	réussi : `eID request N passed`
Aucune requête enregistrée	échoue : `the client was not met in person and no eID request made through Sahl (POST /v1/kyc/eid) is on file for this reference and environment`
Requête en attente	échoue : `eID request N has not been seen completed; poll GET /v1/kyc/eid/{key} once the client has finished`
Requête échouée ou archivée	échoue : `eID request N ended failed` (ou `archived`)
`values.verified_in_person` vaut true	non appliqué. Un contrôle info `policy:met_in_person_declared` consigne que c’est votre déclaration et que Sahl ne l’a pas vérifiée.
`purpose` vaut `periodic_review`	non appliqué

Seul l’enregistrement de Sahl satisfait l’exigence. Un contrôle que vous envoyez dans extra_checks avec un id commençant par eid: est renommé partner:eid:... et ne compte jamais. Utilisez la même reference et le même environment pour la requête eID et pour l’appel /verify. Interrogez jusqu’à la fin du contrôle avant d’appeler /verify, car le résultat est enregistré par l’interrogation.

Erreurs

Statut	Corps	Cause
401, 403	Voir erreurs	Problèmes de clé.
404	`identity verification is not set up for this tenant`	Aucun compte fournisseur sur l’espace de travail.
404	`Not Found`	`key` inconnue, ou clé démarrée par un autre espace de travail.
422	`identity verification is available for Canadian clients only`	`country` n’est ni `CA` ni `CAN`.
422	liste `detail`	Un champ ne respecte pas le schéma, par exemple `documents` ne vaut ni 1 ni 2.
502	`the identity verification service did not answer`	Le fournisseur est indisponible ou a refusé. Réessayez plus tard.

Démarrer

Connexions bancaires et open banking

Documents (OCR)

Vérification et eID

Évaluation du risque et scoring

Construire

Référence

Console uniquement

Avant de commencer

Démarrer un contrôle

États

Interroger

Réponse une fois terminé

Les contrôles

Rapport

Conserver le résultat

Satisfaire l’exigence eID d’une politique

Erreurs

​Avant de commencer

​Démarrer un contrôle

​États

​Interroger

​Réponse une fois terminé

​Les contrôles

​Rapport

​Conserver le résultat

​Satisfaire l’exigence eID d’une politique

​Erreurs

Avant de commencer

Démarrer un contrôle

États

Interroger

Réponse une fois terminé

Les contrôles

Rapport

Conserver le résultat

Satisfaire l’exigence eID d’une politique

Erreurs