Buat listings scan

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

Memulai pemindaian satu bisnis. Pemindaian ini mengaudit apakah bisnis tersebut tercantum dan seberapa akurat informasinya di seluruh jaringan direktori: peta dan mesin pencari seperti Google, Bing, Apple Maps, Yelp, Facebook dan MapQuest, agregator data dan direktori lokal, serta asisten AI seperti ChatGPT dan Gemini. Bergantung pada negaranya, satu pemindaian memeriksa hingga sekitar 60 direktori. Bisnis tersebut tidak harus berupa lokasi di akun Anda, sehingga Anda dapat mengaudit calon klien sebelum proses orientasi.

Panggilan ini langsung mengembalikan pemindaian dengan status QUEUED. Pemeriksaan direktori berjalan di latar belakang, dan hasilnya dibaca dengan GET /listings/scans/{scanId}.

Contoh penggunaan: audit profil bisnis untuk calon klien. Alat penjualan Anda mengumpulkan nama, alamat dan nomor telepon bisnis. Buat pemindaian, simpan scan.id yang dikembalikan, lalu baca pemindaian yang telah selesai dari data.scan saat peristiwa listing_scan.completed diterima. summary memberikan ringkasan (berapa banyak direktori yang menemukan bisnis tersebut, dan berapa banyak di antaranya yang memiliki informasi akurat), sedangkan results[] memberikan detail per direktori untuk ditampilkan dalam laporan.

Contoh penggunaan: pemeriksaan kondisi bisnis yang sudah Anda kelola. Pindai detail bisnis salah satu lokasi Anda sendiri. Pemindaian mengenali bisnis tersebut dan menyusun hasilnya dari profil bisnis yang sebenarnya untuk lokasi tersebut, alih-alih melakukan pencarian ulang (lihat Penggunaan ulang dan pemindaian gratis).

Cara pemindaian berakhir

Pemindaian melewati status QUEUED, IN_PROGRESS, lalu berakhir dengan status COMPLETED atau FAILED. Sebagian besar pemindaian selesai dalam 1 hingga 7 menit. Jika suatu direktori belum merespons setelah sekitar 15 menit, hasilnya ditetapkan menjadi UNAVAILABLE dan pemindaian diselesaikan dengan hasil dari direktori lainnya.

Utamakan webhook. Peristiwa listing_scan.completed dan listing_scan.failed dikirim sekali per pemindaian, dengan objek pemindaian yang sama dengan yang dikembalikan oleh GET /listings/scans/{scanId}, termasuk hasilnya. Peristiwa tersebut dikirim ke akun yang mengaktifkan webhook dan memiliki URL webhook yang terverifikasi, serta ditandatangani seperti semua peristiwa lainnya. Lihat listing_scan.completed.
Gunakan polling sebagai alternatif. Jika Anda tidak dapat menerima webhook, baca pemindaian setiap 15 detik hingga status bernilai COMPLETED atau FAILED. Polling yang lebih sering tidak memberikan manfaat dan menghabiskan kuota permintaan Anda.

Field wajib

name, street, city, countryIso dan phone selalu wajib diisi. Kewajiban mengisi 2 field bergantung pada negara:

Field	Wajib	Pengecualian
`stateIso`	Ya	Tidak wajib untuk `GB`.
`postalCode`	Ya	Tidak wajib untuk `NG` dan `AE`.

Nilai yang tidak diisi atau formatnya salah ditolak dengan SY83003, dan pesan kesalahan menyebutkan nama field tersebut. phone harus terdiri dari 6 hingga 15 digit, dan countryIso harus terdiri dari 2 huruf.

Penggunaan ulang dan pemindaian gratis

Pemindaian tidak selalu melakukan pencarian baru. Field source pada pemindaian yang dikembalikan menunjukkan sumber hasilnya:

`source`	Kapan Anda mendapatkannya
`DIRECTORY_SEARCH`	Pencarian baru di direktori. Hanya jenis ini yang menggunakan kuota bulanan Anda.
`RECENT_SCAN`	Bisnis yang sama telah dipindai oleh siapa pun dalam 7 hari terakhir, sehingga hasilnya disalin. `resultsAsOf` menunjukkan kapan data dikumpulkan. Dikembalikan dalam status `COMPLETED`.
`LOCATION_LISTINGS`	Bisnis cocok dengan salah satu lokasi Anda sendiri berdasarkan nomor telepon, kode pos dan negara. Hasilnya berasal dari profil bisnis yang sebenarnya untuk lokasi tersebut, `locationId` ditetapkan, dan setiap hasil menyertakan `syncStatus`.

Jika Anda memindai bisnis yang sama lagi dalam 7 hari, pemindaian yang sudah ada di akun Anda dikembalikan sebagai pengganti pemindaian baru, dengan reused: true pada respons. Tidak ada pemindaian baru yang dimulai dan tidak ada webhook baru yang dikirim, jadi baca pemindaian yang dikembalikan (yang mungkin masih berjalan) alih-alih menunggu peristiwa lain. Memindai kembali salah satu lokasi Anda sendiri dalam periode penggunaan ulang menghasilkan perilaku yang sama.

Kuota bulanan

Listings scans disertakan dalam paket berbayar dengan kuota bulanan yang bergantung pada paket Anda. Listings scans tidak tersedia dengan akses harian sandbox gratis. Hanya pemindaian DIRECTORY_SEARCH baru yang mengurangi kuota. Berikut ini gratis:

pemindaian ulang bisnis yang sama dalam 7 hari (reused: true),
salinan RECENT_SCAN,
pemindaian LOCATION_LISTINGS,
pemindaian yang gagal, yang tidak dihitung dalam penggunaan kuota.

Kuota direset sesuai periode penagihan akun Anda. Setiap respons create menyertakan quota dengan limit, used, remaining dan resetsAt, termasuk saat permintaan ditolak. Lihat Paket dan add-on.

Kesalahan

Permintaan create yang ditolak mengembalikan HTTP 200 dengan scan: null dan alasan penolakan di errors[], jadi periksa errors, bukan hanya kode status. Kunci hanya baca tidak dapat membuat pemindaian: ini merupakan satu-satunya kegagalan pada tingkat permintaan, berupa HTTP 400 dengan SY90016.

Kode	Arti	Tindakan yang perlu dilakukan
`SY83001`	Listings scans tidak tersedia dalam paket Anda.	Gunakan akun dengan paket berbayar. Akses harian tidak dapat digunakan untuk menjalankan pemindaian.
`SY83002`	Kuota bulanan telah habis. Pesan menyertakan batas kuota dan waktu reset, dan `quota` dikembalikan.	Tunggu hingga `quota.resetsAt`, atau hubungi kami untuk mendapatkan kuota yang lebih besar. Menggunakan kembali pemindaian terbaru tidak dikenai biaya.
`SY83003`	Ada field yang tidak diisi atau tidak valid. `contextInfo` mencantumkan nama field tersebut di `field`.	Perbaiki field tersebut dan kirim ulang.
`SY83004`	Pemindaian tidak tersedia untuk negara tersebut.	Periksa `countryIso`. Pesan mencantumkan kode yang ditolak.
`SY83010`	Pemindaian untuk sementara tidak tersedia.	Coba lagi nanti.

Daftar lengkap kode tersedia di Kode kesalahan.

Catatan.

Isi permintaan harus dibungkus dalam objek input.
Periksa errors, bukan status HTTP. Permintaan create yang ditolak mengembalikan HTTP 200.
Nomor telepon dinormalisasi sebelum pemindaian berjalan, dan dua permintaan yang hanya berbeda dalam format, penggunaan huruf besar atau kecil, atau spasi dianggap sebagai bisnis yang sama.
Satu permintaan create dihitung sebagai satu permintaan dalam batas laju Anda, berapa pun jumlah direktori yang diperiksa oleh pemindaian.
Pemindaian disimpan selama 90 hari. Setelah itu, membacanya akan mengembalikan 404 dengan SY83005.
Pemanggilan ini memerlukan kunci Write (tulis).

Respons

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.

Parameter

Body

Contoh permintaan