Einen listings scan erstellen

Name	Typ	Erforderlich	Beschreibung
input	object	erforderlich	Wrapper object. The entire request body must be nested under `input`.
input.name	string	erforderlich	Business name, up to 150 characters.
input.street	string	erforderlich	Street address, up to 200 characters.
input.city	string	erforderlich	City, up to 100 characters.
input.stateIso	string	optional	State or province code, up to 50 characters. Required for every country except `GB`.
input.postalCode	string	optional	Postal code, up to 20 characters. Required for every country except `NG` and `AE`.
input.countryIso	string	erforderlich	Two-letter ISO 3166-1 country code, for example `US`.
input.phone	string	erforderlich	Business phone number with 6 to 15 digits. Local formats are read in the context of `countryIso`, and an international format with a leading `+` works too.

Startet einen Scan eines einzelnen Unternehmens. Der Scan prüft, ob und wie genau das Unternehmen im Verzeichnisnetzwerk eingetragen ist: in Kartendiensten und Suchmaschinen wie Google, Bing, Apple Maps, Yelp, Facebook und MapQuest, bei Datenaggregatoren und in lokalen Verzeichnissen sowie bei KI-Assistenten wie ChatGPT und Gemini. Je nach Land prüft ein Scan bis zu etwa 60 Verzeichnisse. Das Unternehmen muss nicht als Standort in Ihrem Konto vorhanden sein. Sie können also einen potenziellen Kunden oder einen Kunden vor der Einrichtung prüfen.

Der Aufruf gibt den Scan sofort mit dem Status QUEUED zurück. Die Verzeichnisprüfungen laufen im Hintergrund, und das Ergebnis wird mit GET /listings/scans/{scanId} abgerufen.

Anwendungsfall: Prüfung der Einträge eines potenziellen Kunden. Ihre Vertriebssoftware erfasst den Namen, die Adresse und die Telefonnummer eines Unternehmens. Erstellen Sie einen Scan, speichern Sie die zurückgegebene scan.id und rufen Sie den abgeschlossenen Scan über data.scan ab, sobald das Ereignis listing_scan.completed eintrifft. summary liefert die Zusammenfassung (in wie vielen Verzeichnissen das Unternehmen gefunden wurde und wie viele dieser Einträge korrekt sind), und results[] liefert die Details zu den einzelnen Verzeichnissen für die Anzeige im Bericht.

Anwendungsfall: Zustandsprüfung für ein Unternehmen, das Sie bereits verwalten. Führen Sie einen Scan mit den Unternehmensdaten eines Ihrer eigenen Standorte durch. Der Scan erkennt den Standort und erstellt seine Ergebnisse anhand der tatsächlichen Einträge dieses Standorts, statt erneut zu suchen (siehe Wiederverwendung und kostenlose Scans).

So wird ein Scan abgeschlossen

Ein Scan durchläuft die Status QUEUED und IN_PROGRESS und endet dann mit COMPLETED oder FAILED. Die meisten Scans sind nach einer bis sieben Minuten abgeschlossen. Wenn ein Verzeichnis nach etwa 15 Minuten nicht geantwortet hat, wird sein Ergebnis auf UNAVAILABLE gesetzt und der Scan mit den übrigen Ergebnissen abgeschlossen.

Verwenden Sie vorzugsweise den Webhook. Die Ereignisse listing_scan.completed und listing_scan.failed werden einmal pro Scan mit demselben Scan-Objekt übermittelt, das GET /listings/scans/{scanId} zurückgibt, einschließlich der Ergebnisse. Sie werden an Konten gesendet, bei denen Webhooks aktiviert sind und eine verifizierte Webhook-URL hinterlegt ist, und wie alle anderen Ereignisse signiert. Siehe listing_scan.completed.
Verwenden Sie Polling als Alternative. Wenn Sie keine Webhooks empfangen können, rufen Sie den Scan alle 15 Sekunden ab, bis status den Wert COMPLETED oder FAILED hat. Häufigere Abfragen bringen keinen Vorteil und verbrauchen Ihr Anfragekontingent.

