Criar um listings scan

Nome	Tipo	Obrigatório	Descrição
input	object	obrigatório	Wrapper object. The entire request body must be nested under `input`.
input.name	string	obrigatório	Business name, up to 150 characters.
input.street	string	obrigatório	Street address, up to 200 characters.
input.city	string	obrigatório	City, up to 100 characters.
input.stateIso	string	opcional	State or province code, up to 50 characters. Required for every country except `GB`.
input.postalCode	string	opcional	Postal code, up to 20 characters. Required for every country except `NG` and `AE`.
input.countryIso	string	obrigatório	Two-letter ISO 3166-1 country code, for example `US`.
input.phone	string	obrigatório	Business phone number with 6 to 15 digits. Local formats are read in the context of `countryIso`, and an international format with a leading `+` works too.

Inicia uma varredura de uma empresa. A varredura verifica se a empresa está listada na rede de diretórios e se os dados estão corretos: mapas e mecanismos de busca como Google, Bing, Apple Maps, Yelp, Facebook e MapQuest, agregadores de dados e diretórios locais, e assistentes de IA como ChatGPT e Gemini. Dependendo do país, uma varredura verifica até cerca de 60 diretórios. A empresa não precisa ser um local na sua conta, então você pode auditar um cliente em potencial, um cliente antes da integração.

A chamada retorna imediatamente com a varredura no status QUEUED. As verificações dos diretórios são executadas em segundo plano, e o resultado é consultado com GET /listings/scans/{scanId}.

Caso de uso: auditoria de listagens de um cliente em potencial. Sua ferramenta de vendas coleta o nome, o endereço e o número de telefone de uma empresa. Crie uma varredura, armazene o scan.id retornado e consulte a varredura concluída em data.scan quando o evento listing_scan.completed chegar. O summary fornece o resumo (quantos diretórios encontraram a empresa e quantos deles têm dados corretos), e results[] fornece os detalhes por diretório para exibir no relatório.

Caso de uso: verificação da situação de uma empresa que você já gerencia. Execute uma varredura com os dados da empresa de um dos seus próprios locais. A varredura reconhece a empresa e gera os resultados a partir das listagens reais desse local, em vez de fazer uma nova busca (consulte Reutilização e varreduras gratuitas).

Como uma varredura é finalizada

Uma varredura passa por QUEUED, IN_PROGRESS e termina como COMPLETED ou FAILED. A maioria das varreduras é concluída em 1 a 7 minutos. Se um diretório não responder após cerca de 15 minutos, seu resultado será definido como UNAVAILABLE e a varredura será concluída com os demais resultados.

Dê preferência ao webhook. Os eventos listing_scan.completed e listing_scan.failed são entregues uma vez por varredura, com o mesmo objeto de varredura que GET /listings/scans/{scanId} retorna, incluindo os resultados. Eles são enviados às contas que têm webhooks habilitados e uma URL de webhook verificada, com assinatura como todos os outros eventos. Consulte listing_scan.completed.
Use consultas periódicas como alternativa. Se você não puder receber webhooks, consulte a varredura a cada 15 segundos até que status seja COMPLETED ou FAILED. Consultar com mais frequência não traz nenhum benefício e consome sua cota de requisições.

Campos obrigatórios

name, street, city, countryIso e phone são sempre obrigatórios. Dois campos dependem do país:

Campo	Obrigatório	Exceções
`stateIso`	Sim	Não é obrigatório para `GB`.
`postalCode`	Sim	Não é obrigatório para `NG` e `AE`.

Um valor ausente ou malformado é rejeitado com SY83003, e o erro informa o nome do campo. phone deve ter entre 6 e 15 dígitos, e countryIso deve ter 2 letras.

Reutilização e varreduras gratuitas

Uma varredura nem sempre faz uma nova busca. O campo source da varredura retornada informa de onde vieram os resultados:

`source`	Quando você recebe esse resultado
`DIRECTORY_SEARCH`	Uma nova busca nos diretórios. Este é o único tipo que consome sua cota mensal.
`RECENT_SCAN`	Alguém executou uma varredura da mesma empresa nos últimos 7 dias, então os resultados foram copiados. `resultsAsOf` mostra quando os dados foram coletados. A varredura é retornada já com o status `COMPLETED`.
`LOCATION_LISTINGS`	A empresa corresponde a um dos seus próprios locais pelo número de telefone, código postal e país. Os resultados vêm das listagens reais desse local, `locationId` é definido e cada resultado inclui um `syncStatus`.

