Datenlöschungs-API

Die Datenlöschungs-API ist der Self-Service-Weg, um die persönlichen Daten eines Betreffs aus Pushwoosh zu löschen (DSGVO-Recht auf Löschung). Die Löschung ist unumkehrbar: Verwenden Sie sie, um die Seite Datenanfragen im Control Panel und die Aktion Persönliche Daten löschen auf der Karte eines Abonnenten von Ihren eigenen Systemen aus zu spiegeln.

Basis-URL

https://rpc-api.svc-nue.pushwoosh.com

Alle Endpunkte werden über HTTPS bereitgestellt. Anfragen und Antworten verwenden application/json, mit Ausnahme von Upload, das multipart/form-data verwendet.

Authentifizierung

Jede Anfrage muss einen Authorization-Header mit Ihrem Server-API-Token enthalten:

Authorization: Api IHR_API_TOKEN

Das Token muss über Änderungsrechte für jede in application_codes genannte Anwendung verfügen. Das ist dasselbe Recht, das ein Token benötigt, um Gerätedaten für diese Anwendungen zu schreiben.

Konventionen

• Feldnamen: Anfragekörper akzeptieren lowerCamelCase (zum Beispiel applicationCodes, identifierType). Antworten werden mit den Proto-Feldnamen in snake_case marshalled (task_id, identifier_hash usw.). Die Beispiele und Objektreferenzen unten verwenden diese Schreibweise.
• Kennungen: Ein Betreff wird über identifier_type (SUBJECT_IDENTIFIER_USER_ID, SUBJECT_IDENTIFIER_HWID oder SUBJECT_IDENTIFIER_EMAIL) plus eine Liste von identifiers dieses einen Typs adressiert. Eine E-Mail-Kennung wird nicht case-sensitiv abgeglichen.
• Erst ein Dry-Run, dann referenzieren: Create mit dry_run: true zählt nur, was gelöscht würde, und schreibt nichts. Das Referenzieren der task_id dieses Dry-Runs als confirmation_dry_run_task_id beim eigentlichen Aufruf ist optional, aber wenn Sie eine angeben, muss sie exakt zu den Anwendungen und Kennungen dieses Dry-Runs passen und innerhalb von 15 Minuten nach dessen Abschluss aufgerufen werden. Andernfalls wird der Aufruf abgelehnt.
• Berichte enthalten die Kennung nie im Klartext. Sowohl GetTaskReport als auch GetJournalReport melden jede Kennung als ihren sha256-Hash (identifier_hash), und der Berichtsinhalt ist als CSV base64-kodiert in der JSON-Antwort enthalten.

Fehlerantworten

HTTP-Status	Bedeutung
400 Bad Request	Ungültiges Argument, z. B. ein leeres identifier_type, identifiers oder application_codes, mehr als 10.000 Kennungen, mehr als 50 Anwendungen, Kennungen × Anwendungen über 50.000, eine leere Kennungszeichenfolge oder (nur bei Upload) eine fehlende/unlesbare CSV-Datei. Wird auch (als FailedPrecondition auf der Leitung) zurückgegeben, wenn eine angegebene confirmation_dry_run_task_id nicht zu dem von ihr benannten abgeschlossenen Dry-Run passt, zu alt ist (über 15 Minuten) oder überhaupt kein abgeschlossener Dry-Run ist.
401 Unauthorized	Fehlender oder ungültiger Authorization-Header.
403 Forbidden	Das Token hat kein Änderungs-/Gerätedatenrecht für eine der angeforderten Anwendungen, oder der Aufrufer darf die angeforderte Aufgabe/den angeforderten Bericht nicht lesen.
404 Not Found	Die Aufgabe wurde nicht gefunden oder gehört nicht zum Konto des Aufrufers.
413 Payload Too Large	(Nur bei Upload) die hochgeladene Datei ist größer als 5 MB.
429 Too Many Requests	Das Konto hat in den letzten 24 Stunden bereits 20 Datenlöschungsaufgaben gestartet (Dry-Runs eingeschlossen).

Endpunkte

Methode	Pfad	Beschreibung
POST	/api/data_erasure/tasks	Eine Löschungs- (oder Dry-Run-)Aufgabe erstellen
POST	/api/data_erasure/upload	Eine Löschungsaufgabe aus einer hochgeladenen CSV mit Kennungen erstellen
GET	/api/data_erasure/tasks	Die Löschungsaufgaben des Kontos auflisten
GET	/api/data_erasure/tasks/{task_id}	Eine einzelne Löschungsaufgabe abrufen
GET	/api/data_erasure/tasks/{task_id}/rows	Die Ergebnisse einer Aufgabe pro Kennung auflisten
GET	/api/data_erasure/tasks/{task_id}/report	Den Bericht einer Aufgabe als CSV herunterladen
GET	/api/data_erasure/report	Alle Aufgaben eines Zeitraums als eine CSV herunterladen

Create

Beginnt mit dem Löschen der persönlichen Daten der aufgelisteten Betreffe in den aufgelisteten Anwendungen. Mit dry_run: true zählt die Aufgabe nur, was gelöscht würde.

