--- title: "Create a listings scan" method: POST path: "/api/v4/listings/scans" tags: ["Business Audit"] --- # Create a listings scan `POST /api/v4/listings/scans` ## Request - Base URL: `https://listingsapi.com` - URL: `https://listingsapi.com/api/v4/listings/scans` - Auth: one of: - API key in header `Authorization` - API key in header `X-RapidAPI-Key` and API key in header `X-RapidAPI-Host` - TypeScript: (a function with typed inputs; its response is checked against the schema) Starts a scan of how any business is listed across the directory network: maps and search engines, data aggregators, local directories, and AI assistants. The business does not need to be a location in your account. Returns immediately with the scan `QUEUED`, or `COMPLETED` when a recent scan of the same business is reused. Poll `GET /api/v4/listings/scans/{scanId}` every 15 seconds, or listen for the `listing_scan.completed` and `listing_scan.failed` webhook events. Only a new search uses the monthly allowance that depends on your plan. Needs a read-write API key and a paid plan. ## Request body - object - `input` CreateListingScanInput, required: Autogenerated input type of CreateListingScan - `name` string, required - `street` string, required - `city` string, required - `stateIso` string - `postalCode` string - `countryIso` string, required - `phone` string, required - `clientMutationId` string ## Response `200` Successful response - object - `data` object, required - `createListingScan` CreateListingScanPayload: Autogenerated return type of CreateListingScan - `clientMutationId` string - `errors` ConnectedAccountsMutationError[], required - `message` string - `code` string - `contextInfo` ErrorContext[] - `key` string - `value` string - `quota` ListingScanQuota: Monthly listing scan allowance of the account. - `limit` integer, required - `remaining` integer, required - `resetsAt` string, required - `used` integer, required - `reused` boolean, required - `scan` ListingScan: An audit of how a business is listed across directories. - `business` ListingScanBusiness, required: The business a listing scan was run for, as normalized when the scan was created. - `city` string, required - `countryIso` string, required - `name` string, required - `phone` string, required - `postalCode` string - `stateIso` string - `street` string, required - `completedAt` string - `createdAt` string, required - `failure` ListingScanFailure: Why a listing scan failed. - `code` string, required - `field` string - `message` string, required - `id` string, required - `locationId` string - `results` ListingScanResult[], required - `accuracy` ListingScanAccuracy: Per-detail comparison of a directory listing with the scanned business. - `address` ListingScanFieldCheck, required: Comparison of one business detail on a directory listing. - … - `name` ListingScanFieldCheck, required: Comparison of one business detail on a directory listing. - … - `phone` ListingScanFieldCheck, required: Comparison of one business detail on a directory listing. - … - `accuracySource` 'DIRECTORY_MATCH' | 'SYNC_STATUS', required: How the accuracy of a result was determined. - `accurate` boolean - `directory` ListingScanDirectory, required: A directory that is part of a listing scan. - `id` integer - `name` string, required - `url` string, required - `listing` ListingScanListing: The listing that was found on a directory. - `city` string - `country` string - `fullAddress` string - `name` string - `phones` string[], required - `postalCode` string - `state` string - `street` string - `url` string - `status` 'PENDING' | 'FOUND' | 'NOT_FOUND' | 'UNAVAILABLE', required: Outcome of checking one directory. - `syncStatus` 'SYNCED' | 'IN_PROGRESS' | 'REQUIRING_ACTION' | 'FAILED' | 'AVAILABLE' | 'COMPLETED' | 'PENDING_APPROVAL' | 'CANNOT_SUBMIT': Sync status of a location listing. A listing counts as accurate when its status is SYNCED or COMPLETED. - `resultsAsOf` string - `source` 'DIRECTORY_SEARCH' | 'RECENT_SCAN' | 'LOCATION_LISTINGS', required: Where the data of a listing scan came from. - `startedAt` string - `status` 'QUEUED' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED', required: Where a listing scan is in its lifecycle. - `summary` ListingScanSummary, required: Counts of the directory results of a listing scan. - `accurate` integer, required - `found` integer, required - `inaccurate` integer, required - `notFound` integer, required - `pending` integer, required - `total` integer, required - `unavailable` integer, required - `errors` ApiError[]: Present when the operation reported a request-level failure. Writes can also report validation nested under `data..errors` on a 200. - `message` string, required: Human-readable reason, prefixed with the `SYxxxxx` code where one applies. - `code` string: The `SYxxxxx` error code on its own, when one applies. - `contextInfo` object[]: Key/value pairs naming the field or value that failed. - `key` string - `value` string ## Other responses - `400`: Bad request: a malformed filter, an invalid enum value, or a malformed ID. The body carries an `errors` array, or a single `error` object when the request was rejected before it ran (e.g. `SY90001` on `reviewDetails` with no `interactionIds`). - `401`: Unauthorized — the API key is missing, malformed, or revoked (`SY90005`). - `403`: Forbidden — the key is valid but not permitted for this resource or operation (`SY90003`). - `429`: Rate limit exceeded. Wait `retry_after_seconds` (or the `Retry-After` header) and retry with backoff. - `500`: Server error. The body carries a single `error` object with code `INTERNAL_SERVER_ERROR`. ## Changes - **2026-11-06** `2658a20b9b66`: 1 info - endpoint added [Operation history](https://skmtc.dev/listingsapi/apis/listings-api/changes/api/v4/listings/scans/post.md) --- [API](https://skmtc.dev/listingsapi/apis/listings-api.md) - [All operations](https://skmtc.dev/listingsapi/apis/listings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/listingsapi/apis/listings-api/revisions/2658a20b9b66?raw)