{"openapi":"3.1.0","info":{"title":"AdressMonster Reseller-API","version":"1.0.0","description":"REST-Schnittstelle fuer Reseller-Vertraege: Trefferzahlen, Preise und die Auslieferung deutscher Firmenadressen.\n\n**Zugang nur mit Reseller-Lizenzvertrag.** Die Standardlizenz des Shops gestattet ausschliesslich die eigene Nutzung.\n\n### Wasserzeichen\n\nJede ueber diese API ausgelieferte Datensatz-ID traegt ein Suffix von exakt 13 Zeichen: die Kennung `99999` und eine auf 8 Stellen nullgefuellte Liefernummer.\n\n```\nAM8733  →  AM87339999900004387\n```\n\nDie Basis-ID ist immer `id.slice(0, -13)` und steht zusaetzlich als `baseId` in jeder Zeile. **Der Lizenzvertrag verpflichtet dazu, die Basis-ID mitzufuehren und das Wasserzeichen weder zu entfernen noch zu veraendern** — nur ueber die Basis-ID lassen sich gesperrte Datensaetze aus `/v1/suppressions` wiederfinden.\n\n### Fehler\n\nJede Fehlerantwort hat die Form `{ \"error\": { \"code\", \"message\", \"requestId\" } }`. Der `code` ist stabil und Teil dieses Vertrags; werte ihn aus, nicht die `message`. Die `requestId` steht auch im Header `X-Request-Id` und gehoert in jede Supportanfrage.","contact":{"name":"AdressMonster Support","email":"support@adressmonster.de"}},"servers":[{"url":"https://api.adressmonster.de/v1","description":"Produktion"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Referenz","description":"Unentgeltliche Stammdaten."},{"name":"Suche","description":"Trefferzahl und Preis."},{"name":"Auslieferung","description":"Kostenpflichtiger Datenabruf."},{"name":"Pflichten","description":"DSGVO-Loeschkanal."}],"paths":{"/me":{"get":{"tags":["Referenz"],"operationId":"getMe","summary":"Vertrag, Limits und Kriterienpolitik","description":"Grundlage fuer die eigene Oberflaeche: welche Kriterien der Endkunde waehlen darf, welche erzwungen sind, was sie kosten und welche Grenzen gelten.\n\nBleibt auch bei Zahlungsverzug erreichbar.","security":[{"bearerAuth":["usage:read"]}],"responses":{"200":{"description":"Vertragsdaten.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"`missing_authorization` — Authorization-Header fehlt. Erwartet: 'Authorization: Bearer am_live_...'\n\n`malformed_key` — Das Format des API-Keys ist ungueltig.\n\n`invalid_key` — API-Key unbekannt oder falsch.\n\n`key_expired` — Der API-Key ist abgelaufen.\n\n`key_revoked` — Der API-Key wurde widerrufen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`ip_not_allowed` — Aufruf von dieser IP-Adresse ist fuer diesen Key nicht freigegeben.\n\n`insufficient_scope` — Der Key besitzt den fuer diesen Endpunkt noetigen Scope nicht.\n\n`reseller_suspended` — Das Reseller-Konto ist gesperrt.\n\n`contract_inactive` — Der Vertrag ist nicht (mehr) aktiv.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — Zu viele Anfragen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal_error` — Interner Fehler.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable` — Dienst voruebergehend nicht verfuegbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/branchen":{"get":{"tags":["Referenz"],"operationId":"getBranchen","summary":"Branchen und Kategorien","description":"Liefert bewusst **keine Firmenzahlen**: Eine globale Zahl je Branche beschreibt nicht die Menge unter den eigenen Filtern und der eigenen Kriterienpolitik. Dafuer gibt es `/count`.","security":[{"bearerAuth":["count:read"]}],"responses":{"200":{"description":"Referenzdaten.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"`missing_authorization` — Authorization-Header fehlt. Erwartet: 'Authorization: Bearer am_live_...'\n\n`malformed_key` — Das Format des API-Keys ist ungueltig.\n\n`invalid_key` — API-Key unbekannt oder falsch.\n\n`key_expired` — Der API-Key ist abgelaufen.\n\n`key_revoked` — Der API-Key wurde widerrufen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`ip_not_allowed` — Aufruf von dieser IP-Adresse ist fuer diesen Key nicht freigegeben.\n\n`insufficient_scope` — Der Key besitzt den fuer diesen Endpunkt noetigen Scope nicht.\n\n`reseller_suspended` — Das Reseller-Konto ist gesperrt.\n\n`contract_inactive` — Der Vertrag ist nicht (mehr) aktiv.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — Zu viele Anfragen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal_error` — Interner Fehler.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable` — Dienst voruebergehend nicht verfuegbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/regions":{"get":{"tags":["Referenz"],"operationId":"getRegions","summary":"Bundeslaender und Sucharten","security":[{"bearerAuth":["count:read"]}],"responses":{"200":{"description":"Referenzdaten.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"`missing_authorization` — Authorization-Header fehlt. Erwartet: 'Authorization: Bearer am_live_...'\n\n`malformed_key` — Das Format des API-Keys ist ungueltig.\n\n`invalid_key` — API-Key unbekannt oder falsch.\n\n`key_expired` — Der API-Key ist abgelaufen.\n\n`key_revoked` — Der API-Key wurde widerrufen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`ip_not_allowed` — Aufruf von dieser IP-Adresse ist fuer diesen Key nicht freigegeben.\n\n`insufficient_scope` — Der Key besitzt den fuer diesen Endpunkt noetigen Scope nicht.\n\n`reseller_suspended` — Das Reseller-Konto ist gesperrt.\n\n`contract_inactive` — Der Vertrag ist nicht (mehr) aktiv.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — Zu viele Anfragen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal_error` — Interner Fehler.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable` — Dienst voruebergehend nicht verfuegbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/count":{"get":{"tags":["Suche"],"operationId":"getCount","summary":"Trefferzahl, Feldabdeckung und indikativer Preis","description":"Unentgeltlich und fuer den hohen Takt einer Suchmaske ausgelegt. Ergebnisse werden zwischengespeichert; `cached` und `computedAt` sagen, wie frisch die Zahl ist.\n\nDer `queryHash` beschreibt die Filtermenge und ist bei `/records` identisch — damit laesst sich belegen, dass Zaehlung und Lieferung dieselbe Menge betreffen.\n\n**Zu breite Auswahl** wird mit `selection_too_broad` abgewiesen, bevor die teure Abfrage startet. Die Grenze steht als `maxEstimatedRowsPerCount` in `/me`.","security":[{"bearerAuth":["count:read"]}],"parameters":[{"name":"suchart","in":"query","required":true,"description":"Art der geografischen Eingrenzung.\n\n`gesamt` — Bundesweit, ohne geografische Einschraenkung.\n\n`bundesland` — Ein oder mehrere Bundeslaender, kommagetrennt.\n\n`umkreis` — Radius um eine Postleitzahl, 1 bis 500 Kilometer.\n\n`plzBereich` — Postleitzahlbereiche als VON-BIS-Paare ('76000-76999'), maximal 25 Bereiche. Praefixe wie '76' sind eine Bequemlichkeit der Shop-Oberflaeche und werden hier nicht aufgeloest.","schema":{"type":"string","enum":["gesamt","bundesland","umkreis","plzBereich"]}},{"name":"branchenIds","in":"query","required":true,"description":"Kommagetrennte Branchen-IDs aus `GET /v1/branchen`.\n\n**Pflicht.** Ohne Branchenauswahl laesst sich die Treffermenge nicht vorab abschaetzen; eine solche Abfrage wird nicht ausgefuehrt, sondern mit `invalid_parameter` abgewiesen. Der Kanal fuer sehr breite Auswertungen ist der Bulk-Export. Maximal 1000 IDs.","schema":{"type":"string","example":"92,145"}},{"name":"land","in":"query","required":false,"description":"Laenderkennung. Muss in den fuer den Vertrag freigegebenen Laendern liegen (siehe `GET /v1/me`, Feld `countries`). Ohne Angabe gilt der erste freigegebene Wert.","schema":{"type":"string","example":"DE"}},{"name":"bundeslaender","in":"query","required":false,"description":"Nur bei `suchart=bundesland`. Kommagetrennte Namen, z. B. `Bayern,Hessen`.","schema":{"type":"string"}},{"name":"plz","in":"query","required":false,"description":"Nur bei `suchart=umkreis`. Mittelpunkt des Radius, 4 oder 5 Ziffern.","schema":{"type":"string","pattern":"^\\d{4,5}$","example":"76646"}},{"name":"umkreis","in":"query","required":false,"description":"Nur bei `suchart=umkreis`. Radius in Kilometern.","schema":{"type":"integer","minimum":1,"maximum":500,"example":25}},{"name":"plzRanges","in":"query","required":false,"description":"Nur bei `suchart=plzBereich`. Kommagetrennte VON-BIS-Paare, jeweils fuenfstellig, maximal 25 Bereiche.","schema":{"type":"string","example":"76000-76999,18000-18999"}},{"name":"felder","in":"query","required":false,"description":"Kommagetrennte Kriterien, deren Spalten geliefert werden sollen — ohne zu filtern.\n\nErlaubt: `basis`, `strasse`, `telefon`, `email`, `homepage`, `ansprechpartner`, `groesse`. Welche davon der Vertrag freigibt, steht in `GET /v1/me`; ein gesperrtes Kriterium fuehrt zu `criterion_not_permitted` und wird nicht stillschweigend verworfen.\n\n**Erzwungene Kriterien (`mode: forced`) sind immer aktiv**, auch wenn sie hier fehlen.","schema":{"type":"string","example":"telefon,email"}},{"name":"hatStrasse","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"hatTelefon","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"hatEmail","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"hatHomepage","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"hatAnsprechpartner","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"unternehmensgroesse","in":"query","required":false,"description":"Kommagetrennte Groessenklassen. **Setzt das Kriterium `groesse` voraus** — ist es im Vertrag gesperrt, wird die Abfrage abgewiesen. Ein Filter ist auch ein Auslesekanal.","schema":{"type":"string","example":"1,2"}},{"name":"keineDuplikateTelefon","in":"query","required":false,"description":"`true` laesst jeden Wert hoechstens einmal im Ergebnis vorkommen. Setzt das zugehoerige Kriterium voraus und verkleinert die Treffermenge.","schema":{"type":"boolean"}},{"name":"keineDuplikateEmail","in":"query","required":false,"description":"`true` laesst jeden Wert hoechstens einmal im Ergebnis vorkommen. Setzt das zugehoerige Kriterium voraus und verkleinert die Treffermenge.","schema":{"type":"boolean"}},{"name":"keineDuplikateHomepage","in":"query","required":false,"description":"`true` laesst jeden Wert hoechstens einmal im Ergebnis vorkommen. Setzt das zugehoerige Kriterium voraus und verkleinert die Treffermenge.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Trefferzahl und Preis.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountResponse"}}}},"400":{"description":"`invalid_parameter` — Ein Parameter fehlt oder ist ungueltig.\n\n`criterion_not_permitted` — Ein angefragtes Kriterium ist fuer diesen Vertrag nicht verfuegbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_authorization` — Authorization-Header fehlt. Erwartet: 'Authorization: Bearer am_live_...'\n\n`malformed_key` — Das Format des API-Keys ist ungueltig.\n\n`invalid_key` — API-Key unbekannt oder falsch.\n\n`key_expired` — Der API-Key ist abgelaufen.\n\n`key_revoked` — Der API-Key wurde widerrufen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`ip_not_allowed` — Aufruf von dieser IP-Adresse ist fuer diesen Key nicht freigegeben.\n\n`insufficient_scope` — Der Key besitzt den fuer diesen Endpunkt noetigen Scope nicht.\n\n`reseller_suspended` — Das Reseller-Konto ist gesperrt.\n\n`contract_inactive` — Der Vertrag ist nicht (mehr) aktiv.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`selection_too_broad` — Die Auswahl ist zu breit. Bitte weiter eingrenzen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — Zu viele Anfragen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal_error` — Interner Fehler.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable` — Dienst voruebergehend nicht verfuegbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/records":{"get":{"tags":["Auslieferung"],"operationId":"getRecords","summary":"Datensaetze abrufen","description":"**Kostenpflichtig.** Jeder Abruf wird abgerechnet, auch der wiederholte.\n\n### Blaettern\n\nDer erste Aufruf friert die Treffermenge ein und liefert `pagination.nextCursor`. Solange dieser Cursor benutzt wird, bleibt die Menge stabil — auch wenn zwischenzeitlich importiert wird. Der Snapshot laeuft nach der in `snapshotExpiresAt` genannten Zeit ab; danach muss ohne `cursor` neu begonnen werden.\n\nEine Seite kann **kuerzer** als `limit` sein: wenn das Ergebnis endet, wenn das Tageskontingent nur noch einen Rest hergibt, oder wenn ein Datensatz seit dem Einfrieren gesperrt wurde. Abgerechnet wird immer nur, was geliefert wurde.\n\n### Wiederholung nach Abbruch\n\nBei Verbindungsabbruch dieselbe Anfrage mit demselben `Idempotency-Key` wiederholen: Sie liefert die identische Antwort samt Liefernummer, ohne ein zweites Mal abzurechnen. Derselbe Schluessel mit anderen Parametern wird mit `idempotency_key_reuse` abgewiesen.\n\n### Grenzen\n\nUeber `maxRecordsPerSyncQuery` Treffer antwortet der Endpunkt mit `result_too_large`; solche Mengen gehoeren in einen Bulk-Export.","security":[{"bearerAuth":["records:read"]}],"parameters":[{"name":"suchart","in":"query","required":true,"description":"Art der geografischen Eingrenzung.\n\n`gesamt` — Bundesweit, ohne geografische Einschraenkung.\n\n`bundesland` — Ein oder mehrere Bundeslaender, kommagetrennt.\n\n`umkreis` — Radius um eine Postleitzahl, 1 bis 500 Kilometer.\n\n`plzBereich` — Postleitzahlbereiche als VON-BIS-Paare ('76000-76999'), maximal 25 Bereiche. Praefixe wie '76' sind eine Bequemlichkeit der Shop-Oberflaeche und werden hier nicht aufgeloest.","schema":{"type":"string","enum":["gesamt","bundesland","umkreis","plzBereich"]}},{"name":"branchenIds","in":"query","required":true,"description":"Kommagetrennte Branchen-IDs aus `GET /v1/branchen`.\n\n**Pflicht.** Ohne Branchenauswahl laesst sich die Treffermenge nicht vorab abschaetzen; eine solche Abfrage wird nicht ausgefuehrt, sondern mit `invalid_parameter` abgewiesen. Der Kanal fuer sehr breite Auswertungen ist der Bulk-Export. Maximal 1000 IDs.","schema":{"type":"string","example":"92,145"}},{"name":"land","in":"query","required":false,"description":"Laenderkennung. Muss in den fuer den Vertrag freigegebenen Laendern liegen (siehe `GET /v1/me`, Feld `countries`). Ohne Angabe gilt der erste freigegebene Wert.","schema":{"type":"string","example":"DE"}},{"name":"bundeslaender","in":"query","required":false,"description":"Nur bei `suchart=bundesland`. Kommagetrennte Namen, z. B. `Bayern,Hessen`.","schema":{"type":"string"}},{"name":"plz","in":"query","required":false,"description":"Nur bei `suchart=umkreis`. Mittelpunkt des Radius, 4 oder 5 Ziffern.","schema":{"type":"string","pattern":"^\\d{4,5}$","example":"76646"}},{"name":"umkreis","in":"query","required":false,"description":"Nur bei `suchart=umkreis`. Radius in Kilometern.","schema":{"type":"integer","minimum":1,"maximum":500,"example":25}},{"name":"plzRanges","in":"query","required":false,"description":"Nur bei `suchart=plzBereich`. Kommagetrennte VON-BIS-Paare, jeweils fuenfstellig, maximal 25 Bereiche.","schema":{"type":"string","example":"76000-76999,18000-18999"}},{"name":"felder","in":"query","required":false,"description":"Kommagetrennte Kriterien, deren Spalten geliefert werden sollen — ohne zu filtern.\n\nErlaubt: `basis`, `strasse`, `telefon`, `email`, `homepage`, `ansprechpartner`, `groesse`. Welche davon der Vertrag freigibt, steht in `GET /v1/me`; ein gesperrtes Kriterium fuehrt zu `criterion_not_permitted` und wird nicht stillschweigend verworfen.\n\n**Erzwungene Kriterien (`mode: forced`) sind immer aktiv**, auch wenn sie hier fehlen.","schema":{"type":"string","example":"telefon,email"}},{"name":"hatStrasse","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"hatTelefon","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"hatEmail","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"hatHomepage","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"hatAnsprechpartner","in":"query","required":false,"description":"`true` liefert nur Datensaetze, bei denen das Feld gefuellt ist, und waehlt das Kriterium damit zugleich aus (Pflicht statt optional). Das verkleinert die Treffermenge und veraendert den Preis.","schema":{"type":"boolean"}},{"name":"unternehmensgroesse","in":"query","required":false,"description":"Kommagetrennte Groessenklassen. **Setzt das Kriterium `groesse` voraus** — ist es im Vertrag gesperrt, wird die Abfrage abgewiesen. Ein Filter ist auch ein Auslesekanal.","schema":{"type":"string","example":"1,2"}},{"name":"keineDuplikateTelefon","in":"query","required":false,"description":"`true` laesst jeden Wert hoechstens einmal im Ergebnis vorkommen. Setzt das zugehoerige Kriterium voraus und verkleinert die Treffermenge.","schema":{"type":"boolean"}},{"name":"keineDuplikateEmail","in":"query","required":false,"description":"`true` laesst jeden Wert hoechstens einmal im Ergebnis vorkommen. Setzt das zugehoerige Kriterium voraus und verkleinert die Treffermenge.","schema":{"type":"boolean"}},{"name":"keineDuplikateHomepage","in":"query","required":false,"description":"`true` laesst jeden Wert hoechstens einmal im Ergebnis vorkommen. Setzt das zugehoerige Kriterium voraus und verkleinert die Treffermenge.","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Datensaetze je Seite. Ueber `maxRecordsPerRequest` (siehe `/me`) ist es ein Fehler und keine stille Kuerzung.","schema":{"type":"integer","minimum":1,"example":1000}},{"name":"cursor","in":"query","required":false,"description":"`pagination.nextCursor` der vorigen Seite. Fehlt er, beginnt die Auslieferung von vorn.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Frei waehlbar, hoechstens 64 Zeichen, 24 Stunden gueltig.","schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"Datensaetze. Der Header `Idempotent-Replay: true` zeigt an, dass es sich um die Wiederholung einer frueheren Antwort handelt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsResponse"}}}},"400":{"description":"`invalid_parameter` — Ein Parameter fehlt oder ist ungueltig.\n\n`criterion_not_permitted` — Ein angefragtes Kriterium ist fuer diesen Vertrag nicht verfuegbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_authorization` — Authorization-Header fehlt. Erwartet: 'Authorization: Bearer am_live_...'\n\n`malformed_key` — Das Format des API-Keys ist ungueltig.\n\n`invalid_key` — API-Key unbekannt oder falsch.\n\n`key_expired` — Der API-Key ist abgelaufen.\n\n`key_revoked` — Der API-Key wurde widerrufen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`ip_not_allowed` — Aufruf von dieser IP-Adresse ist fuer diesen Key nicht freigegeben.\n\n`insufficient_scope` — Der Key besitzt den fuer diesen Endpunkt noetigen Scope nicht.\n\n`reseller_suspended` — Das Reseller-Konto ist gesperrt.\n\n`contract_inactive` — Der Vertrag ist nicht (mehr) aktiv.\n\n`full_database_denied` — Abfragen ohne Branchen- und Geo-Einschraenkung sind fuer diesen Vertrag nicht freigegeben.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_key_reuse` — Der Idempotency-Key wurde bereits fuer eine andere Anfrage verwendet.\n\n`idempotency_in_flight` — Eine Anfrage mit diesem Idempotency-Key wird gerade bearbeitet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`result_too_large` — Die Treffermenge ueberschreitet das Limit fuer synchrone Abfragen. Bitte Bulk-Export verwenden.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`selection_too_broad` — Die Auswahl ist zu breit. Bitte weiter eingrenzen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — Zu viele Anfragen.\n\n`quota_exceeded` — Das vertraglich vereinbarte Kontingent ist aufgebraucht.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal_error` — Interner Fehler.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable` — Dienst voruebergehend nicht verfuegbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suppressions":{"get":{"tags":["Pflichten"],"operationId":"getSuppressions","summary":"Gesperrte, deaktivierte und geloeschte Datensaetze","description":"Unentgeltlich, und **vertraglich verpflichtend regelmaessig abzurufen**. Der Feed nennt Datensaetze, die nicht mehr genutzt werden duerfen.\n\nEr liefert **Basis-IDs**. Ausgelieferte IDs tragen ein Suffix von 13 Zeichen; die Zuordnungsregel steht als `matchRule` in jeder Antwort (`strip-last-13`).\n\nInkrementell abrufen: `pagination.nextSince` der letzten Antwort als `since` mitgeben. Ohne `since` beginnt der Feed beim Vertragsbeginn.\n\nBleibt auch bei Zahlungsverzug erreichbar.","security":[{"bearerAuth":["suppressions:read"]}],"parameters":[{"name":"since","in":"query","required":false,"description":"`nextSince` der vorigen Antwort. Werte vor Vertragsbeginn werden angehoben.","schema":{"type":"string","example":"8412"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10000,"default":1000}}],"responses":{"200":{"description":"Sperrereignisse.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionsResponse"}}}},"400":{"description":"`invalid_parameter` — Ein Parameter fehlt oder ist ungueltig.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_authorization` — Authorization-Header fehlt. Erwartet: 'Authorization: Bearer am_live_...'\n\n`malformed_key` — Das Format des API-Keys ist ungueltig.\n\n`invalid_key` — API-Key unbekannt oder falsch.\n\n`key_expired` — Der API-Key ist abgelaufen.\n\n`key_revoked` — Der API-Key wurde widerrufen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`ip_not_allowed` — Aufruf von dieser IP-Adresse ist fuer diesen Key nicht freigegeben.\n\n`insufficient_scope` — Der Key besitzt den fuer diesen Endpunkt noetigen Scope nicht.\n\n`reseller_suspended` — Das Reseller-Konto ist gesperrt.\n\n`contract_inactive` — Der Vertrag ist nicht (mehr) aktiv.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` — Zu viele Anfragen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal_error` — Interner Fehler.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable` — Dienst voruebergehend nicht verfuegbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"tags":["Referenz"],"operationId":"getOpenApi","summary":"Diese Beschreibung","description":"Oeffentlich, ohne Schluessel abrufbar.","security":[],"responses":{"200":{"description":"OpenAPI-Dokument.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer am_live_…` bzw. `am_test_…` fuer die Sandbox.\n\nDer wirksame Zugriff ist die Schnittmenge aus den Scopes des Schluessels und denen des Vertrags. Moegliche Scopes: `count:read`, `records:read`, `bulk:write`, `bulk:read`, `suppressions:read`, `webhooks:manage`, `usage:read`.\n\n**Sandbox:** Ein `am_test_`-Schluessel verhaelt sich in allem identisch — Zaehlung, Preise, Blaettern, Wasserzeichen —, sieht aber nur einen kleinen, breit gestreuten Ausschnitt echter Firmen. Abrufe werden protokolliert, aber nicht abgerechnet."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["missing_authorization","malformed_key","invalid_key","key_expired","key_revoked","ip_not_allowed","insufficient_scope","reseller_suspended","contract_inactive","full_database_denied","invalid_parameter","criterion_not_permitted","not_found","idempotency_key_reuse","idempotency_in_flight","result_too_large","selection_too_broad","rate_limited","quota_exceeded","internal_error","service_unavailable"],"description":"Stabiler Bezeichner. Hierauf reagieren, nicht auf `message`."},"message":{"type":"string","description":"Erlaeuterung fuer Menschen. Wortlaut kann sich aendern."},"requestId":{"type":"string","description":"Auch im Header `X-Request-Id`. Gehoert in jede Supportanfrage."},"details":{"type":"object","additionalProperties":true}}}}},"Firma":{"type":"object","description":"Welche Felder erscheinen, bestimmt die Kriterienpolitik des Vertrags. Gesperrte Kriterien fehlen vollstaendig — sie sind nicht `null`, sondern gar nicht vorhanden.","properties":{"id":{"type":"string","description":"Gewasserzeichnete ID. Basis-ID = `id.slice(0, -13)`.","pattern":"^.+99999[0-9]{8}$","example":"AM87339999900004387"},"baseId":{"type":"string","description":"Unveraenderte Datensatz-ID. **Diese speichern** — nur sie passt zum Suppression-Feed.","example":"AM8733"},"firmenname":{"type":"string","nullable":true},"postanschrift":{"type":"string","nullable":true,"description":"Kriterium `strasse`."},"plz":{"type":"string","nullable":true},"ort":{"type":"string","nullable":true},"bundesland":{"type":"string","nullable":true},"landkreis":{"type":"string","nullable":true},"land":{"type":"string","nullable":true},"anrede":{"type":"string","nullable":true,"description":"Kriterium `ansprechpartner`."},"ansprechpartner_vorname":{"type":"string","nullable":true,"description":"Kriterium `ansprechpartner`."},"ansprechpartner_nachname":{"type":"string","nullable":true,"description":"Kriterium `ansprechpartner`."},"telefon":{"type":"string","nullable":true,"description":"Kriterium `telefon`."},"email":{"type":"string","nullable":true,"description":"Kriterium `email`."},"homepage":{"type":"string","nullable":true,"description":"Kriterium `homepage`."},"mitarbeiter":{"type":"string","nullable":true,"description":"Kriterium `groesse`."},"gesellschaftsform":{"type":"string","nullable":true},"branche":{"type":"string","nullable":true}}},"MeResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"reseller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"contract":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"billingModel":{"type":"string"}}},"environment":{"type":"string","enum":["LIVE","SANDBOX"]},"key":{"type":"object","description":"Der benutzte Schluessel — nur sein Praefix, nie das Geheimnis. Derselbe Wert steht in den Zugriffsprotokollen und in jeder Verbrauchszeile; wer mehrere Schluessel im Einsatz hat, kann damit zuordnen, welcher gerade arbeitet.","properties":{"prefix":{"type":"string","example":"am_live_9f3k2d7q"}}},"scopes":{"type":"array","items":{"type":"string","enum":["count:read","records:read","bulk:write","bulk:read","suppressions:read","webhooks:manage","usage:read"]}},"countries":{"type":"array","items":{"type":"string"}},"limits":{"type":"object","additionalProperties":true},"criteria":{"type":"array","description":"Nur freigegebene Kriterien. Gesperrte tauchen hier gar nicht auf.","items":{"type":"object","properties":{"kriterium":{"type":"string","enum":["basis","strasse","telefon","email","homepage","ansprechpartner","groesse"]},"mode":{"type":"string","enum":["selectable","forced"]},"auswahl":{"type":"string","enum":["optional","pflicht"],"description":"Nur bei `forced`: der unveraenderbare Wert."},"unitPriceCents":{"type":"integer"},"unitPriceNet":{"type":"string"}}}}}}}},"CountResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer"},"fieldCounts":{"type":"object","additionalProperties":{"type":"integer"},"description":"Gefuellte Felder je Kriterium. Nur fuer freigegebene Kriterien."},"queryHash":{"type":"string"},"cached":{"type":"boolean"},"computedAt":{"type":"string","format":"date-time"},"estimatedRows":{"type":"integer","description":"Obergrenze der Vorab-Schaetzung, nicht die Trefferzahl."},"criteria":{"type":"array","items":{"type":"object"}},"price":{"type":"object","properties":{"currency":{"type":"string","enum":["EUR"]},"netCents":{"type":"integer","description":"Nettobetrag in Cent."},"indicative":{"type":"boolean","description":"`true` bei `/v1/count`: Der Preis kann auf einer bis zu `countCacheTtlSeconds` alten Trefferzahl beruhen und ist unverbindlich. `false` bei `/v1/records`: genau dieser Betrag wird abgerechnet."},"breakdown":{"type":"array","items":{"type":"object","properties":{"kriterium":{"type":"string"},"rows":{"type":"integer","description":"Datensaetze, fuer die dieses Kriterium berechnet wird."},"unitPriceCents":{"type":"integer","description":"Gerundet, nur zur Anzeige."},"unitPriceNet":{"type":"string","description":"Exakter Preis je Datensatz, vier Nachkommastellen. Zum Nachrechnen diesen Wert verwenden, nicht `unitPriceCents` — der ist gerundet.","example":"0.0525"},"netCents":{"type":"integer"}}}}}},"filter":{"type":"object","additionalProperties":true,"description":"Die effektiv angewandten Filter."}}}}},"RecordsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/Firma"}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"returned":{"type":"integer"},"position":{"type":"integer"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"snapshotExpiresAt":{"type":"string","format":"date-time"}}},"delivery":{"type":"object","properties":{"deliveryNo":{"type":"integer","description":"Fortlaufende Liefernummer, steckt im Wasserzeichen."},"idFormat":{"type":"object","properties":{"pattern":{"type":"string"},"baseIdRule":{"type":"string"}}}}},"queryHash":{"type":"string"},"columns":{"type":"array","items":{"type":"string"}},"price":{"type":"object","properties":{"currency":{"type":"string","enum":["EUR"]},"netCents":{"type":"integer","description":"Nettobetrag in Cent."},"indicative":{"type":"boolean","description":"`true` bei `/v1/count`: Der Preis kann auf einer bis zu `countCacheTtlSeconds` alten Trefferzahl beruhen und ist unverbindlich. `false` bei `/v1/records`: genau dieser Betrag wird abgerechnet."},"breakdown":{"type":"array","items":{"type":"object","properties":{"kriterium":{"type":"string"},"rows":{"type":"integer","description":"Datensaetze, fuer die dieses Kriterium berechnet wird."},"unitPriceCents":{"type":"integer","description":"Gerundet, nur zur Anzeige."},"unitPriceNet":{"type":"string","description":"Exakter Preis je Datensatz, vier Nachkommastellen. Zum Nachrechnen diesen Wert verwenden, nicht `unitPriceCents` — der ist gerundet.","example":"0.0525"},"netCents":{"type":"integer"}}}}}}}}}},"SuppressionsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Cursor-Wert dieses Ereignisses."},"firmenId":{"type":"string","description":"Basis-ID."},"reason":{"type":"string","enum":["BLACKLISTED","INACTIVE","DELETED"]},"occurredAt":{"type":"string","format":"date-time"}}}},"matchRule":{"type":"string","enum":["strip-last-13"]},"matchRuleExplanation":{"type":"string"},"pagination":{"type":"object","properties":{"since":{"type":"string"},"nextSince":{"type":"string"},"returned":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}}}}