Client (KYC)

Créez une nouvelle vérification en envoyant les documents et les données du client final.

Créer une vérification

POST /v1/verifications (multipart/form-data)

• Auth requise: Authorization: Bearer <API_KEY>
• Idempotence: Idempotency-Key: <UUID> (recommandé)

Champs (multipart):

• applicant (JSON) — informations personnelles
• documents[] (fichiers) — images/PDF des documents
• documents_meta (JSON) — description des fichiers (type, side)
• Optionnel: webhook_url pour surcharger la config du compte
• Optionnel: consent (boolean), metadata (JSON)

Exemple cURL (carte d’identité 2 faces + selfie):

curl -X POST https://api.sankara.africa/v1/verifications \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'applicant={"first_name":"Awa","last_name":"Traoré","dob":"1992-07-15","nationality":"ML","phone":"+22370000000","email":"awa@example.com"};type=application/json' \
  -F 'documents_meta={"items":[{"name":"ci_front.jpg","type":"national_id","side":"front"},{"name":"ci_back.jpg","type":"national_id","side":"back"},{"name":"selfie.jpg","type":"selfie"}]};type=application/json' \
  -F 'documents[]=@/path/ci_front.jpg;type=image/jpeg' \
  -F 'documents[]=@/path/ci_back.jpg;type=image/jpeg' \
  -F 'documents[]=@/path/selfie.jpg;type=image/jpeg'

Réponse (201):

{
  "id": "ver_01HXX...",
  "status": "pending",
  "created_at": "2025-08-09T10:21:00Z",
  "applicant": {"first_name": "Awa", "last_name": "Traoré"},
  "expected_documents": [
    {"type": "national_id", "sides": ["front", "back"]},
    {"type": "selfie"}
  ],
  "links": {"self": "/v1/verifications/ver_01HXX..."}
}

Récupérer une vérification

GET /v1/verifications/{verification_id}

Réponse (ex.):

{
  "id": "ver_01HXX...",
  "status": "processing",
  "ocr": {
    "national_id": {"first_name": "AWA", "last_name": "TRAORE", "id_number": "AB12345"}
  },
  "face_match": {"score": 0.93, "passed": true},
  "checks": {"watchlists": {"passed": true}},
  "errors": [],
  "created_at": "2025-08-09T10:21:00Z",
  "updated_at": "2025-08-09T10:22:30Z"
}

Lister les vérifications

GET /v1/verifications?status=processing&limit=20&starting_after=...

Pagination: curseurs limit, starting_after, ending_before.

Statuts et délais ⏱️

• pending → processing en quelques secondes
• processing → completed/failed selon les résultats
• needs_review si une action manuelle est requise (qualité, incohérences)

Conseils qualité d’image 📸

• Bonne luminosité, pas de reflet, visage dégagé
• Document complet visible, non rogné, net
• Taille ≤ 15 MB; résolution ≥ 600x600; pas de filigrane

Champs et types (POST /v1/verifications)

• Principe: très peu de champs obligatoires; fournissez un maximum d’informations pour de meilleurs résultats.

Champs multipart principaux:

Champ	Type	Obligatoire	Description
applicant	JSON	optionnel	Données personnelles de l’applicant
documents[]	fichier	obligatoire (≥1)	Images/PDF à analyser. JPEG/PNG/PDF (1 page), ≤ 15 MB
documents_meta	JSON	recommandé	Métadonnées décrivant chaque fichier (type, face)
webhook_url	string(url)	optionnel	URL de webhook pour cette vérif (écrase la config compte)
consent	boolean	optionnel	Consentement explicite de l’utilisateur final
metadata	JSON	optionnel	Données métier libres (clé/valeur)

Objet applicant (JSON):

Champ	Type	Obligatoire	Description
first_name	string	optionnel	Prénom
last_name	string	optionnel	Nom
dob	string(YYYY-MM-DD)	optionnel	Date de naissance
nationality	string(ISO2)	optionnel	Nationalité
email	string(email)	optionnel	Email
phone	string	optionnel	Téléphone au format international
address.line1	string	optionnel	Adresse ligne 1
address.line2	string	optionnel	Adresse ligne 2
address.city	string	optionnel	Ville
address.state	string	optionnel	État/Région
address.postal_code	string	optionnel	Code postal
address.country	string(ISO2)	optionnel	Pays

Objet documents_meta (JSON):

Champ	Type	Obligatoire	Description
items	array[DocItem]	recommandé	Liste synchronisée avec documents[] (même ordre)

Type DocItem:

Champ	Type	Obligatoire	Description
name	string	recommandé	Nom de fichier
type	enum	obligatoire	national_id
side	enum	optionnel	front