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

Ottieni un listings scan

Restituisce un listings scan con il riepilogo e i risultati per directory, parziali mentre la scansione è ancora in corso.

Richiede una chiave API. Consulta Autenticazione per il formato dell’header e la rotazione delle chiavi.

Parametri

Percorso

Nome	Tipo	Obbligatorio	Descrizione
scanId	string	obbligatorio	The scan `id` returned by POST /listings/scans or listed by GET /listings/scans.

Risposte

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.

Restituisce una scansione creata da POST /listings/scans, con il relativo summary e una voce results[] per ogni directory. Durante l'esecuzione della scansione, results contiene quanto è stato verificato fino a quel momento e alcune voci potrebbero essere ancora PENDING. Quando status è COMPLETED, i risultati sono definitivi.

Caso d'uso: leggere il report dopo la ricezione del webhook. L'evento listing_scan.completed include già la scansione completa, quindi la maggior parte delle integrazioni non richiede alcuna lettura. Usa questo endpoint per rileggere una scansione in un secondo momento, per mostrarla in una dashboard o per recuperarla se un webhook non è stato ricevuto.

Caso d'uso: polling quando i webhook non sono disponibili. Leggi la scansione ogni 15 secondi finché status non è COMPLETED o FAILED. Non eseguire il polling più frequentemente: ogni lettura viene conteggiata nel tuo limite di richieste. Le scansioni vengono conservate per 90 giorni; trascorso questo periodo, l'endpoint restituisce 404 con SY83005.

Stati della scansione

`status`	Finale	Significato
`QUEUED`	no	Accettata, non ancora avviata. `results` è vuoto.
`IN_PROGRESS`	no	La verifica delle directory è in corso. `results` si popola man mano.
`COMPLETED`	sì	Tutte le directory sono state verificate. I risultati sono definitivi.
`FAILED`	sì	Non è stato possibile eseguire la scansione. Leggi `failure`. Non ha consumato la tua quota disponibile.

L'oggetto scansione

Campo	Tipo	Descrizione
`id`	string	L'ID della scansione. Usalo con questo endpoint.
`status`	string	`QUEUED`, `IN_PROGRESS`, `COMPLETED` o `FAILED`.
`source`	string	L'origine dei risultati: `DIRECTORY_SEARCH` (una nuova ricerca), `RECENT_SCAN` (una copia dei dati di un'attività identica sottoposta a scansione da chiunque negli ultimi 7 giorni) o `LOCATION_LISTINGS` (l'attività corrispondeva a una delle tue sedi).
`locationId`	string o null	La sede corrispondente. Impostato solo quando `source` è `LOCATION_LISTINGS`.
`resultsAsOf`	string o null	Quando sono stati raccolti i dati delle directory. Per una copia `RECENT_SCAN`, questo momento è precedente a `createdAt`. `null` finché non sono disponibili risultati.
`createdAt`	string	Quando è stata creata la scansione.
`startedAt`	string o null	Quando sono iniziate le verifiche delle directory.
`completedAt`	string o null	Quando la scansione ha raggiunto lo stato `COMPLETED` o `FAILED`.
`business`	object	L'attività sottoposta a scansione: `name`, `street`, `city`, `stateIso`, `postalCode`, `countryIso` e `phone`. Il numero di telefono viene restituito in formato internazionale.
`summary`	object	Conteggi complessivi dei risultati: `total`, `found`, `accurate`, `inaccurate`, `notFound`, `pending` e `unavailable`.
`failure`	object o null	Impostato quando `status` è `FAILED`: `code`, `message` e, quando la causa è un singolo campo di input, `field`.
`results`	array	Una voce per directory. Vuoto se la scansione non è riuscita.

summary.found conta le directory in cui è presente la scheda dell'attività. Tra queste, accurate conta quelle i cui dettagli corrispondono e inaccurate quelle i cui dettagli non corrispondono. Una scheda trovata e confermata senza una verifica campo per campo viene conteggiata solo in found, perciò la somma di accurate e inaccurate può essere inferiore a found.

Un risultato

Campo	Tipo	Descrizione
`directory`	object	La directory: `id`, `name` e `url`. `id` corrisponde all'ID del sito usato altrove nell'API.
`status`	string	`FOUND`, `NOT_FOUND`, `UNAVAILABLE` o `PENDING`.
`accurate`	boolean o null	Indica se la scheda corrisponde all'attività. Vedi sotto.
`accuracySource`	string	Come è stata determinata l'accuratezza: `DIRECTORY_MATCH` (la scheda è stata confrontata con l'attività) o `SYNC_STATUS` (ricavata dallo stato di sincronizzazione della tua sede).
`accuracy`	object o null	La verifica per ciascun campo: `name`, `address` e `phone`, ciascuno `{ status, message }`. `null` quando non è presente alcuna scheda o non è stato eseguito alcun confronto.
`listing`	object o null	I dati mostrati dalla directory: `name`, `street`, `city`, `state`, `postalCode`, `country`, `fullAddress`, `phones` e `url`. I campi che la directory non pubblica sono `null`. `null` quando la scheda non viene trovata.
`syncStatus`	string o null	Lo stato di sincronizzazione della tua sede su questa directory. Impostato solo per le scansioni `LOCATION_LISTINGS`.

