Créer un processusPOST

Démarrez un processus et obtenez le Human Token et l'intelligence de la personne.

Markdown

POST /v1/processes

Démarre un processus avec l'un des flux et répond avec id, state et le résultat dans data : le Human Token et l'intelligence de la personne, data.ndocs.

Avant d'appeler

• Human Plugin est en cours d'exécution et GET /health/ready répond 200.
• Votre clé d'accès est activée pour le flux que vous utilisez.
• Si vous envoyez un document, son type figure dans le catalogue d'attributs.

Flux

Le champ flow choisit ce que fait le processus. Human Plugin exécute ces flux, selon deux modèles d'intégration :

• API Only : votre back-end envoie le selfie dans imageBase64, et la création répond avec le résultat.
• Human Token Journey : la personne prend le selfie dans le parcours de capture et revient vers votre callbackUri. La création répond avec un token et un link, et vous lisez le résultat avec Obtenir un processus.

Flow	Description	Possible result	Integration components required	Example
api+humantoken	Reçoit un selfie via votre back-end et génère le Human Token, un identifiant facial unique. La réponse est définitive : pas de capture, pas de second appel.	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	Capture un selfie dans le parcours de capture, avec une vérification de détection de vie, et génère le Human Token. La création renvoie le `token` et le `link` ; lisez le résultat à la fin de la capture.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
humantoken+revalidation	Capture un selfie et compare le visage avec le Human Token attendu. Indique s'il s'agit de la même personne ou non, par exemple avant une action sensible.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

clientId, correlationId et credential sont identiques dans tous les flux.

Requête

{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}

Champs communs

Champ	Obligatoire	Limite (octets)	Remarques
flow	Oui	64	L'un des flux
clientId	Oui	128	Votre identifiant du client. L'intelligence compte les valeurs distinctes
correlationId	Oui	128	Votre référence pour ce processus. Unique : une valeur déjà utilisée par un autre processus, quel que soit son état, est refusée avec 409
credential	Oui, mais peut être vide		La clé doit être présente. Voir ci-dessous
credential.type	Avec un document		Un code du catalogue d'attributs, exact et sensible à la casse
credential.value	Avec un document	64	Le numéro du document

flow, clientId et correlationId doivent être des chaînes, sans caractères de contrôle et sans espaces au début ni à la fin. Les valeurs invalides sont rejetées, jamais réécrites.

Le champ credential

• Avec un document : un objet contenant exactement type et value, deux chaînes, envoyées ensemble.
• Sans document : null ou {}. Le processus compte quand même comme une transaction et comme un client dans l'intelligence.
• Omis, ou objet avec des chaînes vides : rejeté avec 400 MISSING_CREDENTIAL_TYPE. Cela permet de détecter une clé mal orthographiée avant tout traitement.
• Toute autre clé dans credential est rejetée.

Champs des flux

Ce que chaque flux ajoute aux champs communs :

Champ	Flux	Obligatoire	Valeur
imageBase64	api+humantoken	Oui	Le selfie en base64. PNG, JPEG ou WebP, jusqu'à 800 Ko
callbackUri	humantoken, humantoken+revalidation	Oui	L'endroit où la personne revient à la fin de la capture : une de vos pages, ou le schéma d'URL de votre application
references	humantoken+revalidation	Oui	Un élément avec le Human Token attendu, comme dans l'exemple ci-dessus

Human Plugin ne stocke pas ces champs, et un champ facultatif mal orthographié peut être ignoré sans erreur.

Avec api+humantoken, utilisez un selfie de face, bien éclairé, montrant un seul visage. Une valeur qui n'est pas une image est refusée, et le processus est enregistré comme échoué : voir Refus des flux.

Avec humantoken+revalidation, le résultat contient humanTokenMatch au lieu de humanToken :

• "true" : il s'agit de la même personne. Le processus compte pour cette personne, et ndocs la décrit.
• Toute autre valeur, ou une capture non vivante : ce n'est pas confirmé. Le processus ne compte pour personne, et il n'y a pas de ndocs.

PROCESS_STATE_FINISHED est renvoyé dans les deux cas : lisez humanTokenMatch. Voir Obtenir un processus.

