GET/api/v4/listings/scans/{scanId}

Einen listings scan abrufen

Gibt einen listings scan mit Zusammenfassung und Ergebnissen je Verzeichnis zurück, bei laufendem Scan mit unvollständigen Ergebnissen.

Erfordert einen API-Schlüssel. Format des Headers und Schlüsselrotation finden Sie unter Authentifizierung.

Parameter

Pfad

Name	Typ	Erforderlich	Beschreibung
scanId	string	erforderlich	The scan `id` returned by POST /listings/scans or listed by GET /listings/scans.

Antworten

200A completed scan. The real response lists every directory in `results`, usually around 60. This example is trimmed to six entries, one of each kind described below.

Response

{  "data": {    "listingScan": {      "id": "TGlzdGluZ1NjYW46Mzk0YTRhNWMtZjcwMy00NjZiLTg2NjAtMDU4MTlmNDhkZjMz",      "status": "COMPLETED",      "source": "DIRECTORY_SEARCH",      "locationId": null,      "resultsAsOf": "2026-11-05T07:01:51Z",      "createdAt": "2026-11-05T07:01:08Z",      "startedAt": "2026-11-05T07:01:11Z",      "completedAt": "2026-11-05T07:01:51Z",      "business": {        "name": "Joe's Pizza",        "street": "7 Carmine Street",        "city": "New York",        "stateIso": "NY",        "postalCode": "10014",        "countryIso": "US",        "phone": "+12123661182"      },      "summary": {        "total": 62,        "found": 21,        "accurate": 18,        "inaccurate": 2,        "notFound": 41,        "pending": 0,        "unavailable": 0      },      "failure": null,      "results": [        {          "directory": {            "id": 1,            "name": "Google Maps",            "url": "maps.google.com"          },          "status": "FOUND",          "accurate": true,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "ACCURATE",              "message": null            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine Street",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": "US",            "fullAddress": "7 Carmine St, New York, NY 10014, USA",            "phones": [              "+1 212-366-1182"            ],            "url": "https://maps.google.com/?cid=4877966330195296067"          },          "syncStatus": null        },        {          "directory": {            "id": 2,            "name": "Yelp",            "url": "yelp.com"          },          "status": "FOUND",          "accurate": true,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "ACCURATE",              "message": null            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine St",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": "US",            "fullAddress": "7 Carmine St, New York, NY 10014",            "phones": [              "+12123661182"            ],            "url": "https://www.yelp.com/biz/joes-pizza-new-york-4"          },          "syncStatus": null        },        {          "directory": {            "id": 374,            "name": "Map Quest",            "url": "www.mapquest.com"          },          "status": "FOUND",          "accurate": null,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "MISSING",              "message": "Not shown"            },            "phone": {              "status": "MISSING",              "message": "Not shown"            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine St",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": null,            "fullAddress": "7 Carmine St, New York, NY 10014, US",            "phones": [],            "url": null          },          "syncStatus": null        },        {          "directory": {            "id": 352,            "name": "YellowPages",            "url": "www.yellowpages.com"          },          "status": "NOT_FOUND",          "accurate": null,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": null,          "listing": null,          "syncStatus": null        },        {          "directory": {            "id": 50,            "name": "Judys Book",            "url": "judysbook.com"          },          "status": "FOUND",          "accurate": false,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "INACCURATE",              "message": "Phone number does not match"            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 CARMINE ST",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": null,            "fullAddress": "7 CARMINE ST, New York, NY 10014",            "phones": [              "8553685707"            ],            "url": "https://www.judysbook.com/Joes-Pizza-Uncategorized-newyork-r29271293.htm"          },          "syncStatus": null        },        {          "directory": {            "id": 350,            "name": "Uber",            "url": "uber.com"          },          "status": "FOUND",          "accurate": true,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "ACCURATE",              "message": null            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine Street",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": "US",            "fullAddress": "7 Carmine St, New York, NY 10014, USA",            "phones": [              "+1 212-366-1182"            ],            "url": null          },          "syncStatus": null        }      ]    }  }}

200A failed scan. `failure` has the code and message, and `results` is empty.

Response

{  "data": {    "listingScan": {      "id": "TGlzdGluZ1NjYW46ZGVkZTNhOTgtNDA5Ni00ZDI3LWJlMjUtMzY3YTYxOTk4Y2Y1",      "status": "FAILED",      "source": "DIRECTORY_SEARCH",      "locationId": null,      "resultsAsOf": null,      "createdAt": "2026-11-03T08:53:18Z",      "startedAt": null,      "completedAt": "2026-11-03T08:53:18Z",      "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": {        "code": "SY83010",        "message": "SY83010: Listing scans are temporarily unavailable, try again later",        "field": null      },      "results": []    }  }}

401Unauthenticated, missing or invalid API key.

404No scan with that ID on this account, or the scan is older than 90 days (`SY83005`).

Response

{  "data": {    "listingScan": null  },  "errors": [    {      "message": "SY83005: Listing scan not found"    }  ]}

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

Gibt einen mit POST /listings/scans erstellten Scan mit seinem summary und einem results[]-Eintrag für jedes Verzeichnis zurück. Während der Scan läuft, enthält results die bisherigen Prüfergebnisse, und einige Einträge können noch PENDING sein. Wenn status den Wert COMPLETED hat, sind die Ergebnisse endgültig.

Anwendungsfall: den Bericht nach Eingang des Webhooks lesen. Das Ereignis listing_scan.completed enthält bereits den vollständigen Scan, sodass die meisten Integrationen keinen Lesezugriff benötigen. Verwenden Sie diesen Endpunkt, um einen Scan später erneut abzurufen, ihn in einem Dashboard anzuzeigen oder ihn abzurufen, wenn ein Webhook nicht empfangen wurde.

Anwendungsfall: regelmäßige Abfragen, wenn keine Webhooks verfügbar sind. Rufen Sie den Scan alle 15 Sekunden ab, bis status den Wert COMPLETED oder FAILED hat. Fragen Sie nicht häufiger ab: Jeder Lesezugriff wird auf Ihr Anfragelimit angerechnet. Scans werden 90 Tage lang aufbewahrt; danach gibt dieser Endpunkt 404 mit SY83005 zurück.

Scan-Statuswerte

`status`	Endzustand	Bedeutung
`QUEUED`	nein	Angenommen, noch nicht gestartet. `results` ist leer.
`IN_PROGRESS`	nein	Die Verzeichnisse werden geprüft. `results` wird dabei nach und nach gefüllt.
`COMPLETED`	ja	Jedes Verzeichnis wurde geprüft. Die Ergebnisse sind endgültig.
`FAILED`	ja	Der Scan konnte nicht ausgeführt werden. Lesen Sie `failure`. Er wurde nicht auf Ihr Kontingent angerechnet.

Das Scan-Objekt

Feld	Typ	Beschreibung
`id`	string	Die Scan-ID. Verwenden Sie sie bei diesem Endpunkt.
`status`	string	`QUEUED`, `IN_PROGRESS`, `COMPLETED` oder `FAILED`.
`source`	string	Die Herkunft der Ergebnisse: `DIRECTORY_SEARCH` (eine neue Suche), `RECENT_SCAN` (eine Kopie für ein identisches Unternehmen, für das innerhalb der letzten 7 Tage von einem beliebigen Nutzer ein Scan durchgeführt wurde) oder `LOCATION_LISTINGS` (das Unternehmen stimmte mit einem Ihrer eigenen Standorte überein).
`locationId`	string oder null	Der übereinstimmende Standort. Nur gesetzt, wenn `source` den Wert `LOCATION_LISTINGS` hat.
`resultsAsOf`	string oder null	Der Zeitpunkt, zu dem die Verzeichnisdaten erfasst wurden. Bei einer `RECENT_SCAN`-Kopie liegt dieser Zeitpunkt vor `createdAt`. `null`, bis Ergebnisse vorliegen.
`createdAt`	string	Der Zeitpunkt, zu dem der Scan erstellt wurde.
`startedAt`	string oder null	Der Zeitpunkt, zu dem die Verzeichnisprüfungen begannen.
`completedAt`	string oder null	Der Zeitpunkt, zu dem der Scan den Status `COMPLETED` oder `FAILED` erreichte.
`business`	object	Das Unternehmen, für das der Scan durchgeführt wurde: `name`, `street`, `city`, `stateIso`, `postalCode`, `countryIso` und `phone`. Die Telefonnummer wird im internationalen Format zurückgegeben.
`summary`	object	Zähler für alle Ergebnisse: `total`, `found`, `accurate`, `inaccurate`, `notFound`, `pending` und `unavailable`.
`failure`	object oder null	Gesetzt, wenn `status` den Wert `FAILED` hat: `code`, `message` und, wenn ein einzelnes Eingabefeld die Ursache war, `field`.
`results`	array	Ein Eintrag pro Verzeichnis. Bei einem fehlgeschlagenen Scan leer.

summary.found zählt die Verzeichnisse, in denen das Unternehmen eingetragen ist. Davon zählt accurate diejenigen, deren Angaben übereinstimmen, und inaccurate diejenigen, deren Angaben nicht übereinstimmen. Ein gefundener Eintrag, der ohne Prüfung der einzelnen Felder bestätigt wurde, wird nur in found gezählt, weshalb die Summe aus accurate und inaccurate kleiner als found sein kann.

Ein Ergebnis

Feld	Typ	Beschreibung
`directory`	object	Das Verzeichnis: `id`, `name` und `url`. `id` entspricht der an anderer Stelle in der API verwendeten Site-ID.
`status`	string	`FOUND`, `NOT_FOUND`, `UNAVAILABLE` oder `PENDING`.
`accurate`	boolean oder null	Gibt an, ob der Eintrag mit den Unternehmensdaten übereinstimmt. Siehe unten.
`accuracySource`	string	Wie die Richtigkeit bestimmt wurde: `DIRECTORY_MATCH` (der Eintrag wurde mit den Unternehmensdaten verglichen) oder `SYNC_STATUS` (aus dem Synchronisierungsstatus Ihres eigenen Standorts übernommen).
`accuracy`	object oder null	Die Prüfung pro Feld: `name`, `address` und `phone`, jeweils `{ status, message }`. `null`, wenn kein Eintrag oder kein Vergleich vorliegt.
`listing`	object oder null	Die vom Verzeichnis angezeigten Angaben: `name`, `street`, `city`, `state`, `postalCode`, `country`, `fullAddress`, `phones` und `url`. Felder, die das Verzeichnis nicht veröffentlicht, haben den Wert `null`. `null`, wenn kein Eintrag gefunden wurde.
`syncStatus`	string oder null	Der Synchronisierungsstatus Ihres eigenen Standorts in diesem Verzeichnis. Nur bei `LOCATION_LISTINGS`-Scans gesetzt.

Ergebnis status

Wert	Bedeutung
`FOUND`	Das Unternehmen ist in diesem Verzeichnis eingetragen.
`NOT_FOUND`	Das Verzeichnis wurde geprüft, und das Unternehmen ist nicht eingetragen.
`UNAVAILABLE`	Dieses Verzeichnis konnte diesmal nicht geprüft werden. Das bedeutet nicht, dass das Unternehmen nicht eingetragen ist.
`PENDING`	Noch nicht geprüft. Tritt nur auf, während der Scan läuft.

accurate

Wert	Bedeutung
`true`	Ein gefundener Eintrag, dessen geprüfte Angaben alle mit den Unternehmensdaten übereinstimmen.
`false`	Ein gefundener Eintrag, bei dem mindestens ein Feld falsch ist. Lesen Sie `accuracy`, um zu erfahren, welches Feld betroffen ist.
`null`	Keine Beurteilung. Entweder wurde das Unternehmen nicht gefunden, oder es wurde gefunden und sein Vorhandensein ohne Prüfung der einzelnen Felder bestätigt, wie bei einigen Verzeichnissen und bei KI-Assistenten. Diese werden nur in `found` gezählt.

accuracy pro Feld. name, address und phone sind jeweils ein Objekt mit einem status mit dem Wert ACCURATE, INACCURATE oder MISSING sowie einem message, das eine Abweichung erklärt, zum Beispiel Phone number does not match. MISSING bedeutet, dass das Verzeichnis diese Angabe nicht anzeigt, zum Beispiel No phone number on the listing. Verwenden Sie listing, um die tatsächlich im Verzeichnis gespeicherten Angaben neben den erwarteten Angaben anzuzeigen.

syncStatus. Bei einem LOCATION_LISTINGS-Scan ergibt sich die Beurteilung aus dem tatsächlichen Eintrag Ihres Standorts statt aus einem Vergleich. syncStatus ist der Status dieses Eintrags (SYNCED, COMPLETED, IN_PROGRESS, PENDING_APPROVAL, REQUIRING_ACTION, FAILED, AVAILABLE oder CANNOT_SUBMIT), mit denselben Werten wie bei GET /locations/{locationId}/listings/premium. SYNCED und COMPLETED gelten als korrekt.

Hinweise.

Ein Scan wird nur für das Konto zurückgegeben, das ihn erstellt hat. Bei jeder anderen ID gibt der Endpunkt 404 mit SY83005 zurück.
Einige Verzeichnisse zeigen Daten eines anderen Verzeichnisses an. Beispielsweise zeigen Uber, Waze und Lyft Daten von Google Maps an, und CopilotAI zeigt Daten von Bing an. Ihr Ergebnis entspricht dem des Quellverzeichnisses und enthält kein eigenes url für den Eintrag.
Werten Sie UNAVAILABLE nicht als negatives Ergebnis: Das Verzeichnis konnte nicht geprüft werden, daher ist die Antwort unbekannt.
Wenn der Scan eine RECENT_SCAN-Kopie ist, gibt resultsAsOf den Zeitpunkt der Datenerfassung an und createdAt den Zeitpunkt, zu dem die Daten in Ihr Konto kopiert wurden.

Request

curl -X GET 'https://listingsapi.com/api/v4/listings/scans/<scanId>' \  -H "Authorization: API $LISTINGSAPI_KEY"

Run in playground