Listings APIListings API
로그인
POST/api/v4/listings/scans

listings scan 생성

어떤 업체든 대상으로 디렉터리 네트워크 전반의 등록 정보 현황에 대한 감사를 시작하고, 완료 웹훅을 기다릴 수 있도록 스캔을 즉시 반환합니다.

API 키가 필요합니다. 헤더 형식과 키 교체는 인증을 참고하세요.

매개변수

본문

이름유형필수설명
inputobject필수Wrapper object. The entire request body must be nested under `input`.
input.namestring필수Business name, up to 150 characters.
input.streetstring필수Street address, up to 200 characters.
input.citystring필수City, up to 100 characters.
input.stateIsostring선택State or province code, up to 50 characters. Required for every country except `GB`.
input.postalCodestring선택Postal code, up to 20 characters. Required for every country except `NG` and `AE`.
input.countryIsostring필수Two-letter ISO 3166-1 country code, for example `US`.
input.phonestring필수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.

요청 예시

바로 붙여 넣을 수 있는 본문입니다. 예시 ID와 값을 실제 값으로 바꾸세요.

Request body
{  "input": {    "name": "Franklin Barbecue",    "street": "900 E 11th St",    "city": "Austin",    "stateIso": "TX",    "postalCode": "78702",    "countryIso": "US",    "phone": "+15126531187"  }}

