Dokumentation → Directors' Dealings

Dokumentation

Directors' Dealings

Insider-Transaktionen aus SEC und BaFin in einem Format. Für nachgelagerte Systeme ist /dealings/changes der richtige Einstieg, nicht ein Zeitfenster.

Wozu das gut ist, steht auf der Produktseite: Directors' Dealings

GET/dealingsGET/dealings/by/{identifier}GET/dealings/changesGET/dealings/eventsGET/dealings/item/{source_key}GET/dealings/jobs/{job_id}GET/dealings/recentPOST/dealings/rematchPOST/dealings/sync/bafinPOST/dealings/sync/bafin/allPOST/dealings/sync/bafin/recentPOST/dealings/sync/bulkPOST/dealings/sync/sec/backfillPOST/dealings/sync/sec/recentPOST/dealings/sync/sec/{identifier}

GET /dealings

Dealings List

Persistierte Directors Dealings, gefiltert und paginiert.

Name	Typ	Bedeutung
`ticker`	string, in der Abfrage optional	—
`isin`	string, in der Abfrage optional	—
`direction`	string, in der Abfrage optional	BUY \| SELL \| OTHER
`source`	string, in der Abfrage optional	sec \| bafin
`person`	string, in der Abfrage optional	Namensteil, case-insensitive
`date_from`	string, in der Abfrage optional	Transaktionsdatum >= YYYY-MM-DD
`date_to`	string, in der Abfrage optional	Transaktionsdatum <= YYYY-MM-DD
`match_status`	string, in der Abfrage optional	matched \| unmatched
`min_volume`	number, in der Abfrage optional	—
`since`	string, in der Abfrage optional	Nur Datensätze mit created_at > since (ISO-Cursor)
`updated_since`	string, in der Abfrage optional	Nur Datensätze mit updated_at > Wert
`order`	string, in der Abfrage optional	created_at \| updated_at (aufsteigend); sonst neueste Transaktion zuerst
`limit`	integer, in der Abfrage optional · Vorgabe `100`	—
`offset`	integer, in der Abfrage optional · Vorgabe `0`	—

Beispiel

curl "$API/dealings" \
  -H "X-API-Key: $KEY"

GET /dealings/by/{identifier}

Dealings By Identifier

Dealings zu Ticker/ISIN/CIK/WKN/entity_value.

Der Identifier wird zentral aufgelöst; anschließend wird über Ticker UND Aktien-ISIN gesucht (Meldungen können unter beidem gespeichert sein). Ist der Titel nicht auflösbar, greift die alte ISIN/Ticker-Heuristik.

Name	Typ	Bedeutung
`identifier`	string, im Pfad Pflicht	—
`limit`	integer, in der Abfrage optional · Vorgabe `100`	—
`offset`	integer, in der Abfrage optional · Vorgabe `0`	—

Beispiel

curl "$API/dealings/by/SAP" \
  -H "X-API-Key: $KEY"

GET /dealings/changes

Dealings Changes

Lückenloser Inkrement-Feed für Downstream-Consumer (z.B. Newsroom).

Cursor über den Ingestion-Zeitstempel created_at, aufsteigend. Zwei Wege, denselben Endpunkt zu nutzen:

A) Cursor aus eigenen Daten ableiten (zustandslos): schicke als since das

größte created_at, das du bereits importiert hast. Der Feed antwortet
inklusiv (created_at >= since); per source_key deduplizieren fängt den
einen Grenz-Datensatz ab. Einfachster Weg.

B) next_since-Token durchreichen: speichere das zurückgegebene next_since

und schicke es beim nächsten Aufruf. Exakt, kein Re-Fetch.

Beide sind lückenlos: der Cursor ist zusammengesetzt aus (created_at, source_key), sodass Datensätze mit identischem created_at an der Batch-Grenze nicht verloren gehen. created_at (nicht Transaktions-/Meldedatum) ist der richtige Schlüssel, weil Meldungen verspätet eintreffen (SEC-Nachreichungen, BaFin-Korrekturen) und nur die Ingestion-Zeit aus Consumer-Sicht monoton ist.

Name	Typ	Bedeutung
`since`	string, in der Abfrage optional	Cursor. Entweder MAX(created_at) der eigenen Daten (ISO) ODER das `next_since`-Token aus dem letzten Aufruf. Leer = von Anfang.
`updated_since`	string, in der Abfrage optional	Alternativ: nach updated_at feeden (fängt auch In-Place-Änderungen).
`source`	string, in der Abfrage optional	sec \| bafin
`limit`	integer, in der Abfrage optional · Vorgabe `500`	—

Beispiel

curl "$API/dealings/changes" \
  -H "X-API-Key: $KEY"

GET /dealings/events

Dealings Events

Aggregierte Directors-Dealings-News-Events für Downstream (Newsroom).

