Connexion
Documentation

API Documentation

Utilisez l'API SotaID pour accéder aux clients, aux sessions vérification et bien plus encore.

Introduction

L'API SotaID est structurée autour de REST. Notre API utilise des URL prévisibles orientées ressources, accepte les corps de requêtes codés par formulaire, renvoie des réponses codées en JSON et utilise les codes de réponse, l'authentification et les verbes HTTP standard. Vous pouvez utiliser l'API SotaID en mode test, ce qui n'affecte pas vos données en temps réel. La clé API utilisée pour authentifier la requête détermine si celle-ci est en mode temps réel ou en mode test.

Ce point de terminaison vous permet de créer une session de vérification sur votre serveur et de rediriger vers son URL pour commencer la vérification.

Base URL
https://app.sotaboost.com/api

Authentication

L'API SotaID utilise des clés API pour authentifier les requêtes. Vous pouvez consulter et gérer vos clés API dans le tableau de bord SotaID.

Les clés secrètes du mode test ont le préfixe sk_test et celles du mode live, le préfixe sk_live.

Vos clés API confèrent de nombreux privilèges ; veillez donc à les conserver en lieu sûr ! Ne partagez pas vos clés API secrètes dans des espaces publics tels que GitHub, le code côté client, etc.

Toutes les requêtes API doivent être effectuées via HTTPS. Les appels effectués via HTTP échoueront. Les requêtes API sans authentification échoueront également.

Authenticated Request 
curl https://app.sotaboost.com/api/verification_sessions \
  -H "Authorization: Bearer {token}"

Errors

SotaID utilise des codes de réponse HTTP conventionnels pour indiquer la réussite ou l'échec d'une requête API. En général : les codes de la plage 2xx indiquent une réussite. Les codes de la plage 4xx indiquent une erreur ayant échoué compte tenu des informations fournies (par exemple, un paramètre obligatoire a été omis, etc.). Les codes de la plage 5xx indiquent une erreur au niveau des serveurs de SotaID (ce sont des erreurs rares).

Certaines erreurs 4xx pouvant être traitées par programmation (par exemple, une vérification echouée) incluent un code d'erreur expliquant brièvement l'erreur signalée.

HTTP Status Code Summary 
200 OK  Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized    No valid API key provided.
402 Request Failed  The parameters were valid but the request failed.
403 Forbidden   The API key doesn’t have permissions to perform the request.
404 Not Found   The requested resource doesn’t exist.
409 Conflict    The request conflicts with another request (perhaps due to using the same idempotent key).
429 Too Many Requests   Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504  Server Errors   Something went wrong on SotaID’s end. (These are rare.)

Metadata

Les objets SotaID modifiables (Account et VerificationSession) disposent d'un paramètre de metadata. Ce paramètre permet d'associer des données clé-valeur à ces objets SotaID.

Vous pouvez spécifier jusqu'à 50 clés, avec des noms de clés comportant jusqu'à 40 caractères et des valeurs jusqu'à 500 caractères. Les clés et les valeurs sont stockées sous forme de chaînes de caractère.

Vous pouvez utiliser des métadonnées pour stocker des informations structurées supplémentaires sur un objet. Par exemple, vous pouvez stocker le nom complet de votre utilisateur et l'identifiant unique correspondant de votre système dans un objet SotaID Customer.

Certains des objets listés ci-dessus prennent également en charge un paramètre de description. Vous pouvez utiliser le paramètre « description » pour annoter une vérification, par exemple une description lisible.

Ne stockez aucune information sensible (numéros de compte bancaire, informations de carte, etc.) dans les métadonnées ou le paramètre « description ».

Pagination

Toutes les ressources API de niveau supérieur prennent en charge les récupérations groupées via les méthodes API « liste ». Par exemple, vous pouvez lister les clients et les verification_sessions. Ces méthodes API partagent une structure commune et acceptent au minimum les deux paramètres suivants : limit et cursor.

Les méthodes API de SotaID utilisent une pagination par curseur via le paramètre cursor. Le curseur est une chaîne codée contenant l'emplacement et la direction de la prochaine requête paginée.

Parameters

limitoptional, default is 10

Limite du nombre d'objets à renvoyer. Cette limite peut varier de 1 à 100, la valeur par défaut étant 10.

