Créer un listings scan

Nom	Type	Obligatoire	Description
input	object	obligatoire	Wrapper object. The entire request body must be nested under `input`.
input.name	string	obligatoire	Business name, up to 150 characters.
input.street	string	obligatoire	Street address, up to 200 characters.
input.city	string	obligatoire	City, up to 100 characters.
input.stateIso	string	facultatif	State or province code, up to 50 characters. Required for every country except `GB`.
input.postalCode	string	facultatif	Postal code, up to 20 characters. Required for every country except `NG` and `AE`.
input.countryIso	string	obligatoire	Two-letter ISO 3166-1 country code, for example `US`.
input.phone	string	obligatoire	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.

Lance une analyse d’une entreprise. L’analyse vérifie si l’entreprise figure dans le réseau d’annuaires et si ses informations y sont exactes : services cartographiques et moteurs de recherche tels que Google, Bing, Apple Maps, Yelp, Facebook et MapQuest, agrégateurs de données et annuaires locaux, ainsi qu’assistants d’IA tels que ChatGPT et Gemini. Selon le pays, une analyse vérifie jusqu’à environ 60 annuaires. L’entreprise n’a pas besoin d’être un établissement de votre compte : vous pouvez donc auditer un prospect ou un client avant son intégration.

L’appel renvoie immédiatement l’analyse avec le statut QUEUED. Les vérifications des annuaires s’exécutent en arrière-plan, et le résultat se consulte avec GET /listings/scans/{scanId}.

Cas d’utilisation : audit des fiches d’un prospect. Votre outil commercial recueille le nom, l’adresse et le numéro de téléphone d’une entreprise. Créez une analyse, enregistrez le scan.id renvoyé et consultez l’analyse terminée via data.scan à la réception de l’événement listing_scan.completed. Le champ summary fournit la synthèse (le nombre d’annuaires dans lesquels l’entreprise a été trouvée et le nombre de ceux dont les informations sont exactes), et results[] fournit les détails par annuaire à afficher dans le rapport.

Cas d’utilisation : vérification de l’état des fiches d’une entreprise que vous gérez déjà. Lancez une analyse à partir des coordonnées de l’un de vos établissements. L’analyse le reconnaît et produit ses résultats à partir des fiches réelles de cet établissement au lieu de lancer une nouvelle recherche (voir Réutilisation et analyses gratuites).

Déroulement d’une analyse jusqu’à sa fin

Une analyse passe par les statuts QUEUED et IN_PROGRESS, puis se termine avec le statut COMPLETED ou FAILED. La plupart des analyses se terminent en 1 à 7 minutes. Si un annuaire n’a pas répondu après environ 15 minutes, son résultat est défini sur UNAVAILABLE et l’analyse se termine avec les autres résultats.

Privilégiez le webhook. Les événements listing_scan.completed et listing_scan.failed sont transmis une fois par analyse, avec le même objet d’analyse que celui renvoyé par GET /listings/scans/{scanId}, résultats inclus. Ils sont envoyés aux comptes pour lesquels les webhooks sont activés et dont l’URL de webhook est vérifiée, et sont signés comme tous les autres événements. Voir listing_scan.completed.
Utilisez l’interrogation périodique comme solution de repli. Si vous ne pouvez pas recevoir de webhooks, consultez l’analyse toutes les 15 secondes jusqu’à ce que status soit égal à COMPLETED ou FAILED. Une interrogation plus fréquente n’apporte rien et consomme votre quota de requêtes.

Champs obligatoires

name, street, city, countryIso et phone sont toujours obligatoires. Le caractère obligatoire de 2 champs dépend du pays :

Champ	Obligatoire	Exceptions
`stateIso`	Oui	Non obligatoire pour `GB`.
`postalCode`	Oui	Non obligatoire pour `NG` et `AE`.

Une valeur manquante ou mal formée est rejetée avec SY83003, et l’erreur indique le nom du champ. phone doit comporter entre 6 et 15 chiffres, et countryIso doit comporter 2 lettres.

Réutilisation et analyses gratuites

Une analyse ne correspond pas toujours à une nouvelle recherche. Le champ source de l’analyse renvoyée indique la provenance de ses résultats :