status del risultato

Valore	Significato
`FOUND`	La scheda dell'attività è presente in questa directory.
`NOT_FOUND`	La directory è stata verificata e la scheda dell'attività non è presente.
`UNAVAILABLE`	Non è stato possibile verificare questa directory questa volta. Questo non significa che la scheda dell'attività sia assente.
`PENDING`	Non ancora verificata. Presente solo durante l'esecuzione della scansione.

accurate

Valore	Significato
`true`	Una scheda trovata i cui dettagli verificati corrispondono tutti a quelli dell'attività.
`false`	Una scheda trovata in cui almeno un campo è errato. Leggi `accuracy` per sapere quale.
`null`	Nessuna valutazione. L'attività non è stata trovata oppure è stata trovata e la sua presenza è stata confermata senza una verifica campo per campo, come avviene per alcune directory e per gli assistenti AI. Questi risultati vengono conteggiati solo in `found`.

accuracy per campo. Ciascuno dei campi name, address e phone è un oggetto con un status pari a ACCURATE, INACCURATE o MISSING e un message che spiega una differenza, ad esempio Phone number does not match. MISSING significa che la directory non mostra quel dettaglio, ad esempio No phone number on the listing. Usa listing per visualizzare i dati effettivamente presenti nella directory accanto a quelli attesi.

syncStatus. In una scansione LOCATION_LISTINGS, la valutazione deriva dalla scheda effettiva della tua sede anziché da un confronto. syncStatus è lo stato di quella scheda (SYNCED, COMPLETED, IN_PROGRESS, PENDING_APPROVAL, REQUIRING_ACTION, FAILED, AVAILABLE o CANNOT_SUBMIT), con gli stessi valori di GET /locations/{locationId}/listings/premium. SYNCED e COMPLETED vengono considerati accurati.

Note.

Una scansione viene restituita solo all'account che l'ha creata. Per qualsiasi altro ID, l'endpoint restituisce 404 con SY83005.
Alcune directory mostrano i dati di un'altra directory. Ad esempio, Uber, Waze e Lyft mostrano i dati di Google Maps e CopilotAI mostra i dati di Bing. Il loro risultato rispecchia quello della directory di origine e non ha un proprio url della scheda.
Non interpretare UNAVAILABLE come un risultato negativo: non è stato possibile verificare la directory, quindi la risposta è sconosciuta.
Quando la scansione è una copia RECENT_SCAN, resultsAsOf indica quando sono stati raccolti i dati e createdAt quando sono stati copiati nel tuo account.

Request

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

Run in playground