cursoroptional

Un curseur à utiliser pour la pagination contenant l'emplacement et la direction de la prochaine requête paginée. Si le paramètre n'est fourni, la première page de résultats sera renvoyée.

Response
{
  "data": [
    {
      "id": "01jpnp4x6z1ystaxsgk26t7wbw",
      "name": "John Doe",
      "email": "johndoe@example.com",
      "phone": null,
      "description": null,
      "metadata": {},
      "created_at": "2025-03-19T08:28:31.000000Z",
      "updated_at": "2025-03-21T00:16:41.000000Z"
    }
  ],
  "path": "https://app.sotaboost.com/api/customers",
  "per_page": 1,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMy0xOCAxNTowNDozOCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "next_page_url": "https://app.sotaboost.com/api/customers?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0wMy0xOCAxNTowNDozOCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "prev_cursor": null,
  "prev_page_url": null
}

Webhooks

Dans ce guide, nous verrons comment enregistrer et utiliser des webhooks pour intégrer votre application à SotaID. Grâce aux webhooks, votre application peut être informée des événements survenant dans SotaID, comme la fin d'une vérification ou l'ajout d'un customer.

Enregistrement des webhooks

Pour enregistrer un nouveau webhook, votre application doit contenir une URL que SotaID peut appeler. Vous pouvez configurer un nouveau webhook depuis le tableau de bord SotaID, dans les paramètres Développeurs. Donnez un nom à votre webhook, sélectionnez les événements à écouter et ajoutez votre URL.

Désormais, dès qu'un événement intéressant se produit dans votre application, SotaID déclenche un webhook. Dans la section suivante, nous verrons comment utiliser les webhooks.

Consommer des webhooks

Lorsque votre application reçoit une requête webhook de Protocol, vérifiez l'attribut type pour identifier l'événement qui l'a provoquée. La première partie du type d'événement indique le type de payload (customer, verification_session, etc.).

Dans l’exemple ci-dessous, un client a été mise à jour (updated) et le type de payload est un customer.

Types d'événements

Voici la liste de tous les types d'événements que nous envoyons actuellement. Nous sommes susceptibles d'en ajouter d'autres à tout moment. Par conséquent, lors du développement et de la maintenance de votre code, ne partez pas du principe que seuls ces types existent.

Vous remarquerez que ces événements suivent un modèle resource.event. Notre objectif est de concevoir un système cohérent qui facilite l'anticipation et la programmation.

Types d'événements

verification_session.created

Se produit chaque fois qu'une VerificationSession est créée

verification_session.verified

Se produit chaque fois qu'une VerificationSession passe à vérifiée

verification_session.failed

Se produit chaque fois qu'une VerificationSession passe à échouée

customer.created

Se produit chaque fois qu'un nouveau client est créé.

customer.updated

Se produit chaque fois qu'une propriété d'un client change.

customer.deleted

Se produit chaque fois qu'un client est supprimé.

Response
{
  "type": "customer.updated",
  "data": {
    "id": "01jpnp4x6z1ystaxsgk26t7wbw",
    "name": "John Doe",
    "email": "johndoe@example.com",
    "phone": null,
    "description": null,
    "metadata": {},
    "created_at": "2025-03-19T08:28:31.000000Z",
    "updated_at": "2025-03-21T00:16:41.000000Z"
  }
}

Verification Session

Une VerificationSession représente la session de vérification d'identités de votre utilisateur. Elle contient des informations sur la pièce d'identité. Créez une seule session de vérification pour chaque vérification effectuée dans votre système.

Une VerificationSession passe par plusieurs états tout au long de son cycle de vie, au fur et à mesure de sa progression dans le processus de vérification. Elle contient les données vérifiées de l'utilisateur une fois les contrôles de vérification terminés.

Vous pouvez créer une session de vérification sur votre serveur et rediriger vers son URL pour commencer la vérification.

POST/verification_sessions

Create a VerificationSession

Ce point de terminaison vous permet de créer une session de vérification sur votre serveur et de rediriger vers son URL pour commencer la vérification.

Parameters

client_reference_idstring

Une chaîne de caractères pour référencer cet utilisateur. Il peut s'agir d'un identifiant client, d'un identifiant de session ou d'un identifiant similaire, et peut être utilisée pour rapprocher cette vérification avec vos systèmes internes.