POST /api/data_erasure/tasks

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
identifierType	string	Ja	SUBJECT_IDENTIFIER_USER_ID, SUBJECT_IDENTIFIER_HWID oder SUBJECT_IDENTIFIER_EMAIL.
identifiers	Array von Strings	Ja	Kennungen des Betreffs dieses einen Typs, bis zu 10.000 pro Aufgabe, keine leeren Werte.
applicationCodes	Array von Strings	Ja	Anwendungscodes, aus denen gelöscht werden soll, bis zu 50. Es gibt keine Möglichkeit, in einem Aufruf aus jeder Anwendung des Kontos zu löschen, daher müssen Sie jede einzeln benennen. identifiers.length × applicationCodes.length darf 50.000 nicht überschreiten, da der Bericht eine Zeile pro Kennung und Anwendung enthält.
dryRun	boolean	Nein	Zählt, was gelöscht würde, und schreibt nichts. Standardmäßig false.
confirmationDryRunTaskId	integer	Nein	task_id eines abgeschlossenen Dry-Runs, der genau diese Löschung gemessen hat. Siehe Konventionen.

Anfragebeispiel

{
  "identifierType": "SUBJECT_IDENTIFIER_EMAIL",
  "identifiers": ["subject@example.com"],
  "applicationCodes": ["XXXXX-XXXXX"],
  "dryRun": true
}

Antwort

Feld	Typ	Beschreibung
task_id	integer	ID der erstellten Aufgabe. Verwenden Sie sie bei jedem anderen Endpunkt auf dieser Seite.

Gefahr

Die Löschung kann nicht rückgängig gemacht werden. Das Löschen eines Betreffs entfernt dessen Daten in jeder genannten Anwendung, storniert jedoch nicht bereits geplante oder in der Warteschlange befindliche Nachrichten für diesen Betreff, zum Beispiel einen verzögerten Versand oder den nächsten Schritt einer laufenden Journey.

Upload

Erstellt die gleiche Art von Aufgabe wie Create, aber die Kennungen stammen aus einer hochgeladenen CSV anstelle eines JSON-Arrays. Verwenden Sie dies für eine umfangreiche Betreffliste.

POST /api/data_erasure/upload

Anfrage (multipart/form-data)

Feld	Erforderlich	Beschreibung
file	Ja	CSV-Datei, bis zu 5 MB, eine Kennung pro Zeile, in der einzigen Spalte. Die erste Zeile kann statt einer Kennung den Spaltennamen enthalten (user_id, userid, user id, hwid, email, identifier oder subject, nicht case-sensitiv). Diese Zeile wird dann als Kopfzeile übersprungen und nicht mitgezählt. Leere Zeilen werden übersprungen und separat gezählt. Doppelte Kennungen (bei E-Mail nicht case-sensitiv) werden zu einer zusammengefasst und separat gezählt.
identifier_type	Ja	user_id, hwid oder email, kleingeschrieben, eine andere Schreibweise als die JSON-identifierType-Enum-Werte, die an anderer Stelle auf dieser Seite verwendet werden. Ein Typ gilt für die gesamte Datei.
application_codes	Ja	Durch Komma getrennte Anwendungscodes.
dry_run	Nein	true/false.
confirmation_dry_run_task_id	Nein	Wie bei Create.

Antwort

{
  "task_id": 123,
  "identifier_count": 480,
  "duplicate_count": 3,
  "skipped_rows": 1
}

ListTasks

Listet die Löschungen des Kontos auf, neueste zuerst: das Prüfprotokoll, wer was wann gelöscht hat. Dry-Runs werden ausgelassen, sofern nicht includeDryRuns gesetzt ist.

GET /api/data_erasure/tasks

Abfrageparameter

Parameter	Typ	Beschreibung
limit / offset	integer	Paginierung.
includeDryRuns	boolean	Dry-Run-Aufgaben (nur Messung) einschließen.
from / to	string (RFC 3339)	Behält Aufgaben, die im Zeitraum [from, to) gestartet wurden.
applicationCode	string	Behält Aufgaben, die diese Anwendung abdecken.
initiatorUserId	integer	Behält Aufgaben, die von diesem Control-Panel-Benutzer gestartet wurden. 0 (Standard) behält jeden Initiator.
initiatorTokenId	integer	Behält Aufgaben, die von diesem API-Token gestartet wurden. 0 (Standard) behält jeden Initiator.
initiatorEmail	string	Behält Aufgaben, die von diesem Control-Panel-Benutzer gestartet wurden, abgeglichen per E-Mail, nicht case-sensitiv.

Antwort

Feld	Typ	Beschreibung
tasks	Array von Löschaufgaben-Objekten	Übereinstimmende Aufgaben.

GetTask

Gibt eine einzelne Löschaufgabe mit ihrem Status und ihren Zählern zurück. Verwenden Sie sie, um eine mit Create oder Upload gestartete Aufgabe zu verfolgen.

GET /api/data_erasure/tasks/{task_id}

