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

Obter um listings scan

Retorna um listings scan com seu resumo e resultados por diretório, parciais enquanto o listings scan ainda está em execução.

Requer uma chave de API. Consulte Autenticação para ver o formato do cabeçalho e a rotação de chaves.

Parâmetros

Caminho

Nome	Tipo	Obrigatório	Descrição
scanId	string	obrigatório	The scan `id` returned by POST /listings/scans or listed by GET /listings/scans.

Respostas

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.

Retorna uma varredura criada por POST /listings/scans, com seu summary e uma entrada de results[] para cada diretório. Enquanto a varredura está em execução, results contém o que já foi verificado, e algumas entradas ainda podem estar como PENDING. Quando status é COMPLETED, os resultados são definitivos.

Caso de uso: ler o relatório após a chegada do webhook. O evento listing_scan.completed já inclui a varredura completa, portanto a maioria das integrações não precisa fazer nenhuma leitura. Use este endpoint para reler uma varredura mais tarde, exibi-la em um painel ou recuperá-la caso um webhook não tenha sido recebido.

Caso de uso: consultar periodicamente quando os webhooks não estão disponíveis. Consulte a varredura a cada 15 segundos até que status seja COMPLETED ou FAILED. Não consulte com maior frequência: cada leitura conta para o seu limite de requisições. As varreduras são mantidas por 90 dias; depois desse período, este endpoint retorna 404 com SY83005.

Status da varredura

`status`	Final	Significado
`QUEUED`	não	Aceita, mas não iniciada. `results` está vazio.
`IN_PROGRESS`	não	Os diretórios estão sendo verificados. `results` é preenchido à medida que a verificação avança.
`COMPLETED`	sim	Todos os diretórios foram verificados. Os resultados são definitivos.
`FAILED`	sim	Não foi possível executar a varredura. Leia `failure`. Ela não consumiu sua cota.

O objeto da varredura

Campo	Tipo	Descrição
`id`	string	O ID da varredura. Use-o neste endpoint.
`status`	string	`QUEUED`, `IN_PROGRESS`, `COMPLETED` ou `FAILED`.
`source`	string	A origem dos resultados: `DIRECTORY_SEARCH` (uma nova pesquisa), `RECENT_SCAN` (uma cópia de uma varredura de uma empresa idêntica realizada por qualquer pessoa nos últimos 7 dias) ou `LOCATION_LISTINGS` (a empresa correspondeu a um dos seus próprios locais).
`locationId`	string ou null	O local correspondente. Definido somente quando `source` é `LOCATION_LISTINGS`.
`resultsAsOf`	string ou null	Quando os dados dos diretórios foram coletados. Para uma cópia `RECENT_SCAN`, esse momento é anterior a `createdAt`. `null` até que existam resultados.
`createdAt`	string	Quando a varredura foi criada.
`startedAt`	string ou null	Quando as verificações dos diretórios começaram.
`completedAt`	string ou null	Quando a varredura atingiu `COMPLETED` ou `FAILED`.
`business`	object	A empresa verificada na varredura: `name`, `street`, `city`, `stateIso`, `postalCode`, `countryIso` e `phone`. O telefone é retornado no formato internacional.
`summary`	object	Contagens dos resultados: `total`, `found`, `accurate`, `inaccurate`, `notFound`, `pending` e `unavailable`.
`failure`	object ou null	Definido quando `status` é `FAILED`: `code`, `message` e, quando um campo de entrada foi a causa, `field`.
`results`	array	Uma entrada por diretório. Vazio em uma varredura que falhou.

summary.found conta os diretórios em que a empresa está listada. Desses, accurate conta aqueles cujos dados correspondem aos da empresa e inaccurate conta aqueles cujos dados não correspondem. Uma listagem encontrada e confirmada sem uma verificação campo a campo é contabilizada apenas em found, por isso a soma de accurate e inaccurate pode ser menor que found.

Um resultado

Campo	Tipo	Descrição
`directory`	object	O diretório: `id`, `name` e `url`. `id` corresponde ao ID do site usado em outras partes da API.
`status`	string	`FOUND`, `NOT_FOUND`, `UNAVAILABLE` ou `PENDING`.
`accurate`	boolean ou null	Indica se a listagem corresponde à empresa. Veja abaixo.
`accuracySource`	string	Como a exatidão foi determinada: `DIRECTORY_MATCH` (a listagem foi comparada com a empresa) ou `SYNC_STATUS` (obtida do estado de sincronização do seu próprio local).
`accuracy`	object ou null	A verificação por campo: `name`, `address` e `phone`, cada um com `{ status, message }`. `null` quando não há listagem ou comparação.
`listing`	object ou null	O que o diretório exibe: `name`, `street`, `city`, `state`, `postalCode`, `country`, `fullAddress`, `phones` e `url`. Os campos que o diretório não publica são `null`. `null` quando a listagem não é encontrada.
`syncStatus`	string ou null	O estado de sincronização do seu próprio local neste diretório. Definido apenas em varreduras `LOCATION_LISTINGS`.

status do resultado

Valor	Significado
`FOUND`	A empresa está listada neste diretório.
`NOT_FOUND`	O diretório foi verificado e a empresa não está listada.
`UNAVAILABLE`	Não foi possível verificar este diretório desta vez. Isso não significa que a empresa não esteja listada.
`PENDING`	Ainda não verificado. Aparece apenas enquanto a varredura está em execução.

accurate

Valor	Significado
`true`	Uma listagem encontrada cujos dados verificados correspondem integralmente aos da empresa.
`false`	Uma listagem encontrada em que pelo menos um campo está incorreto. Leia `accuracy` para ver qual.
`null`	Sem conclusão. A empresa não foi encontrada ou foi encontrada e sua presença foi confirmada sem uma verificação campo a campo, como ocorre em alguns diretórios e em assistentes de IA. Esses resultados são contabilizados apenas em `found`.

accuracy por campo. Cada um dos campos name, address e phone é um objeto com um status de valor ACCURATE, INACCURATE ou MISSING e um message que explica uma diferença, por exemplo, Phone number does not match. MISSING significa que o diretório não exibe esse dado, por exemplo, No phone number on the listing. Use listing para exibir o que o diretório realmente contém ao lado do que você esperava.

syncStatus. Em uma varredura LOCATION_LISTINGS, a conclusão vem da listagem real do seu local, em vez de uma comparação. syncStatus é o estado dessa listagem (SYNCED, COMPLETED, IN_PROGRESS, PENDING_APPROVAL, REQUIRING_ACTION, FAILED, AVAILABLE ou CANNOT_SUBMIT), com os mesmos valores de GET /locations/{locationId}/listings/premium. SYNCED e COMPLETED são considerados exatos.

Observações.

Uma varredura só é retornada para a conta que a criou. Para qualquer outro ID, o endpoint retorna 404 com SY83005.
Alguns diretórios exibem dados de outro diretório. Por exemplo, Uber, Waze e Lyft exibem dados do Google Maps, e CopilotAI exibe dados do Bing. O resultado deles reflete o diretório de origem e não tem um url de listagem próprio.
Não interprete UNAVAILABLE como um resultado negativo: não foi possível verificar o diretório, portanto a resposta é desconhecida.
Quando a varredura é uma cópia RECENT_SCAN, resultsAsOf indica quando os dados foram coletados e createdAt indica quando foram copiados para sua conta.

Request

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

Run in playground