return_urlstring

L'URL vers laquelle l'utilisateur sera redirigé une fois le flux de vérification terminé.

customer_idstring

ID d'un client existant.

metadatastring

Ensemble de paires clé-valeur que vous pouvez associer à un objet. Cela peut être utile pour stocker des informations supplémentaires sur l'objet dans un format structuré. Il est possible de désactiver des clés individuelles en leur attribuant une valeur vide. L'annulation de toutes les clés s'effectue en attribuant une valeur vide aux métadonnées.

Response
{
  "id": "01jppr9etsyrxyvff4j17aatnd",
  "document_type": null,
  "document_country": null,
  "status": "requires_document",
  "verified_at": null,
  "created_at": "2025-03-19T08:28:31.000000Z",
  "updated_at": "2025-03-21T00:16:41.000000Z",
  "app_id": "01jpgh0xygvb28n40c0fv3rqws",
  "customer_id": null,
  "client_reference_id": null,
  "mode": null,
  "options": {},
  "verified_outputs": {},
  "metadata": {},
  "last_error": [],
  "return_url": null,
  "url": "https://sotaid.sotaboost.com/verify/01jppr9etsyrxyvff4j17aatnd",
  "document": {
    "name": null,
    "country": null
  }
}

GET/verification_sessions/:id

Retrieve a VerificationSession

Récupère les détails d'une VerificationSession qui a été précédemment créée.

Parameters

No parameters.
Response
{
  "id": "01jppr9etsyrxyvff4j17aatnd",
  "document_type": "id_card",
  "document_country": "BJ",
  "status": "verified",
  "verified_at": "2025-03-21T00:16:41.000000Z",
  "created_at": "2025-03-19T08:28:31.000000Z",
  "updated_at": "2025-03-21T00:16:41.000000Z",
  "app_id": "01jpgh0xygvb28n40c0fv3rqws",
  "customer_id": null,
  "client_reference_id": null,
  "mode": null,
  "options": {},
  "verified_outputs": {
    "name": "M. John Doe"
  },
  "metadata": {},
  "last_error": [],
  "return_url": null,
  "url": "https://sotaid.sotaboost.com/verify/01jppr9etsyrxyvff4j17aatnd",
  "document": {
    "name": "Carte nationale d'identité",
    "country": "Bénin"
  }
}

GET/verification_sessions

List all VerificationSession

Renvoie une liste de VerificationSessions

Parameters

client_reference_idstring

Une chaîne de caractères pour référencer cet utilisateur. Il peut s'agir d'un identifiant client, d'un identifiant de session ou d'un identifiant similaire, et peut être utilisée pour rapprocher cette vérification avec vos systèmes internes.

limitinteger

Limite du nombre d'objets à renvoyer. Cette limite peut varier de 1 à 100, la valeur par défaut étant 10.

Response
{
  "data": [
    {
      "id": "01jppr9etsyrxyvff4j17aatnd",
      "document_type": "id_card",
      "document_country": "BJ",
      "status": "verified",
      "verified_at": "2025-03-21T00:16:41.000000Z",
      "created_at": "2025-03-19T08:28:31.000000Z",
      "updated_at": "2025-03-21T00:16:41.000000Z",
      "app_id": "01jpgh0xygvb28n40c0fv3rqws",
      "customer_id": null,
      "client_reference_id": null,
      "mode": null,
      "options": {},
      "verified_outputs": {
        "name": "M. John Doe"
      },
      "metadata": {},
      "last_error": [],
      "return_url": null,
      "url": "https://sotaid.sotaboost.com/verify/01jppr9etsyrxyvff4j17aatnd",
      "document": {
        "name": "Carte nationale d'identité",
        "country": "Bénin"
      }
    }
  ],
  "path": "https://app.sotaboost.com/api/verification_sessions",
  "per_page": 1,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMy0xOCAxNTowNDozOCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "next_page_url": "https://app.sotaboost.com/api/verification_sessions?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0wMy0xOCAxNTowNDozOCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "prev_cursor": null,
  "prev_page_url": null
}

Customers

Cet objet représente un client de votre entreprise. Utilisez-le pour créer une VerificationSession, et suivre les VerificationSessions appartenant à ce même client.

