Benutzersegmente REST-API

Erstellen Sie manuell aktualisierte listenbasierte Segmente und überschreiben, erweitern oder entfernen Sie Mitglieder anhand der Segment-ID.

Allgemeines

• Anfragen und Antworten verwenden JSON in UTF-8-Kodierung.
• Die vollständige Endpunkt-URL setzt sich aus der Base URL des Rechenzentrums und dem API-Pfad zusammen. Informationen zum Abrufen der Base URL sowie von API Key / API Secret finden Sie in der RestAPI-Übersicht.
• Verwenden Sie HTTP Basic Authentication: Authorization: Basic ${base64(api_key:api_secret)}. Die an den API Key gebundene API-Datenquelle bestimmt das Projekt; Aufrufer übergeben keine Projekt-ID im Anfragebody.
• Erfolgreiche Antworten folgen einer gemeinsamen Struktur: code 0 bedeutet Erfolg, message beschreibt das Ergebnis und data enthält die Nutzdaten. Die Stapelverarbeitung für Mitglieder-Schreibvorgänge hängt von der Operation ab: OVERRIDE wird erst ausgeführt, nachdem alle Stapel empfangen wurden; jeder Stapel von APPEND und REMOVE wird unabhängig angewendet. data.status und data.complete in der Antwort zeigen den Verarbeitungsstatus an.

Listenbasiertes Segment erstellen

Erstellt ein Segment mit manuellem Aktualisierungsmodus und Listen-Upload als Erstellungsmethode. Das Segment hat nach der Erstellung keine Mitglieder; verwenden Sie Segmentmitglieder aktualisieren, um die Liste hochzuladen.

Endpunkt

POST /v1/segments

Anfragebeispiel

              
              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"
  }'

            

Anfrageparameter

Antwortbeispiel

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

            

Segmentmitglieder aktualisieren

Ein einzelner Endpunkt überschreibt, erweitert oder entfernt Listenmitglieder. Es werden nur Segmente im aktuellen Projekt akzeptiert, die per Listen-Upload erstellt wurden, manuell aktualisiert werden und aktiv sind. Benutzerkennungen müssen bestehenden aktiven Benutzern im Projekt entsprechen; die API erstellt keine Benutzer-Assets. Wenn das Segment nicht qualifiziert ist, werden die Fehler 55210–55214 zurückgegeben (siehe Fehlerantworten).

Endpunkt

POST /v1/segments/{segmentId}/members

Anfragebeispiel

Das folgende Beispiel teilt eine OVERRIDE-Operation in zwei Stapel auf. Jede batchId steht für eine Listenoperation; alle Stapel müssen dieselbe batchId, operation und batchCount verwenden. OVERRIDE wendet die Listenänderung erst an, nachdem alle Stapel empfangen wurden. APPEND und REMOVE treten in Kraft, sobald die jeweilige Stapelanfrage erfolgreich ist.

              
              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"}
    ]
  }'

            

Wenn der erste OVERRIDE-Stapel empfangen wird, ist status in der Antwort RECEIVING und complete ist false. Senden Sie den verbleibenden Stapel mit derselben batchId und setzen Sie batchIndex auf 1.

Anfrageparameter

members-Elemente unterstützen die folgenden zwei Formate; euid darf nicht zusammen mit identityName / identityValue gesendet werden:

Listenoperationen

Wiederholungen mit derselben batchId müssen dieselbe Operation, batchCount und Stapelinhalt verwenden; dieselbe batchId und batchIndex dürfen unterschiedliche Inhalte nicht tragen. Idempotente Ergebnisse werden 24 Stunden aufbewahrt.

OVERRIDE-Stapel werden gehalten, bis alle empfangen wurden, und dann angewendet; gehaltene Daten verfallen nach einer 24-Stunden-TTL, und die Liste wird nicht geändert, wenn Stapel vor Ablauf unvollständig sind. Jeder APPEND- und REMOVE-Stapel wird unabhängig angewendet; batchCount und batchIndex identifizieren weiterhin Stapel, unterstützen Idempotenz und verfolgen den Fortschritt, ohne den aktuellen Stapel zu blockieren.

Jede erfolgreiche Listenänderung wird in der Segment-Aktualisierungshistorie mit der Quelle REST API protokolliert. OVERRIDE wird pro abgeschlossenem Stapel protokolliert; APPEND und REMOVE pro erfolgreichem Stapel. Auditdatensätze enthalten keine Beispiele nicht abgeglichener oder ungültiger Kennungen.

Antwortbeispiele

Stapel noch nicht vollständig:

              
              {
  "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
  }
}

            

OVERRIDE-Stapel abgeschlossen:

              
              {
  "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
  }
}

            

Wenn ein APPEND- oder REMOVE-Stapel erfolgreich ist, wird der aktuelle Stapel sofort angewendet und gibt complete: true zurück, auch wenn batchCount größer ist als die bisher empfangene Stapelanzahl. Beispiel: Bei batchCount 2 und nur dem ersten empfangenen Stapel ist receivedBatchCount 1 und status ist 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
  }
}

            

Beispiele folgen der Mitgliedskennungs-Objektstruktur aus der Anfrage und können den übermittelten identityValue enthalten. Der Server speichert Beispiele nur im 24-Stunden-Idempotenz-Cache, nicht in Auditdatensätzen; behandeln Sie Antworten und Protokolle gemäß Ihren Datenschutzanforderungen.

Wenn die Antwort PROCESSING ist, wiederholen Sie mit derselben batchId, batchIndex und dem ursprünglichen Stapelinhalt für ein idempotentes Ergebnis. Es gibt keine separate API zur Abfrage des Stapel-Fortschritts.

Fehlerantworten

Fehler verwenden code und message; siehe HTTP-Statuscodes für HTTP-Statuscodes und allgemeine Rückgabecodes.

Beim Erstellen eines Segments werden Geschäftsfehlercodes und message aus Metadata an den Aufrufer durchgereicht, z. B. doppelter Name 40026, Limit 40032. Auf dem Listen-Upload-Pfad liefert „Segment existiert nicht“ 55201 statt 40027.

Nicht abgeglichene oder ungültige Mitgliedskennungen führen nicht zum Fehlschlagen der gesamten Listenoperation (außer OVERRIDE, wenn keine Benutzer abgeglichen werden; siehe 55214). Die Antwort liefert Zählungen und bis zu 100 Kennungsbeispiele. Beispiele können identityValue enthalten; schützen Sie Antwortdaten entsprechend.