Bündelt die Rohzeilen (ein Dokument je Transaktion) zu einem Event je Aktie+Tag (ticker_day, Default) bzw. je Filing (filing). Jedes Event enthält Netto-Käufe/-Verkäufe, beteiligte Personen, Gesamt- und Netto- Volumen, Währung(en) und – zum Aufklappen – die source_keys.

Nutzung:

Erstbefüllung: ?date_from=2026-01-01 (optional source= und/oder

  ticker=/isin=), dann per offset durchpaginieren bis has_more=false.
- Laufend: ein Trailing-Fenster nachziehen (z.B. date_from=heute-14d)
  und auf Consumer-Seite per event_id upserten (Events sind idempotent;
  Nachmeldungen aktualisieren das jeweilige Event).

Nur gematchte Zeilen (mit Ticker) fließen in ticker_day-Events ein; unmatched Rohzeilen bleiben über GET /dealings?match_status=unmatched sichtbar.

Name	Typ	Bedeutung
`group`	string, in der Abfrage optional · Vorgabe `ticker_day`	ticker_day \| filing
`date_from`	string, in der Abfrage optional	Event-Tag >= YYYY-MM-DD (z.B. 2026-01-01 für Erstbefüllung)
`date_to`	string, in der Abfrage optional	Event-Tag <= YYYY-MM-DD
`source`	string, in der Abfrage optional	sec \| bafin (leer = alle Quellen)
`ticker`	string, in der Abfrage optional	—
`isin`	string, in der Abfrage optional	—
`include_source_keys`	boolean, in der Abfrage optional · Vorgabe `True`	Roh-source_keys je Event zum Aufklappen mitliefern
`limit`	integer, in der Abfrage optional · Vorgabe `100`	—
`offset`	integer, in der Abfrage optional · Vorgabe `0`	—

Beispiel

curl "$API/dealings/events" \
  -H "X-API-Key: $KEY"

GET /dealings/item/{source_key}

Dealings Item

Name	Typ	Bedeutung
`source_key`	string, im Pfad Pflicht	—

Beispiel

curl "$API/dealings/item/SAP" \
  -H "X-API-Key: $KEY"

GET /dealings/jobs/{job_id}

Dealings Job Status

Name	Typ	Bedeutung
`job_id`	string, im Pfad Pflicht	—

Beispiel

curl "$API/dealings/jobs/job_7f3c" \
  -H "X-API-Key: $KEY"

GET /dealings/recent

Dealings Recent

Dealings der letzten N Tage (Transaktionsdatum).

Name	Typ	Bedeutung
`days`	integer, in der Abfrage optional · Vorgabe `7`	—
`source`	string, in der Abfrage optional	—
`direction`	string, in der Abfrage optional	—
`limit`	integer, in der Abfrage optional · Vorgabe `100`	—
`offset`	integer, in der Abfrage optional · Vorgabe `0`	—

Beispiel

curl "$API/dealings/recent?days=7&limit=2" \
  -H "X-API-Key: $KEY"

{
  "count": 2,
  "items": [
    { "issuer": "SAP SE", "isin": "DE0007164600",
      "person": "Christian Klein", "type": "buy",
      "shares": 4200, "price": 231.40, "date": "2026-08-29",
      "regulator": "BaFin" }
  ]
}

POST /dealings/rematch

Dealings Rematch

Rematcht persistierte Dealings gegen das aktuelle Matching + ticker_reference.

Nach einer Verbesserung der Zuordnung einmalig laufen lassen: bereits gespeicherte Meldungen werden neu zugeordnet, ohne sie erneut zu holen. Background-Job — Fortschritt über GET /dealings/jobs/{job_id} (successful = aktualisierte Datensätze).

Name	Typ	Bedeutung
`source`	string, in der Abfrage optional	sec \| bafin (Default: beide)

Beispiel

curl -X POST "$API/dealings/rematch" \
  -H "X-API-Key: $KEY"

POST /dealings/sync/bafin

Dealings Sync Bafin

Synchronisiert Eigengeschäfte von Führungskräften aus der BaFin-Datenbank.

Ohne isin/issuer wird marktweit gesucht — dann greift scope (Default: letzter Monat, all = gesamte Datenbank).

Keine Parameter.

Anfragekörper `BafinSyncRequest`

Name	Typ	Bedeutung
`isin`	string optional	Isin
`issuer`	string optional	Issuer
`from_date`	string optional	From Date
`to_date`	string optional	To Date
`scope`	string optional	Scope

Beispiel

curl -X POST "$API/dealings/sync/bafin" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

POST /dealings/sync/bafin/all

Dealings Sync Bafin All

BaFin-Sammel-Sync über alle deutschen ISINs (Emittenten-Einzelabfragen).

Nur für gezielte Tiefe pro DE-Emittent nötig (scope=all holt das komplette aktuell verfügbare Fenster eines Titels). Für den regulären wiederkehrenden Sync stattdessen /sync/bafin/recent nutzen — vollständiger und billiger. Als Background-Job — Fortschritt über GET /dealings/jobs/{job_id}.

