API REST Segments utilisateurs

Créez des segments basés sur des listes mis à jour manuellement et remplacez, ajoutez ou supprimez des membres par ID de segment.

Généralités

• Les requêtes et réponses utilisent du JSON encodé en UTF-8.
• L’URL complète du point de terminaison est la Base URL du centre de données plus le chemin API. Consultez la Présentation de l’API REST pour obtenir la Base URL et l’API Key / l’API Secret.
• Utilisez l’authentification HTTP Basic : Authorization: Basic ${base64(api_key:api_secret)}. La source de données API liée à l’API Key détermine le projet ; les appelants ne transmettent pas d’ID de projet dans le corps de la requête.
• Les réponses réussies partagent une structure commune : code 0 signifie succès, message décrit le résultat et data contient la charge utile. Le traitement par lots des écritures de membres dépend de l’opération : OVERRIDE s’exécute uniquement après réception de tous les lots ; chaque lot APPEND et REMOVE est appliqué indépendamment. data.status et data.complete dans la réponse indiquent l’état de traitement.

Créer un segment basé sur une liste

Crée un segment en mode de mise à jour manuelle avec le téléversement de liste comme méthode de création. Le segment n’a aucun membre après création ; utilisez Mettre à jour les membres du segment pour téléverser la liste.

Point de terminaison

POST /v1/segments

Exemple de requête

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "High-value users",
    "description": "High-value user list synced from the order system"
  }'

            

Paramètres de la requête

Exemple de réponse

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "segmentId": 123456789,
    "name": "High-value users",
    "generation": "generation-1"
  }
}

            

Mettre à jour les membres du segment

Un seul point de terminaison remplace, ajoute ou supprime des membres de liste. Seuls les segments du projet actuel créés par téléversement de liste, en mise à jour manuelle et actifs sont acceptés. Les identifiants utilisateur doivent correspondre à des utilisateurs actifs existants dans le projet ; l’API ne crée pas d’actifs utilisateur. Lorsque le segment ne remplit pas les conditions, les erreurs 55210–55214 sont renvoyées (voir Réponses d’erreur).

Point de terminaison

POST /v1/segments/{segmentId}/members

Exemple de requête

L’exemple suivant divise une opération OVERRIDE en deux lots. Chaque batchId représente une opération de liste ; tous les lots doivent utiliser le même batchId, operation et batchCount. OVERRIDE applique le changement de liste uniquement après réception de tous les lots. APPEND et REMOVE prennent effet dès que la requête de lot correspondante réussit.

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments/123456789/members' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "batchIndex": 0,
    "batchCount": 2,
    "members": [
      {"euid": "100001"},
      {"identityName": "user_id", "identityValue": "user-002"}
    ]
  }'

            

Lors de la réception du premier lot OVERRIDE, status dans la réponse est RECEIVING et complete est false. Soumettez le lot restant avec le même batchId et définissez batchIndex sur 1.

Paramètres de la requête

Les éléments members prennent en charge les deux formats suivants ; euid ne peut pas être envoyé avec identityName / identityValue :

Opérations sur la liste

Les nouvelles tentatives avec le même batchId doivent utiliser la même opération, batchCount et contenu de lot ; le même batchId et batchIndex ne peuvent pas porter un contenu différent. Les résultats idempotents sont conservés 24 heures.

Les lots OVERRIDE sont retenus jusqu’à réception complète, puis appliqués ; les données retenues expirent après un TTL de 24 heures, et la liste n’est pas modifiée si les lots sont incomplets avant expiration. Chaque lot APPEND et REMOVE s’applique indépendamment ; batchCount et batchIndex identifient toujours les lots, prennent en charge l’idempotence et suivent la progression sans bloquer le lot actuel.

Chaque changement de liste réussi est enregistré dans l’historique de mise à jour du segment avec la source REST API. OVERRIDE est journalisé par lot terminé ; APPEND et REMOVE par lot réussi. Les enregistrements d’audit n’incluent pas d’échantillons d’identifiants non correspondants ou invalides.

Exemples de réponse

Lot pas encore terminé :

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "RECEIVING",
    "complete": false,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 2,
    "unmatchedCount": 0,
    "unmatchedSamples": [],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 0,
    "exitCount": 0
  }
}

            

Lot OVERRIDE terminé :

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 2,
    "inputCount": 3,
    "matchedCount": 2,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 1,
    "invalidSamples": [
      {"identityName": "not_configured", "identityValue": "example"}
    ],
    "invalidSamplesTruncated": false,
    "enterCount": 2,
    "exitCount": 1
  }
}

            

Lorsqu’un lot APPEND ou REMOVE réussit, le lot actuel s’applique immédiatement et renvoie complete: true même si batchCount est supérieur au nombre de lots reçus jusqu’à présent. Par exemple, avec batchCount 2 et seulement le premier lot reçu, receivedBatchCount est 1 et status est COMPLETED.

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-append",
    "operation": "APPEND",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 1,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 1,
    "exitCount": 0
  }
}

            

Les échantillons suivent la structure d’objet d’identifiant de membre de la requête et peuvent inclure le identityValue soumis. Le serveur ne stocke les échantillons que dans le cache d’idempotence de 24 heures, pas dans les enregistrements d’audit ; traitez les réponses et les journaux conformément à vos exigences de conformité des données.

Si la réponse est PROCESSING, réessayez avec le même batchId, batchIndex et le contenu de lot d’origine pour un résultat idempotent. Il n’existe pas d’API distincte pour interroger la progression des lots.

Réponses d’erreur

Les erreurs utilisent code et message ; consultez les Codes de statut HTTP pour les codes de statut HTTP et les codes de retour généraux.

Lors de la création d’un segment, les codes d’erreur métier et message de Metadata sont transmis à l’appelant, p. ex. nom en double 40026, limite 40032. Sur le chemin de téléversement de liste, « segment inexistant » renvoie 55201 au lieu de 40027.

Les identifiants de membres non correspondants ou invalides ne font pas échouer l’ensemble de l’opération de liste (sauf OVERRIDE lorsqu’aucun utilisateur ne correspond ; voir 55214). La réponse renvoie des comptages et jusqu’à 100 échantillons d’identifiants. Les échantillons peuvent inclure identityValue ; protégez les données de réponse en conséquence.