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

Obtenir un listings scan

Renvoie un listings scan avec son résumé et ses résultats par annuaire, partiels tant que le scan est en cours.

Nécessite une clé API. Consultez Authentification pour le format de l’en-tête et la rotation des clés.

Paramètres

Chemin

Nom	Type	Obligatoire	Description
scanId	string	obligatoire	The scan `id` returned by POST /listings/scans or listed by GET /listings/scans.

Réponses

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.

Renvoie une analyse créée par POST /listings/scans, avec son summary et une entrée results[] pour chaque annuaire. Pendant l'analyse, results contient les éléments déjà vérifiés, et certaines entrées peuvent encore être PENDING. Lorsque status vaut COMPLETED, les résultats sont définitifs.

Cas d'utilisation : lire le rapport à la réception du webhook. L'événement listing_scan.completed contient déjà l'analyse complète ; la plupart des intégrations n'ont donc besoin d'effectuer aucune lecture. Utilisez ce point de terminaison pour relire une analyse ultérieurement, l'afficher dans un tableau de bord ou la récupérer si un webhook n'a pas été reçu.

Cas d'utilisation : interroger régulièrement le point de terminaison lorsque les webhooks ne sont pas disponibles. Lisez l'analyse toutes les 15 secondes jusqu'à ce que status vaille COMPLETED ou FAILED. N'effectuez pas de lectures plus fréquentes : chaque lecture est comptabilisée dans votre limite de requêtes. Les analyses sont conservées pendant 90 jours ; passé ce délai, ce point de terminaison renvoie 404 avec SY83005.

Statuts de l'analyse

`status`	Final	Signification
`QUEUED`	non	Analyse acceptée, mais pas encore démarrée. `results` est vide.
`IN_PROGRESS`	non	La vérification des annuaires est en cours. `results` se remplit au fur et à mesure.
`COMPLETED`	oui	Tous les annuaires ont été vérifiés. Les résultats sont définitifs.
`FAILED`	oui	L'analyse n'a pas pu être exécutée. Consultez `failure`. Elle n'a pas été décomptée de votre quota.

L'objet d'analyse

Champ	Type	Description
`id`	string	L'ID de l'analyse. Utilisez-le avec ce point de terminaison.
`status`	string	`QUEUED`, `IN_PROGRESS`, `COMPLETED` ou `FAILED`.
`source`	string	La provenance des résultats : `DIRECTORY_SEARCH` (une nouvelle recherche), `RECENT_SCAN` (une copie des résultats d'une analyse d'une entreprise identique effectuée par n'importe quel utilisateur au cours des 7 derniers jours) ou `LOCATION_LISTINGS` (l'entreprise correspondait à l'un de vos propres établissements).
`locationId`	string ou null	L'établissement correspondant. Renseigné uniquement lorsque `source` vaut `LOCATION_LISTINGS`.
`resultsAsOf`	string ou null	La date et l'heure de collecte des données des annuaires. Pour une copie `RECENT_SCAN`, cette date est antérieure à `createdAt`. Vaut `null` tant qu'aucun résultat n'est disponible.
`createdAt`	string	La date et l'heure de création de l'analyse.
`startedAt`	string ou null	La date et l'heure de début des vérifications des annuaires.
`completedAt`	string ou null	La date et l'heure auxquelles l'analyse a atteint le statut `COMPLETED` ou `FAILED`.
`business`	object	L'entreprise analysée : `name`, `street`, `city`, `stateIso`, `postalCode`, `countryIso` et `phone`. Le numéro de téléphone est renvoyé au format international.
`summary`	object	Les totaux pour l'ensemble des résultats : `total`, `found`, `accurate`, `inaccurate`, `notFound`, `pending` et `unavailable`.
`failure`	object ou null	Renseigné lorsque `status` vaut `FAILED` : `code`, `message` et, lorsqu'un champ d'entrée est à l'origine de l'erreur, `field`.
`results`	array	Une entrée par annuaire. Vide si l'analyse a échoué.

summary.found compte les annuaires dans lesquels l'entreprise possède une fiche. Parmi ceux-ci, accurate compte ceux dont les informations correspondent et inaccurate ceux dont les informations ne correspondent pas. Une fiche trouvée dont la présence a été confirmée sans vérification champ par champ est comptabilisée uniquement dans found, ce qui explique pourquoi la somme de accurate et de inaccurate peut être inférieure à found.

Un résultat

Champ	Type	Description
`directory`	object	L'annuaire : `id`, `name` et `url`. Le champ `id` correspond à l'ID du site utilisé ailleurs dans l'API.
`status`	string	`FOUND`, `NOT_FOUND`, `UNAVAILABLE` ou `PENDING`.
`accurate`	boolean ou null	Indique si la fiche correspond à l'entreprise. Voir ci-dessous.
`accuracySource`	string	La méthode utilisée pour déterminer l'exactitude : `DIRECTORY_MATCH` (la fiche a été comparée aux informations de l'entreprise) ou `SYNC_STATUS` (l'exactitude a été déterminée à partir de l'état de synchronisation de votre propre établissement).
`accuracy`	object ou null	La vérification par champ : `name`, `address` et `phone`, chacun étant `{ status, message }`. Vaut `null` en l'absence de fiche ou de comparaison.
`listing`	object ou null	Les informations affichées par l'annuaire : `name`, `street`, `city`, `state`, `postalCode`, `country`, `fullAddress`, `phones` et `url`. Les champs que l'annuaire ne publie pas valent `null`. Vaut `null` lorsqu'aucune fiche n'a été trouvée.
`syncStatus`	string ou null	L'état de synchronisation de votre propre établissement sur cet annuaire. Renseigné uniquement pour les analyses `LOCATION_LISTINGS`.

