API serveur des persons

Une person est un utilisateur de ton application, identifié par son identifiant dans ton système, l’externalId. Le SDK la crée au premier identify() ; l’API serveur permet à ton backend de la créer à l’avance et de poser ses propriétés (nom, email, offre…), affichées sur sa fiche dans le dashboard.

L’API serveur s’appelle depuis ton backend uniquement, sur https://api.belvdr.com/v1, avec une clé secrète du projet :

curl -X POST https://api.belvdr.com/v1/persons \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "user_42", "properties": {"email": "ada@example.com", "plan": "pro"}}'

Routes

Route	Effet
POST /v1/persons	Crée la person, ou met à jour ses propriétés si elle existe
GET /v1/persons	Liste les persons, les plus récentes d’abord
GET /v1/persons/:externalId	Détail d’une person
PATCH /v1/persons/:externalId	Met à jour les propriétés d’une person existante
DELETE /v1/persons/:externalId	Suppression RGPD (page dédiée)

L’externalId dans le chemin est encodé comme tout segment d’URL (encodeURIComponent).

Une person est renvoyée sous la forme :

{
  "person": {
    "externalId": "user_42",
    "properties": { "email": "ada@example.com", "plan": "pro" },
    "createdAt": "2026-10-15T09:12:03.000Z",
    "updatedAt": "2026-10-15T09:12:03.000Z"
  }
}

Créer ou mettre à jour : POST /v1/persons

Corps : { "externalId": "…", "properties": { … } }, properties facultatif.

• 201 si la person a été créée, 200 si elle existait : ses propriétés sont alors fusionnées.
• externalId : 1 à 200 caractères, pris tel quel, unique dans le projet. C’est le userId passé à identify() par le SDK.

Mettre à jour les propriétés : PATCH /v1/persons/:externalId

curl -X PATCH https://api.belvdr.com/v1/persons/user_42 \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"plan": "entreprise", "essai": null}}'

Corps : { "properties": { … } }. 404 person_not_found si la person n’existe pas.

Propriétés

Les propriétés sont un objet JSON, dont les clés font 1 à 200 caractères. À chaque mise à jour (POST ou PATCH) :

• chaque clé envoyée remplace la précédente ;
• une clé à null est retirée ;
• les clés non envoyées sont conservées.

La recherche du dashboard (et de GET /v1/persons) porte sur l’externalId et sur les propriétés name et email.

Lister : GET /v1/persons

curl "https://api.belvdr.com/v1/persons?search=ada&limit=20" \
  -H "Authorization: Bearer sk_…"

Réponse : { "persons": [ … ], "nextCursor": "…" }, les plus récentes d’abord.

Paramètre	Effet
limit	Nombre de persons par page : 50 par défaut, 100 au plus
cursor	Le nextCursor de la page précédente (null sur la dernière page)
search	Texte contenu dans l’externalId, le nom ou l’email, sans tenir compte de la casse

Erreurs

Réponse	Cause
400 invalid_request	Corps ou paramètres invalides
401, 403	Clé absente, inconnue, révoquée ou publique (Clés secrètes)
404 person_not_found	Aucune person avec cet externalId dans le projet
409 person_being_deleted	Une suppression de cette person est en cours