Pflichtfelder

name, street, city, countryIso und phone sind immer erforderlich. Zwei Felder hängen vom Land ab:

Feld	Erforderlich	Ausnahmen
`stateIso`	Ja	Für `GB` nicht erforderlich.
`postalCode`	Ja	Für `NG` und `AE` nicht erforderlich.

Ein fehlender oder falsch formatierter Wert wird mit SY83003 abgelehnt, und die Fehlermeldung nennt das Feld. phone muss zwischen 6 und 15 Ziffern enthalten, und countryIso muss aus zwei Buchstaben bestehen.

Wiederverwendung und kostenlose Scans

Ein Scan führt nicht immer eine neue Suche durch. Das Feld source im zurückgegebenen Scan gibt an, woher seine Ergebnisse stammen:

`source`	Wann dieser Wert zurückgegeben wird
`DIRECTORY_SEARCH`	Eine neue Suche in den Verzeichnissen. Nur diese Art von Scan verbraucht Ihr monatliches Kontingent.
`RECENT_SCAN`	Dasselbe Unternehmen wurde innerhalb der letzten 7 Tage von einem beliebigen Nutzer gescannt, daher wurden seine Ergebnisse kopiert. `resultsAsOf` zeigt an, wann die Daten erfasst wurden. Der Scan wird bereits mit dem Status `COMPLETED` zurückgegeben.
`LOCATION_LISTINGS`	Das Unternehmen stimmt anhand von Telefonnummer, Postleitzahl und Land mit einem Ihrer eigenen Standorte überein. Die Ergebnisse stammen aus den tatsächlichen Einträgen dieses Standorts, `locationId` ist gesetzt, und jedes Ergebnis enthält `syncStatus`.

Wenn Sie dasselbe Unternehmen innerhalb von 7 Tagen erneut scannen, wird der vorhandene Scan aus Ihrem Konto anstelle eines neuen zurückgegeben, mit reused: true in der Antwort. Es wird kein neuer Scan gestartet und kein neuer Webhook gesendet. Rufen Sie daher den zurückgegebenen Scan ab (er kann noch laufen), statt auf ein weiteres Ereignis zu warten. Wenn Sie einen Ihrer eigenen Standorte innerhalb des Wiederverwendungszeitraums erneut scannen, verhält es sich genauso.

Monatliches Kontingent

Listings scans sind in kostenpflichtigen Tarifen mit einem monatlichen Kontingent enthalten, das von Ihrem Tarif abhängt. Mit einem kostenlosen Sandbox-Tagespass sind sie nicht verfügbar. Nur ein neuer DIRECTORY_SEARCH-Scan wird auf das Kontingent angerechnet. Folgendes ist kostenlos:

eine Wiederholung für dasselbe Unternehmen innerhalb von 7 Tagen (reused: true),
eine RECENT_SCAN-Kopie,
ein LOCATION_LISTINGS-Scan,
ein fehlgeschlagener Scan, der nicht angerechnet wird.

Das Kontingent wird mit dem Abrechnungszeitraum Ihres Kontos zurückgesetzt. Jede Antwort auf eine Anfrage zum Erstellen enthält quota mit limit, used, remaining und resetsAt, auch wenn die Anfrage abgelehnt wird. Siehe Tarife und Zusatzoptionen.

Fehler

Eine abgelehnte Anfrage zum Erstellen liefert HTTP 200 mit scan: null und dem Grund in errors[] zurück. Prüfen Sie daher errors und nicht nur den Statuscode. Schlüssel mit ausschließlichem Lesezugriff können keine Scans erstellen: Dies ist der einzige Fehler auf Anfrageebene und liefert HTTP 400 mit SY90016 zurück.