Name	Typ	Bedeutung
`scope`	string, in der Abfrage optional · Vorgabe `month`	week \| month \| all (Fenster pro Emittent)

Beispiel

curl -X POST "$API/dealings/sync/bafin/all" \
  -H "X-API-Key: $KEY"

POST /dealings/sync/bafin/recent

Dealings Sync Bafin Recent

Wiederkehrender BaFin-Sync: EIN marktweiter Abzug der letzten N Tage.

Bevorzugter Weg für den täglichen Sync — erfasst alle ISIN-Nationalitäten (nicht nur DE) in einem einzigen Request. ~13 % der Meldungen haben eine Nicht-DE-ISIN (v.a. GB/US), die der DE-ISIN-Ansatz von /sync/bafin/all verpassen würde. Läuft synchron (ein Abzug), gibt Zähler zurück.

Name	Typ	Bedeutung
`days`	integer, in der Abfrage optional · Vorgabe `7`	Marktweites Fenster in Tagen

Beispiel

curl -X POST "$API/dealings/sync/bafin/recent" \
  -H "X-API-Key: $KEY"

POST /dealings/sync/bulk

Dealings Sync Bulk

Background-Job: Directors Dealings für eine Liste von Identifiern.

SEC läuft je Identifier über EDGAR; für BaFin wird die ISIN direkt genutzt oder über ticker_reference aufgelöst.

Keine Parameter.

Anfragekörper `BulkSyncRequest`

Name	Typ	Bedeutung
`identifiers`	array Pflicht	Identifiers
`sources`	array optional · Vorgabe `['sec', 'bafin']`	Sources
`concurrency`	integer optional · Vorgabe `5`	Concurrency
`limit`	integer optional · Vorgabe `25`	Limit

Beispiel

curl -X POST "$API/dealings/sync/bulk" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

POST /dealings/sync/sec/backfill

Dealings Sync Sec Backfill

Marktweiter historischer Backfill über einen Datumsbereich (Daily Index).

Läuft als Background-Job Tag für Tag; kann bei großen Bereichen Stunden dauern (~2000 Form-4/Handelstag). Fortschritt über GET /dealings/jobs/{job_id} (Feld current_date, filings_ingested). Idempotent — ein erneuter Lauf fügt nur Neues hinzu.

Name	Typ	Bedeutung
`from_date`	string, in der Abfrage optional · Vorgabe `2026-01-01`	Start YYYY-MM-DD
`to_date`	string, in der Abfrage optional	Ende YYYY-MM-DD (Default: heute)

Beispiel

curl -X POST "$API/dealings/sync/sec/backfill" \
  -H "X-API-Key: $KEY"

POST /dealings/sync/sec/recent

Dealings Sync Sec Recent

Marktweiter Sync aller Form 3/4/5 eines Handelstags via EDGAR Daily Index.

Startet einen Background-Job — Fortschritt über GET /dealings/jobs/{job_id}.

Name	Typ	Bedeutung
`date`	string, in der Abfrage optional	Handelstag YYYY-MM-DD (Default: heute)

Beispiel

curl -X POST "$API/dealings/sync/sec/recent" \
  -H "X-API-Key: $KEY"

POST /dealings/sync/sec/{identifier}

Dealings Sync Sec

Synchronisiert Directors Dealings eines Emittenten von SEC EDGAR.

identifier: Ticker, CIK oder isin:/wkn:/ticker:/cik:-Präfix. history=true lädt die komplette Filing-Historie (zurück bis 1994).

Name	Typ	Bedeutung
`identifier`	string, im Pfad Pflicht	—
`limit`	integer, in der Abfrage optional · Vorgabe `25`	Max. Form-3/4/5-Filings
`history`	boolean, in der Abfrage optional · Vorgabe `False`	Volle Historie (alle Shards, ignoriert limit)

Beispiel

curl -X POST "$API/dealings/sync/sec/SAP" \
  -H "X-API-Key: $KEY"

Directors' Dealings

Dealings List

Beispiel

Dealings By Identifier

Beispiel

Dealings Changes

Beispiel

Dealings Events

Beispiel

Dealings Item

Beispiel

Dealings Job Status

Beispiel

Dealings Recent

Beispiel

Dealings Rematch

Beispiel

Dealings Sync Bafin

Anfragekörper BafinSyncRequest

Beispiel

Dealings Sync Bafin All

Beispiel

Dealings Sync Bafin Recent

Beispiel

Dealings Sync Bulk

Anfragekörper BulkSyncRequest

Beispiel

Dealings Sync Sec Backfill

Beispiel

Dealings Sync Sec Recent

Beispiel

Dealings Sync Sec

Beispiel

Anfragekörper `BafinSyncRequest`

Anfragekörper `BulkSyncRequest`