Référence de l'API
La référence de l'API de vérification d'identité.
Chaque point de terminaison que vous pouvez appeler, chaque champ que vous recevrez en retour et la marche à suivre avec un webhook à son arrivée. Pour connaître les types de champs exacts, considérez le document OpenAPI en ligne à /docs sur votre propre origine d'API comme la source de référence — cette page en est la version en langage clair.
URL de base et environnements
Une seule URL de base. Deux environnements.
Chaque requête est envoyée au même hôte. L'environnement dans lequel vous vous trouvez est déterminé uniquement par la clé API que vous envoyez.
| URL de base (cette documentation) | https://api.shieldid.ca — illustrative; your production API origin is published together with your API keys. |
|---|---|
| En-tête d'authentification | X-Api-Key: <your key>, sur chaque requête sauf les deux points de terminaison publics indiqués ci-dessous. |
| Préfixe de clé de bac à sable | vk_sand_… — les sessions créées avec cette clé sont marquées environment: "sandbox" et ne sont jamais facturées. |
| Préfixe de clé de production | vk_live_… — les mêmes requêtes, facturées selon votre forfait. |
| Type de contenu | application/json pour chaque corps de requête et de réponse. |
Points de terminaison
L'ensemble de la surface v1.
Six points de terminaison JSON, plus une page hébergée et une vérification publique d'identifiants qui ne sont pas du tout en JSON : il suffit d'y faire un lien.
| Endpoint | Auth | What it does |
|---|---|---|
| POST /v1/sessions | X-Api-Key | Créer une session de vérification. Exige un return_url et un webhook_url. Retourne session_id, verification_url et status: "PENDING". |
| GET /v1/sessions/{id} | X-Api-Key | État et champs principaux d'une session : status, confidence, environment. |
| GET /v1/sessions/{id}/result | X-Api-Key | Le résultat complet une fois qu'une session atteint VERIFIED ou FAILED : person, verdicts par vérification, confidence, verified_until. |
| DELETE /v1/sessions/{id} | X-Api-Key | Annulez une session toujours PENDING ou IN_PROGRESS. Une session déjà à l'état VERIFIED, FAILED ou EXPIRED ne peut pas être annulée. |
| GET /v1/credentials/{token} | None — public | Vérifier si un identifiant vérifié est actuellement valide. Aucune clé API requise, donc appelable depuis un navigateur. Remarque : la réponse actuelle inclut aussi le nom de la personne vérifiée ainsi que le type et le pays du document, et non seulement un indicateur valide/invalide — ne transmettez pas ce lien à un tiers à qui vous ne voulez pas révéler ces renseignements. |
| GET /v1/pricing/{country} | X-Api-Key | Tarification par pays pour un code de pays ISO 3166-1 à deux lettres. |
| /v/{session_id} | La page de vérification hébergée — le verification_url retourné par une session. Sur ordinateur, elle affiche un code QR; en le balayant, le téléphone du demandeur reçoit le même lien pour saisir son document et son égoportrait. |
|---|---|
| /c/{session_id} | Une page publique et sans authentification de vérification d'identifiant pour une session vérifiée. Remarque : la réponse actuelle inclut aussi le nom de la personne vérifiée ainsi que le type et le pays du document, et non seulement un indicateur valide/invalide — ne transmettez pas ce lien à un tiers à qui vous ne voulez pas révéler ces renseignements. |
| /docs | La référence OpenAPI interactive en direct pour l'origine d'API de votre compte. |
Création d'une session
POST /v1/sessions, de bout en bout.
La requête, et exactement ce qui est renvoyé.
curl -X POST https://api.shieldid.ca/v1/sessions \
-H "X-Api-Key: vk_sand_your_key" \
-H "Content-Type: application/json" \
-d '{
"return_url": "https://yourapp.example/verified",
"webhook_url": "https://yourapp.example/hooks/shieldid",
"expected_name": "Jordan Smith",
"locale": "en",
"metadata": { "application_id": "app_9182" }
}'| return_url | chaîne, obligatoire — Où le demandeur est redirigé une fois qu'il a terminé. Doit être http ou https. |
|---|---|
| webhook_url | chaîne, obligatoire — Où le résultat signé est transmis. Voir Webhooks ci-dessous. |
| expected_name | chaîne, obligatoire — Le nom que vous attendez sur le document, utilisé pour recouper ce que la pièce d'identité indique réellement. |
| expected_dob / expected_address | chaîne, facultatif — Recoupé avec le document lorsqu'il est fourni; non requis pour effectuer une vérification. |
| locale | chaîne, facultatif — "en" ou "fr". Définit la langue de la page hébergée que voit le demandeur. |
| metadata | objet, facultatif — Vos propres données de référence — un identifiant de demande, un identifiant de client, tout ce que vous voulez retrouver tel quel dans le résultat et le webhook. |
Le résultat
GET /v1/sessions/{id}/result — forme de la réponse.
La même structure est transmise dans la charge utile du webhook, de sorte que vous avez rarement besoin d'interroger ce point de terminaison.
| session_id | L'identifiant que vous avez créé. |
|---|---|
| status | PENDING, IN_PROGRESS, VERIFIED, FAILED ou EXPIRED. |
| environment | "sandbox" ou "production", selon la clé qui a créé la session. |
| person | Les champs lus dans le document : nom, date de naissance, type de document, pays et province ou territoire du document, adresse. |
| checks | Un verdict par vérification — voir ci-dessous. Jamais un score opaque unique. |
| confidence | Un chiffre global unique pour la vérification. Les vérifications individuelles, y compris la comparaison faciale, sont toujours présentées séparément par rapport à un seuil de décision fixe — ce champ ne les remplace pas. |
| verified_until | Durée pendant laquelle le résultat est considéré comme à jour, pour une session VERIFIED. |
| failure_reason | Défini sur une session FAILED — par exemple FACE_MATCH_BELOW_THRESHOLD ou CANCELLED_BY_API. null dans les autres cas. |
| metadata | Tout ce que vous avez envoyé lors de la création de la session, tel quel. |
{
"session_id": "ses_9f2c1a",
"status": "VERIFIED",
"environment": "sandbox",
"person": {
"name": "Jordan Smith",
"dob": "1994-03-11",
"document_type": "drivers_licence",
"document_country": "CA",
"document_jurisdiction": "ON"
},
"checks": {
"document": "PASS",
"liveness": "PASS",
"antispoof": "PASS",
"face_match": "PASS"
},
"confidence": 88,
"verified_until": "2027-03-11T00:00:00Z",
"failure_reason": null,
"metadata": { "application_id": "app_9182" }
}Add-onchecks.document, checks.liveness, checks.antispoof et checks.face_match se résolvent chacun en PASS, FAIL ou SKIPPED. Le filtrage des listes de surveillance (checks.sanctions — CLEAR, MATCH ou SKIPPED) est un module complémentaire et n'apparaît que pour les comptes qui l'activent.
Cycle de vie de la session
Cinq états, un seul parcours.
Une session progresse d'elle-même; vous ne pilotez pas la machine à états, vous ne faites que la lire.
| PENDING | Créée. Personne n'a encore ouvert la verification_url. |
|---|---|
| IN_PROGRESS | Le demandeur a ouvert le lien et se trouve quelque part dans le parcours de capture. |
| VERIFIED | Toutes les vérifications ont été exécutées et le résultat est prêt. État final — appelez le point de terminaison du résultat ou lisez le webhook. |
| FAILED | Au moins une vérification n'a pas été réussie. failure_reason indique laquelle. Bientôt disponible : une nouvelle tentative qui réinitialise la session à PENDING — d'ici là, considérez FAILED comme un état final et créez une nouvelle session si le demandeur souhaite réessayer. |
| EXPIRED | Personne n'a terminé à temps. Les sessions expirent automatiquement après un délai par défaut (30 minutes); créez-en une nouvelle pour réessayer. |
DELETE /v1/sessions/{id} annule de façon anticipée une session PENDING ou IN_PROGRESS. Une session ayant déjà atteint l'état VERIFIED, FAILED ou EXPIRED ne peut pas être annulée : elle est déjà terminée.
Erreurs
Ce qu'il faut prévoir.
Voici la liste restreinte sur laquelle il vaut la peine de coder dès aujourd'hui. L'ensemble complet et à jour des codes d'erreur et des charges utiles est documenté dans l'OpenAPI en ligne à /docs.
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED | L'en-tête X-Api-Key est manquant. |
| 401 | INVALID_KEY_FORMAT | La clé ne commence pas par vk_sand_ ou vk_live_, ou ne correspond à aucune clé du compte. |
| 403 | FORBIDDEN | La clé est valide, mais n'a pas accès à la session ou à la ressource demandée. |
| 404 | NOT_FOUND | Aucune session, aucun identifiant ni aucune ressource n'existe avec cet id. |
| 409 | CONFLICT | La session n'est pas dans un état qui permet l'action, par exemple l'annulation d'une session déjà VERIFIED. |
| 422 | VALIDATION_ERROR | Un champ obligatoire est manquant ou mal formé — par exemple, return_url n'est pas une URL http ou https valide. |
Webhooks
Signés, livrés, relancés.
Lorsqu'une session atteint l'état VERIFIED ou FAILED, ShieldID envoie par POST la structure documentée ci-dessus à votre webhook_url.
- Livré par POST avec un corps JSON correspondant à la structure de résultat ci-dessus.
- Signé avec HMAC-SHA256 sur le corps brut de la requête, envoyé dans un en-tête X-Bio-Signature. Vérifiez-le à l'aide de votre secret de webhook avant de faire confiance à la charge utile.
- Nouvelle tentative jusqu'à trois fois avec un délai progressif linéaire si votre point de terminaison ne répond pas avec un statut 2xx.
- Bientôt disponible : une nouvelle tentative pour les sessions FAILED qui livre un second webhook une fois la session résolue. Pour l'instant, considérez qu'il y a un seul webhook par session.
- Les noms de champs ici correspondent à cette référence. Si ce qui arrive réellement est différent, fiez-vous à la charge utile réelle plutôt qu'à cette page et signalez-le-nous : la liste des champs est tenue en phase avec l'API, et non l'inverse.
Vérifiez la signature
import crypto from "node:crypto";
function isValidShieldIdSignature(rawBody, signatureHeader, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const provided = signatureHeader || "";
const a = Buffer.from(expected, "hex");
const b = Buffer.from(provided, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// rawBody must be the exact, unparsed request body
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
const ok = isValidShieldIdSignature(req.body, req.headers["x-bio-signature"], process.env.SHIELDID_WEBHOOK_SECRET);
if (!ok) return res.status(401).send("invalid signature");
const result = JSON.parse(req.body);
// result.session_id, result.status, result.checks, …
res.status(200).send("ok");
});Idempotence et nouvelles tentatives
Concevez des gestionnaires qui peuvent s'exécuter deux fois sans risque.
Il n'existe pas encore de clé d'idempotence dédiée, ni pour la création de session ni pour la livraison des webhooks.
- Une livraison de webhook relancée peut arriver plus d'une fois pour la même session. Identifiez votre gestionnaire à partir de session_id + status et rendez l'écriture du résultat idempotente.
- Ne relancez pas POST /v1/sessions aveuglément après un délai d'attente dépassé : vérifiez d'abord si la session a été créée, sinon vous risquez d'obtenir deux sessions pour un même demandeur.
- Un en-tête Idempotency-Key dédié pour la création de session est prévu.
Bientôt disponiblePrise en charge d'Idempotency-Key pour la création de session
Rester à jour
Cette référence évolue. Consultez le journal des modifications.
Les ajouts de champs, les nouveaux codes d'erreur et les changements de points de terminaison y sont annoncés avant d'apparaître ici.
Questions
FAQ de la référence.
Suivant
Mettez cette référence en pratique.
Suivez le guide de démarrage rapide pour passer, dans l'ordre, d'une clé de bac à sable à une session vérifiée et à un webhook signé.