Code	Bedeutung	Maßnahme
`SY83001`	Listings scans sind in Ihrem Tarif nicht verfügbar.	Verwenden Sie ein Konto mit einem kostenpflichtigen Tarif. Mit Tagespässen können keine Scans ausgeführt werden.
`SY83002`	Das monatliche Kontingent ist aufgebraucht. Die Meldung enthält das Limit und den Zeitpunkt der Zurücksetzung, und `quota` wird zurückgegeben.	Warten Sie auf `quota.resetsAt` oder kontaktieren Sie uns wegen eines höheren Kontingents. Die Wiederverwendung eines kürzlich durchgeführten Scans ist kostenlos.
`SY83003`	Ein Feld fehlt oder ist ungültig. `contextInfo` nennt es unter `field`.	Korrigieren Sie dieses Feld und senden Sie die Anfrage erneut.
`SY83004`	Für dieses Land sind keine Scans verfügbar.	Prüfen Sie `countryIso`. Die Meldung nennt den abgelehnten Code.
`SY83010`	Scans sind vorübergehend nicht verfügbar.	Versuchen Sie es später erneut.

Die vollständige Liste der Codes finden Sie unter Fehlercodes.

Hinweise.

Der Anfrageinhalt muss in ein input-Objekt eingebettet sein.
Prüfen Sie errors, nicht den HTTP-Status. Eine abgelehnte Anfrage zum Erstellen liefert HTTP 200 zurück.
Telefonnummern werden vor der Ausführung des Scans normalisiert, und zwei Anfragen, die sich nur in Formatierung, Groß- und Kleinschreibung oder Leerzeichen unterscheiden, werden demselben Unternehmen zugeordnet.
Eine Anfrage zum Erstellen wird als eine Anfrage auf Ihr Anfragelimit angerechnet, unabhängig davon, wie viele Verzeichnisse der Scan prüft.
Ein Scan wird 90 Tage lang gespeichert. Danach liefert das Abrufen des Scans 404 mit SY83005 zurück.
Dieser Aufruf erfordert einen Schlüssel mit der Berechtigung Write (Schreibzugriff).

Antworten

200The scan was accepted and is `QUEUED`. `reused` is `false` and `results` is empty until directories are checked. Wait for the `listing_scan.completed` webhook, or poll the scan.

Response

{  "data": {    "createListingScan": {      "reused": false,      "scan": {        "id": "TGlzdGluZ1NjYW46N2MxZTRmNTItOWEzYi00ZDY4LWIwZTEtNWYyYThjOWQzZTQ3",        "status": "QUEUED",        "source": "DIRECTORY_SEARCH",        "locationId": null,        "resultsAsOf": null,        "createdAt": "2026-11-05T07:00:41Z",        "startedAt": null,        "completedAt": null,        "business": {          "name": "Franklin Barbecue",          "street": "900 E 11th St",          "city": "Austin",          "stateIso": "TX",          "postalCode": "78702",          "countryIso": "US",          "phone": "+15126531187"        },        "summary": {          "total": 0,          "found": 0,          "accurate": 0,          "inaccurate": 0,          "notFound": 0,          "pending": 0,          "unavailable": 0        },        "failure": null,        "results": []      },      "quota": {        "limit": 50,        "used": 6,        "remaining": 44,        "resetsAt": "2026-11-23T12:38:03Z"      },      "errors": []    }  }}

200The request was rejected, so **no scan was created**. The error is reported in `errors[]` on an `HTTP 200`, `scan` is `null`, and `quota` still returns the current allowance. This example is a phone number with too few digits.

{  "data": {    "createListingScan": {      "reused": false,      "scan": null,      "quota": {        "limit": 50,        "used": 5,        "remaining": 45,        "resetsAt": "2026-11-23T12:38:03Z"      },      "errors": [        {          "code": "SY83003",          "message": "SY83003: Invalid value for phone",          "contextInfo": [            {              "key": "field",              "value": "phone"            }          ]        }      ]    }  }}

400A read-only key was used on this write (`SY90016`). Use a Write key.

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.