Quelques noms sont réservés par Human Plugin et refusés avec 400 INVALID_REQUEST, comme clientReference. Il en va de même pour une autre orthographe des champs propres à Human Plugin, comme client_id, correlation_id ou Flow : seuls flow, clientId, correlationId et credential sont lus, avec exactement cette orthographe.

Règles du corps

• Un seul objet JSON, de 2 MiB au maximum (à peu près suffisant pour un selfie en base64). Un corps plus volumineux est refusé avec 400 REQUEST_TOO_LARGE.
• Rien ne doit suivre l'objet JSON.

Réponse

201 Created, avec Location: /v1/processes/<id>.

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

• id est l'UUID de Human Plugin. Chaque requête acceptée en crée un nouveau.
• state est le statut local. Voir cycle de vie.
• humantoken et humantoken+revalidation répondent PROCESS_STATE_CREATED avec un token et un link. Ils sont renvoyés une seule fois et ne sont jamais stockés : conservez-les. Voir Human Token Journey et le guide de capture de votre plateforme.
• data.ndocs est l'intelligence de la personne. Il peut être absent : voir Intelligence.

Le résultat dans data

Un processus terminé a ces champs dans data. Les flux Journey les renvoient lorsque vous lisez le processus après la capture.

Champ	Quand	Valeur
humanToken	api+humantoken, humantoken	Qui est la personne : value est le Human Token, et status vaut validated lorsqu'il a été généré
humanTokenMatch	humantoken+revalidation	"true" lorsqu'il s'agit de la même personne que le Human Token de references
liveness	Flux qui vérifient la détection de vie, comme les flux Journey	value vaut live lorsque la capture provient d'une personne vivante, ou not_live dans le cas contraire ; status vaut validated lorsque la vérification a été effectuée
ndocs	Lorsqu'il existe de l'intelligence pour la personne	L'intelligence de la personne

Un résultat Journey ressemble à ceci :

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}

Vérifiez liveness avant de faire confiance au résultat : avec not_live, considérez la capture comme échouée et demandez à la personne de réessayer. Un processus avec not_live ne compte pour l'intelligence de personne.

Erreurs

Statut	message	Signification
400	INVALID_REQUEST, REQUEST_TOO_LARGE	Pas un seul objet JSON, un champ réservé, un type incorrect, ou un corps supérieur à 2 MiB
400	MISSING_<FIELD>, INVALID_<FIELD>	Un champ obligatoire est absent ou mal formé, comme MISSING_CLIENT_ID
401	Vide ("")	Unico a refusé votre clé d'accès : elle est absente, incorrecte ou n'est plus valide. Le processus est enregistré comme échoué. Vérifiez HUMAN_API_ACCESS_KEY
409	CORRELATION_ID_ALREADY_USED	Un autre processus a déjà ce correlationId. Rien n'est stocké ni envoyé
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	credential.type ne figure pas dans le catalogue. Rien n'est stocké ni envoyé
4xx	Le message du flux	Le flux a refusé la requête, par exemple à cause d'une image invalide. Voir Refus des flux
502	UPSTREAM_UNAVAILABLE	Le processus n'a pas pu être confirmé à temps
503	DATABASE_UNAVAILABLE	La base de données a échoué. Rien n'a été traité
500	INTERNAL	Erreur inattendue

Refus des flux

Lorsqu'un flux refuse la requête, la création répond 4xx avec la raison dans message, dans l'enveloppe habituelle. Les plus courants :

message	Cause
invalid flow	flow n'est pas un flux activé pour votre compte
INVALID_IMAGE (400)	api+humantoken sans imageBase64
INVALID_REQUEST (400)	imageBase64 n'est pas une image en base64
IMAGE_TOO_LARGE	L'image dépasse 800 Ko
UNSUPPORTED_IMAGE_FORMAT	L'image n'est pas au format PNG, JPEG ou WebP
PERMISSION_DENIED (403)	Votre clé d'accès n'est pas activée pour ce flux

Un processus refusé est enregistré comme échoué. Corrigez la requête et créez un nouveau processus avec un nouveau correlationId.

Lisez Erreurs et nouvelles tentatives avant d'ajouter une logique de nouvelle tentative : une nouvelle tentative nécessite un nouveau correlationId.

Suite

Obtenir un processus