Résultat status

Valeur	Signification
`FOUND`	L'entreprise possède une fiche dans cet annuaire.
`NOT_FOUND`	L'annuaire a été vérifié et l'entreprise n'y possède pas de fiche.
`UNAVAILABLE`	Cet annuaire n'a pas pu être vérifié cette fois-ci. Cela ne signifie pas que l'entreprise n'y possède pas de fiche.
`PENDING`	Pas encore vérifié. Apparaît uniquement pendant l'analyse.

accurate

Valeur	Signification
`true`	Une fiche trouvée dont toutes les informations vérifiées correspondent à celles de l'entreprise.
`false`	Une fiche trouvée dont au moins un champ est incorrect. Consultez `accuracy` pour savoir lequel.
`null`	Aucune conclusion. Soit l'entreprise n'a pas été trouvée, soit elle a été trouvée et sa présence a été confirmée sans vérification champ par champ, comme pour certains annuaires et pour les assistants IA. Ces résultats sont comptabilisés uniquement dans `found`.

accuracy par champ. Chacun des champs name, address et phone est un objet dont le champ status vaut ACCURATE, INACCURATE ou MISSING, et dont le champ message explique une différence, par exemple Phone number does not match. MISSING signifie que l'annuaire n'affiche pas cette information, par exemple No phone number on the listing. Utilisez listing pour afficher les informations réellement présentes dans l'annuaire à côté de celles que vous attendiez.

syncStatus. Pour une analyse LOCATION_LISTINGS, la conclusion provient de la fiche réelle de votre établissement plutôt que d'une comparaison. syncStatus est l'état de cette fiche (SYNCED, COMPLETED, IN_PROGRESS, PENDING_APPROVAL, REQUIRING_ACTION, FAILED, AVAILABLE ou CANNOT_SUBMIT), avec les mêmes valeurs que GET /locations/{locationId}/listings/premium. SYNCED et COMPLETED sont considérés comme indiquant une fiche exacte.

Remarques.

Une analyse n'est renvoyée que pour le compte qui l'a créée. Pour tout autre ID, le point de terminaison renvoie 404 avec SY83005.
Certains annuaires affichent les données d'un autre annuaire. Par exemple, Uber, Waze et Lyft affichent les données de Google Maps, et CopilotAI affiche les données de Bing. Leur résultat reprend celui de l'annuaire source et ne possède pas de url de fiche qui lui soit propre.
N'interprétez pas UNAVAILABLE comme un résultat négatif : l'annuaire n'a pas pu être vérifié, la réponse est donc inconnue.
Lorsque l'analyse est une copie RECENT_SCAN, resultsAsOf indique la date et l'heure de collecte des données, et createdAt la date et l'heure de leur copie dans votre compte.

Request

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

Run in playground