Antwort

Feld	Typ	Beschreibung
task	Löschaufgaben-Objekt	Die angeforderte Aufgabe.

ListTaskRows

Gibt das Ergebnis einer Aufgabe pro Kennung zurück: was gelöscht, nicht gefunden, übersprungen oder fehlgeschlagen wurde. Kennungen werden als ihr sha256-Hash gemeldet.

GET /api/data_erasure/tasks/{task_id}/rows

Abfrageparameter

Parameter	Typ	Beschreibung
limit / offset	integer	Paginierung.

Antwort

Feld	Typ	Beschreibung
rows	Array von Löschaufgabenzeilen-Objekten	Diese Ergebnisseite.

GetTaskReport

Gibt den vollständigen Bericht einer Aufgabe als CSV-Datei zurück: eine Zeile pro Kennung und Anwendung, mit ihrem Ergebnis. ListTaskRows zeigt stattdessen dieselben Zeilen seitenweise an.

GET /api/data_erasure/tasks/{task_id}/report

Antwort

Feld	Typ	Beschreibung
filename	string	Vorgeschlagener Dateiname, zum Beispiel data-erasure-task-42.csv.
content_type	string	text/csv.
content	string (base64)	Die CSV-Datei. Spalten: task_id, created, identifier_type, identifier_hash, application_code, result, detail.

GetJournalReport

Gibt jede Löschung eines Zeitraums als eine CSV-Datei zurück: eine Zeile pro Kennung und Anwendung, mit der Aufgabe und ihrem Initiator auf jeder Zeile. Das ist es, was ein Konto einem Prüfer aushändigt.

GET /api/data_erasure/report

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
from	string (RFC 3339)	Ja	Beginn des Zeitraums.
to	string (RFC 3339)	Nein	Ende des Zeitraums. Standardmäßig jetzt.
includeDryRuns	boolean	Nein	Dry-Run-Aufgaben einschließen.

Vorsicht

Ein Zeitraum mit mehr als 2.000 Löschaufgaben wird abgelehnt, anstatt gekürzt zu werden. Grenzen Sie den Zeitraum ein und rufen Sie erneut auf.

Antwort

Feld	Typ	Beschreibung
filename	string	Vorgeschlagener Dateiname, zum Beispiel data-erasure-2026-01-01-2026-04-01.csv.
content_type	string	text/csv.
content	string (base64)	Die CSV-Datei. Spalten: task_id, task_created, initiator_user_id, initiator_email, initiator_token_id, dry_run, identifier_type, identifier_hash, application_code, result, detail, row_created.

Löschaufgaben-Objekt

Feld	Typ	Beschreibung
task_id	integer	Aufgaben-ID.
identifier_type	string	SUBJECT_IDENTIFIER_USER_ID, SUBJECT_IDENTIFIER_HWID oder SUBJECT_IDENTIFIER_EMAIL.
application_codes	Array von Strings	Anwendungen, die die Aufgabe abdeckt.
dry_run	boolean	Ob diese Aufgabe nur ein Volumen gemessen hat.
status	string	ERASURE_TASK_STATUS_PENDING, _IN_PROGRESS, _DONE oder _FAILED.
total_count	integer	Kennungen × Anwendungen, die diese Aufgabe abdeckt.
deleted_count	integer	Wie viele gelöscht wurden (oder bei einem Dry-Run würden).
not_found_count	integer	Wie viele auf nichts zutrafen.
failed_count	integer	Wie viele fehlgeschlagen sind. Den Grund finden Sie in ListTaskRows oder im Bericht.
fail_reason	string	Gesetzt, wenn status gleich ERASURE_TASK_STATUS_FAILED ist.
initiator_user_id	integer	Control-Panel-Benutzer, der die Aufgabe gestartet hat. 0, wenn ein API-Token es getan hat.
initiator_token_id	integer	API-Token, das die Aufgabe gestartet hat. 0, wenn ein Control-Panel-Benutzer es getan hat.
initiator_email	string	Adresse des Control-Panel-Benutzers, der die Aufgabe gestartet hat. Leer bei einem API-Token.
created	string (RFC 3339)	Wann die Aufgabe erstellt wurde.
started_at	string (RFC 3339)	Wann die Löscharbeit begann.
finished_at	string (RFC 3339)	Wann die Aufgabe einen endgültigen Status erreichte.

Löschaufgabenzeilen-Objekt

Feld	Typ	Beschreibung
identifier_hash	string	sha256 der Kennung. Der Bericht speichert oder gibt niemals die Kennung selbst zurück.
application_code	string	Anwendung, für die das Ergebnis dieser Zeile gilt.
result	string	ERASURE_ROW_RESULT_DELETED, _NOT_FOUND, _SKIPPED oder _FAILED.
detail	string	Technisches Detail, hauptsächlich bei einem Fehlschlag gesetzt.
created	string (RFC 3339)	Wann diese Zeile geschrieben wurde.

Verwandte Themen

Datenanfragen (Produktanleitung)

Persönliche Daten aus dem User Explorer löschen