POST/customers

Create a customer

Ce point de terminaison vous permet de créer client sur votre serveur.

Parameters

namestringRequired

Le nom complet ou le nom commercial du client.

emailstring

Adresse e-mail du client. Elle s'affiche à côté du client dans votre tableau de bord et peut être utile pour la recherche et le suivi.

phonestring

Le numéro de téléphone du client.

descriptionstring

Une chaîne arbitraire que vous pouvez associer à un objet client. Elle s'affiche à côté du client dans le tableau de bord.

metadatastring

Ensemble de paires clé-valeur que vous pouvez associer à un objet. Cela peut être utile pour stocker des informations supplémentaires sur l'objet dans un format structuré. Il est possible de désactiver des clés individuelles en leur attribuant une valeur vide. L'annulation de toutes les clés s'effectue en attribuant une valeur vide aux métadonnées.

Response
{
  "id": "01jpnp4x6z1ystaxsgk26t7wbw",
  "name": "John Doe",
  "email": "johndoe@example.com",
  "phone": null,
  "description": null,
  "metadata": {},
  "created_at": "2025-03-19T08:28:31.000000Z",
  "updated_at": "2025-03-21T00:16:41.000000Z"
}

PUT/customers/:id

Update a customer

Met à jour le client spécifié en définissant les valeurs des paramètres transmis. Les paramètres non fournis restent inchangés.

Cette requête accepte généralement les mêmes arguments que l'appel de création de client.

Parameters

namestringRequired

Le nom complet ou le nom commercial du client.

emailstring

Adresse e-mail du client. Elle s'affiche à côté du client dans votre tableau de bord et peut être utile pour la recherche et le suivi.

phonestring

Le numéro de téléphone du client.

descriptionstring

Une chaîne arbitraire que vous pouvez associer à un objet client. Elle s'affiche à côté du client dans le tableau de bord.

metadatastring

Ensemble de paires clé-valeur que vous pouvez associer à un objet. Cela peut être utile pour stocker des informations supplémentaires sur l'objet dans un format structuré. Il est possible de désactiver des clés individuelles en leur attribuant une valeur vide. L'annulation de toutes les clés s'effectue en attribuant une valeur vide aux métadonnées.

Response
{
  "id": "01jpnp4x6z1ystaxsgk26t7wbw",
  "name": "John Doe",
  "email": "johndoe@example.com",
  "phone": null,
  "description": null,
  "metadata": {},
  "created_at": "2025-03-19T08:28:31.000000Z",
  "updated_at": "2025-03-21T00:16:41.000000Z"
}

GET/customers/:id

Retrieve a customer

Récupère un objet Client.

Response
{
  "id": "01jpnp4x6z1ystaxsgk26t7wbw",
  "name": "John Doe",
  "email": "johndoe@example.com",
  "phone": null,
  "description": null,
  "metadata": {},
  "created_at": "2025-03-19T08:28:31.000000Z",
  "updated_at": "2025-03-21T00:16:41.000000Z"
}

GET/customers

List all customers

Renvoie la liste de vos clients. Les clients sont triés par date de création, les plus récents apparaissant en premier.

Parameters

emailstring

Filtre sensible à la casse sur la liste, basé sur l'adresse e-mail du client. La valeur doit être une chaîne.

limitinteger

Limite du nombre d'objets à renvoyer. Cette limite peut varier de 1 à 100, la valeur par défaut étant 10.

Response
{
  "data": [
    {
      "id": "01jpnp4x6z1ystaxsgk26t7wbw",
      "name": "John Doe",
      "email": "johndoe@example.com",
      "phone": null,
      "description": null,
      "metadata": {},
      "created_at": "2025-03-19T08:28:31.000000Z",
      "updated_at": "2025-03-21T00:16:41.000000Z"
    }
  ],
  "path": "https://app.sotaboost.com/api/customers",
  "per_page": 1,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMy0xOCAxNTowNDozOCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "next_page_url": "https://app.sotaboost.com/api/customers?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0wMy0xOCAxNTowNDozOCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "prev_cursor": null,
  "prev_page_url": null
}

DELETE/customers/:id

Delete a customer

Supprime définitivement un client. Cette opération est irréversible.

← Documentation