응답

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.
Response
{  "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.

업체 1곳의 스캔을 시작합니다. 스캔은 디렉터리 네트워크 전반에서 업체의 등록 여부와 등록 정보의 정확성을 점검합니다. 여기에는 Google, Bing, Apple Maps, Yelp, Facebook, MapQuest와 같은 지도 및 검색 엔진, 데이터 수집 서비스와 지역 디렉터리, ChatGPT와 Gemini 같은 AI 어시스턴트가 포함됩니다. 국가에 따라 스캔 1회로 최대 약 60개의 디렉터리를 확인합니다. 업체가 계정에 등록된 사업장일 필요는 없으므로, 잠재 고객이나 온보딩 전 고객의 등록 정보를 점검할 수 있습니다.

호출은 QUEUED 상태의 스캔을 즉시 반환합니다. 디렉터리 확인은 백그라운드에서 실행되며, 결과는 GET /listings/scans/{scanId}로 조회합니다.

사용 사례: 잠재 고객의 등록 정보 점검. 영업 도구에서 업체명, 주소, 전화번호를 수집합니다. 스캔을 생성하고 반환된 scan.id를 저장한 다음, listing_scan.completed 이벤트가 도착하면 data.scan에서 완료된 스캔을 조회하세요. summary는 요약 정보(업체를 찾은 디렉터리 수와 그중 정보가 정확한 디렉터리 수)를 제공하고, results[]는 보고서에 표시할 디렉터리별 세부 정보를 제공합니다.

사용 사례: 이미 관리 중인 업체의 상태 점검. 계정에 등록된 사업장 중 1곳의 업체 정보로 스캔하세요. 스캔은 해당 사업장을 인식하고 다시 검색하는 대신 해당 사업장의 실제 등록 정보를 바탕으로 결과를 구성합니다(재사용 및 무료 스캔 참조).

스캔 완료 과정

스캔은 QUEUED, IN_PROGRESS을 거친 다음 COMPLETED 또는 FAILED 상태로 종료됩니다. 대부분의 스캔은 1~7분 안에 완료됩니다. 약 15분이 지나도 디렉터리에서 응답하지 않으면 해당 디렉터리의 결과는 UNAVAILABLE로 설정되고, 나머지 결과로 스캔이 완료됩니다.

  • 웹훅을 우선 사용하세요. listing_scan.completed 및 listing_scan.failed 이벤트는 스캔당 1회 전달되며, GET /listings/scans/{scanId}가 반환하는 것과 동일한 스캔 객체를 결과와 함께 포함합니다. 이 이벤트는 다른 모든 이벤트와 마찬가지로 서명되며, 웹훅이 활성화되어 있고 검증된 웹훅 URL이 있는 계정으로 전송됩니다. listing_scan.completed를 참조하세요.
  • 대체 방법으로 폴링을 사용하세요. 웹훅을 수신할 수 없다면 status가 COMPLETED 또는 FAILED가 될 때까지 15초마다 스캔을 조회하세요. 더 자주 폴링해도 이점은 없으며 요청 허용량만 소모합니다.

필수 필드

name, street, city, countryIso, phone는 항상 필수입니다. 다음 2개 필드의 필수 여부는 국가에 따라 달라집니다.

필드필수 여부예외
stateIso예GB에서는 필수가 아닙니다.
postalCode예NG 및 AE에서는 필수가 아닙니다.

값이 누락되거나 형식이 잘못되면 SY83003로 거부되며, 오류에 해당 필드명이 표시됩니다. phone는 6~15자리 숫자여야 하며, countryIso는 영문자 2자여야 합니다.

재사용 및 무료 스캔

스캔이 항상 새 검색을 수행하는 것은 아닙니다. 반환된 스캔의 source 필드는 결과의 출처를 나타냅니다.

source반환되는 조건
DIRECTORY_SEARCH디렉터리를 새로 검색합니다. 월간 허용량을 사용하는 유형은 이 유형뿐입니다.
RECENT_SCAN지난 7일 이내에 누군가 동일한 업체를 스캔했으므로 해당 결과가 복사되었습니다. resultsAsOf는 데이터 수집 시점을 나타냅니다. 이미 COMPLETED 상태로 반환됩니다.
LOCATION_LISTINGS업체의 전화번호, 우편번호, 국가가 본인 계정에 등록된 사업장 중 1곳과 일치합니다. 결과는 해당 사업장의 실제 등록 정보에서 가져오며, locationId가 설정되고 각 결과에 syncStatus가 포함됩니다.

7일 이내에 동일한 업체를 다시 스캔하면 새 스캔 대신 계정의 기존 스캔이 반환되며, 응답에 reused: true가 포함됩니다. 새 스캔이 시작되지 않고 새 웹훅도 전송되지 않으므로, 다른 이벤트를 기다리는 대신 반환된 스캔을 조회하세요(아직 실행 중일 수 있습니다). 재사용 기간 내에 본인 계정의 사업장을 다시 스캔하는 경우에도 동일하게 동작합니다.

월간 제공량

Listings scans는 유료 요금제에 포함되며, 월간 제공량은 요금제에 따라 다릅니다. 무료 샌드박스 1일 이용권에서는 사용할 수 없습니다. 새로 실행하는 DIRECTORY_SEARCH 스캔만 제공량에서 차감됩니다. 다음은 무료입니다:

  • 7일 이내에 동일한 비즈니스를 다시 스캔하는 경우(reused: true),
  • RECENT_SCAN 사본,
  • LOCATION_LISTINGS 스캔,
  • 실패한 스캔은 제공량에서 차감되지 않습니다.

제공량은 계정의 결제 주기에 맞춰 초기화됩니다. 생성 요청이 거부된 경우를 포함하여 모든 생성 응답에는 limit, used, remaining 및 resetsAt가 담긴 quota가 포함됩니다. 요금제 및 추가 기능을 참조하세요.

오류

생성 요청이 거부되면 scan: null과 errors[]에 담긴 사유가 포함된 HTTP 200가 반환되므로, 상태 코드만 확인하지 말고 errors를 확인하세요. 읽기 전용 키로는 스캔을 생성할 수 없으며, 이것이 유일한 요청 수준의 실패로, SY90016가 포함된 HTTP 400가 반환됩니다.

코드의미조치 방법
SY83001현재 요금제에서는 Listings scans를 사용할 수 없습니다.유료 요금제를 사용하는 계정을 이용하세요. 1일 이용권으로는 스캔을 실행할 수 없습니다.
SY83002월간 제공량을 모두 사용했습니다. 메시지에는 한도와 초기화 시간이 포함되며, quota가 반환됩니다.quota.resetsAt까지 기다리거나 제공량 확대에 관해 문의하세요. 최근 스캔을 재사용하는 것은 무료입니다.
SY83003필드가 누락되었거나 유효하지 않습니다. contextInfo는 field에 해당 필드의 이름을 표시합니다.해당 필드를 수정하고 다시 전송하세요.
SY83004해당 국가에서는 스캔을 사용할 수 없습니다.countryIso를 확인하세요. 메시지에 거부된 코드가 표시됩니다.
SY83010일시적으로 스캔을 사용할 수 없습니다.나중에 다시 시도하세요.

전체 코드 목록은 오류 코드에 있습니다.

참고 사항.

  • 요청 본문은 반드시 input 객체로 감싸야 합니다.
  • HTTP 상태가 아니라 errors를 확인하세요. 생성 요청이 거부되면 HTTP 200가 반환됩니다.
  • 스캔을 실행하기 전에 전화번호를 정규화하며, 형식, 대소문자 또는 공백만 다른 두 요청은 동일한 비즈니스에 대한 요청으로 간주합니다.
  • 생성 요청은 스캔에서 확인하는 디렉터리 수에 관계없이 요청 빈도 제한에서 요청 1회로 계산됩니다.
  • 스캔은 90일 동안 보관됩니다. 그 이후에는 스캔 조회 시 SY83005가 포함된 404가 반환됩니다.
  • 이 호출에는 Write(쓰기) 키가 필요합니다.
Request
curl -X POST 'https://listingsapi.com/api/v4/listings/scans' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Franklin Barbecue",      "street": "900 E 11th St",      "city": "Austin",      "stateIso": "TX",      "postalCode": "78702",      "countryIso": "US",      "phone": "+15126531187"    }  }'
Run in playground