`source`	Conditions d’obtention
`DIRECTORY_SEARCH`	Une nouvelle recherche dans les annuaires. C’est le seul type d’analyse qui consomme votre quota mensuel.
`RECENT_SCAN`	La même entreprise a fait l’objet d’une analyse au cours des 7 derniers jours, quel qu’en soit l’auteur, et les résultats de cette analyse ont donc été copiés. `resultsAsOf` indique quand les données ont été recueillies. L’analyse est renvoyée avec le statut déjà défini sur `COMPLETED`.
`LOCATION_LISTINGS`	L’entreprise correspond à l’un de vos propres établissements d’après le numéro de téléphone, le code postal et le pays. Les résultats proviennent des fiches réelles de cet établissement, `locationId` est renseigné et chaque résultat inclut un `syncStatus`.

Si vous analysez de nouveau la même entreprise dans les 7 jours, l’analyse existante de votre compte est renvoyée à la place d’une nouvelle analyse, avec reused: true dans la réponse. Aucune nouvelle analyse n’est lancée et aucun nouveau webhook n’est envoyé : consultez donc l’analyse renvoyée (elle peut encore être en cours) au lieu d’attendre un autre événement. Le comportement est identique si vous analysez de nouveau l’un de vos établissements pendant la période de réutilisation.

Quota mensuel

Les Listings scans sont inclus dans les forfaits payants, avec un quota mensuel qui dépend de votre forfait. Ils ne sont pas disponibles avec un accès à la journée gratuit à l'environnement de test. Seul un nouveau scan DIRECTORY_SEARCH est décompté du quota. Les éléments suivants sont gratuits :

un nouveau scan de la même entreprise dans un délai de 7 jours (reused: true),
une copie RECENT_SCAN,
un scan LOCATION_LISTINGS,
un scan qui échoue, qui n'est pas comptabilisé.

Le quota est réinitialisé à chaque période de facturation de votre compte. Chaque réponse à une demande de création inclut quota avec limit, used, remaining et resetsAt, y compris lorsque la requête est rejetée. Consultez Forfaits et options.

Erreurs

Une demande de création rejetée renvoie une réponse HTTP 200 avec scan: null et le motif dans errors[] ; vérifiez donc errors et pas seulement le code de statut. Les clés en lecture seule ne peuvent pas créer de scans : c'est le seul échec au niveau de la requête, qui renvoie une réponse HTTP 400 avec SY90016.

Code	Signification	Action à effectuer
`SY83001`	Les Listings scans ne sont pas disponibles avec votre forfait.	Utilisez un compte disposant d'un forfait payant. Les accès à la journée ne permettent pas d'exécuter des scans.
`SY83002`	Le quota mensuel est épuisé. Le message inclut la limite et la date et l'heure de réinitialisation, et `quota` est renvoyé.	Attendez `quota.resetsAt` ou contactez-nous pour obtenir un quota supérieur. La réutilisation d'un scan récent est gratuite.
`SY83003`	Un champ est manquant ou invalide. `contextInfo` indique son nom sous `field`.	Corrigez ce champ et renvoyez la requête.
`SY83004`	Les scans ne sont pas disponibles pour ce pays.	Vérifiez `countryIso`. Le message indique le code refusé.
`SY83010`	Les scans sont temporairement indisponibles.	Réessayez plus tard.

La liste complète des codes se trouve dans Codes d'erreur.

Remarques.

Le corps de la requête doit être encapsulé dans un objet input.
Vérifiez errors, pas le statut HTTP. Une demande de création rejetée renvoie une réponse HTTP 200.
Les numéros de téléphone sont normalisés avant l'exécution du scan, et deux requêtes qui ne diffèrent que par le format, la casse ou les espaces sont considérées comme portant sur la même entreprise.
Une demande de création compte pour une requête dans votre limite de débit, quel que soit le nombre d'annuaires vérifiés par le scan.
Un scan est conservé pendant 90 jours. Passé ce délai, sa lecture renvoie 404 avec SY83005.
Cet appel nécessite une clé Write (écriture).

Réponses

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.