Se você executar outra varredura da mesma empresa dentro de 7 dias, a varredura existente na sua conta será retornada em vez de uma nova, com reused: true na resposta. Nenhuma nova varredura é iniciada e nenhum novo webhook é enviado, então consulte a varredura retornada (ela ainda pode estar em execução) em vez de esperar por outro evento. Executar outra varredura de um dos seus próprios locais dentro do período de reutilização tem o mesmo comportamento.

Cota mensal

Listings scans estão incluídos nos planos pagos com uma cota mensal que depende do seu plano. Não estão disponíveis no passe diário gratuito do sandbox. Apenas uma nova varredura DIRECTORY_SEARCH é descontada da cota. Os seguintes casos são gratuitos:

uma repetição para a mesma empresa em até 7 dias (reused: true),
uma cópia RECENT_SCAN,
uma varredura LOCATION_LISTINGS,
uma varredura que falha, que não é contabilizada.

A cota é renovada a cada período de faturamento da sua conta. Toda resposta de criação inclui quota com limit, used, remaining e resetsAt, inclusive quando a solicitação é rejeitada. Consulte Planos e complementos.

Erros

Uma solicitação de criação rejeitada retorna HTTP 200 com scan: null e o motivo em errors[], portanto, verifique errors, e não apenas o código de status. Chaves somente de leitura não podem criar varreduras: essa é a única falha no nível da solicitação, que retorna HTTP 400 com SY90016.

Código	Significado	O que fazer
`SY83001`	Listings scans não estão disponíveis no seu plano.	Use uma conta com um plano pago. Passes diários não permitem executar varreduras.
`SY83002`	A cota mensal foi esgotada. A mensagem inclui o limite e o momento da renovação da cota, e `quota` é retornado.	Aguarde até `quota.resetsAt` ou entre em contato conosco para solicitar uma cota maior. Reutilizar uma varredura recente é gratuito.
`SY83003`	Um campo está ausente ou é inválido. `contextInfo` identifica esse campo em `field`.	Corrija esse campo e reenvie.
`SY83004`	As varreduras não estão disponíveis para esse país.	Verifique `countryIso`. A mensagem identifica o código que foi recusado.
`SY83010`	As varreduras estão temporariamente indisponíveis.	Tente novamente mais tarde.

A lista completa de códigos está em Códigos de erro.

Observações.

O corpo da solicitação deve estar contido em um objeto input.
Verifique errors, não o status HTTP. Uma solicitação de criação rejeitada retorna HTTP 200.
Os números de telefone são normalizados antes da execução da varredura, e duas solicitações que diferem apenas na formatação, no uso de maiúsculas e minúsculas ou no espaçamento são consideradas referentes à mesma empresa.
Uma criação consome uma solicitação do seu limite de requisições, independentemente de quantos diretórios a varredura verifica.
Uma varredura é mantida por 90 dias. Após esse prazo, a leitura dela retorna 404 com SY83005.
Esta chamada exige uma chave Write (escrita).

Respostas

200The scan was accepted and is `QUEUED`. `reused` is `false` and `results` is empty until directories are checked. Wait for the `listing_scan.completed` webhook, or poll the scan.

Response

{  "data": {    "createListingScan": {      "reused": false,      "scan": {        "id": "TGlzdGluZ1NjYW46N2MxZTRmNTItOWEzYi00ZDY4LWIwZTEtNWYyYThjOWQzZTQ3",        "status": "QUEUED",        "source": "DIRECTORY_SEARCH",        "locationId": null,        "resultsAsOf": null,        "createdAt": "2026-11-05T07:00:41Z",        "startedAt": null,        "completedAt": null,        "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": null,        "results": []      },      "quota": {        "limit": 50,        "used": 6,        "remaining": 44,        "resetsAt": "2026-11-23T12:38:03Z"      },      "errors": []    }  }}

200The request was rejected, so **no scan was created**. The error is reported in `errors[]` on an `HTTP 200`, `scan` is `null`, and `quota` still returns the current allowance. This example is a phone number with too few digits.

{  "data": {    "createListingScan": {      "reused": false,      "scan": null,      "quota": {        "limit": 50,        "used": 5,        "remaining": 45,        "resetsAt": "2026-11-23T12:38:03Z"      },      "errors": [        {          "code": "SY83003",          "message": "SY83003: Invalid value for phone",          "contextInfo": [            {              "key": "field",              "value": "phone"            }          ]        }      ]    }  }}

400A read-only key was used on this write (`SY90016`). Use a Write key.

401Unauthenticated, missing or invalid API key.

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

Parâmetros

Corpo

Exemplo de requisição