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

Obtener un listings scan

Devuelve un listings scan con su resumen y resultados por directorio, parciales mientras el escaneo sigue en curso.

Requiere una clave de API. Consulta Autenticación para conocer el formato del encabezado y la rotación de claves.

Parámetros

Ruta

Nombre	Tipo	Obligatorio	Descripción
scanId	string	obligatorio	The scan `id` returned by POST /listings/scans or listed by GET /listings/scans.

Respuestas

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.

Devuelve un análisis creado por POST /listings/scans, con su summary y una entrada results[] por cada directorio. Mientras el análisis está en curso, results contiene lo que se ha comprobado hasta el momento, y algunas entradas pueden seguir en PENDING. Cuando status es COMPLETED, los resultados son definitivos.

Caso de uso: consultar el informe cuando llega el webhook. El evento listing_scan.completed ya incluye el análisis completo, por lo que la mayoría de las integraciones no necesitan realizar ninguna consulta. Usa este endpoint para volver a consultar un análisis más adelante, mostrarlo en un panel o recuperarlo si no se recibió un webhook.

Caso de uso: realizar consultas periódicas cuando los webhooks no están disponibles. Consulta el análisis cada 15 segundos hasta que status sea COMPLETED o FAILED. No lo consultes con más frecuencia: cada consulta cuenta para tu límite de solicitudes. Los análisis se conservan durante 90 días; después de ese plazo, este endpoint devuelve 404 con SY83005.

Estados del análisis

`status`	Terminal	Significado
`QUEUED`	no	Aceptado, sin iniciar. `results` está vacío.
`IN_PROGRESS`	no	Se están comprobando los directorios. `results` se va completando a medida que avanza el análisis.
`COMPLETED`	sí	Se han comprobado todos los directorios. Los resultados son definitivos.
`FAILED`	sí	El análisis no se ha podido ejecutar. Consulta `failure`. No ha consumido tu cuota.

El objeto del análisis

Campo	Tipo	Descripción
`id`	string	El ID del análisis. Úsalo en este endpoint.
`status`	string	`QUEUED`, `IN_PROGRESS`, `COMPLETED` o `FAILED`.
`source`	string	De dónde proceden los resultados: `DIRECTORY_SEARCH` (una búsqueda nueva), `RECENT_SCAN` (una copia de un negocio idéntico analizado por cualquier usuario en los últimos 7 días) o `LOCATION_LISTINGS` (el negocio coincide con una de tus propias ubicaciones).
`locationId`	string o null	La ubicación coincidente. Solo se establece cuando `source` es `LOCATION_LISTINGS`.
`resultsAsOf`	string o null	Cuándo se recopilaron los datos del directorio. En una copia `RECENT_SCAN`, esta fecha es anterior a `createdAt`. `null` hasta que haya resultados.
`createdAt`	string	Cuándo se creó el análisis.
`startedAt`	string o null	Cuándo comenzaron las comprobaciones de los directorios.
`completedAt`	string o null	Cuándo el análisis alcanzó el estado `COMPLETED` o `FAILED`.
`business`	object	El negocio analizado: `name`, `street`, `city`, `stateIso`, `postalCode`, `countryIso` y `phone`. El teléfono se devuelve en formato internacional.
`summary`	object	Recuentos de los resultados: `total`, `found`, `accurate`, `inaccurate`, `notFound`, `pending` y `unavailable`.
`failure`	object o null	Se establece cuando `status` es `FAILED`: `code`, `message` y, cuando la causa es un campo de entrada, `field`.
`results`	array	Una entrada por directorio. Vacío si el análisis falla.

summary.found cuenta los directorios en los que el negocio tiene una ficha. De ellos, accurate cuenta aquellos cuyos datos coinciden y inaccurate aquellos cuyos datos no coinciden. Una ficha encontrada que se haya confirmado sin una comprobación campo por campo se incluye solo en found, por lo que la suma de accurate y inaccurate puede ser inferior a found.

Un resultado

Campo	Tipo	Descripción
`directory`	object	El directorio: `id`, `name` y `url`. El valor de `id` coincide con el ID del sitio utilizado en otras partes de la API.
`status`	string	`FOUND`, `NOT_FOUND`, `UNAVAILABLE` o `PENDING`.
`accurate`	boolean o null	Si la ficha coincide con el negocio. Consulta la explicación a continuación.
`accuracySource`	string	Cómo se determinó la exactitud: `DIRECTORY_MATCH` (se comparó la ficha con el negocio) o `SYNC_STATUS` (se obtuvo del estado de sincronización de tu propia ubicación).
`accuracy`	object o null	La comprobación por campo: `name`, `address` y `phone`, cada uno de tipo `{ status, message }`. `null` cuando no hay ficha o no se ha realizado una comparación.
`listing`	object o null	Lo que muestra el directorio: `name`, `street`, `city`, `state`, `postalCode`, `country`, `fullAddress`, `phones` y `url`. Los campos que el directorio no publica tienen el valor `null`. `null` cuando no se encuentra la ficha.
`syncStatus`	string o null	El estado de sincronización de tu propia ubicación en este directorio. Solo se establece en los análisis `LOCATION_LISTINGS`.

status del resultado

Valor	Significado
`FOUND`	El negocio tiene una ficha en este directorio.
`NOT_FOUND`	Se ha comprobado el directorio y el negocio no tiene una ficha.
`UNAVAILABLE`	No se ha podido comprobar este directorio en esta ocasión. Esto no significa que el negocio no tenga una ficha.
`PENDING`	Aún no se ha comprobado. Solo aparece mientras el análisis está en curso.

accurate

Valor	Significado
`true`	Una ficha encontrada cuyos datos comprobados coinciden todos con los del negocio.
`false`	Una ficha encontrada en la que al menos un campo es incorrecto. Consulta `accuracy` para ver cuál.
`null`	Sin conclusión. No se ha encontrado el negocio, o se ha encontrado y se ha confirmado su presencia sin una comprobación campo por campo, como ocurre con algunos directorios y con los asistentes de IA. Estos casos solo se cuentan en `found`.

accuracy por campo. Cada uno de los campos name, address y phone es un objeto con un campo status cuyo valor es ACCURATE, INACCURATE o MISSING, y un campo message que explica una diferencia, por ejemplo, Phone number does not match. MISSING significa que el directorio no muestra ese dato, por ejemplo, No phone number on the listing. Usa listing para mostrar los datos que realmente contiene el directorio junto a los que esperabas.

syncStatus. En un análisis LOCATION_LISTINGS, la conclusión se obtiene de la ficha real de tu ubicación en lugar de una comparación. syncStatus es el estado de esa ficha (SYNCED, COMPLETED, IN_PROGRESS, PENDING_APPROVAL, REQUIRING_ACTION, FAILED, AVAILABLE o CANNOT_SUBMIT), con los mismos valores que GET /locations/{locationId}/listings/premium. SYNCED y COMPLETED se consideran exactos.

Notas.

Un análisis solo se devuelve a la cuenta que lo creó. Para cualquier otro ID, el endpoint devuelve 404 con SY83005.
Algunos directorios muestran datos de otro directorio. Por ejemplo, Uber, Waze y Lyft muestran datos de Google Maps, y CopilotAI muestra datos de Bing. Su resultado refleja el del directorio de origen y no tiene un url de ficha propio.
No interpretes UNAVAILABLE como un resultado negativo: no se ha podido comprobar el directorio, por lo que la respuesta se desconoce.
Cuando el análisis es una copia RECENT_SCAN, resultsAsOf indica cuándo se recopilaron los datos y createdAt indica cuándo se copiaron a tu cuenta.

Request

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

Run in playground