Phone Carrier Bulk Lookup API: Pemeriksaan massal

Cari operator, operator dasar, jenis saluran, kode negara, wilayah, dan kota yang terkait dengan setiap nomor ponsel yang dikirim. Sederhanakan pengelompokan berdasarkan operator dan penyaringan nomor virtual. Tugas ini menggunakan alur kerja batch asinkron standar.

Format input

Unggah file teks dengan satu nomor telepon per baris. Normalisasi nilai sebelum mengunggah; format E.164 direkomendasikan untuk nomor telepon.

+14155552671
+13105551234

Kirim satu negara per tugas. Nomor dinormalisasi berdasarkan negara tugas (lihat country_code di bawah); nomor dari negara lain dalam file yang sama akan ditulis ulang ke negara tersebut dan hasilnya tidak benar.

Buat tugas

POST https://api.checknumber.ai/v1/tasks

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="globalCarrier"' \
--form 'country_code="US"'

Parameter permintaan

Kolom	Wajib	Deskripsi
file	ya	File teks, satu nomor telepon per baris.
task_type	ya	globalCarrier. Tipe tugas per negara sebelumnya (usaCarrier, deCarrier, gbCarrier, …) tetap diterima dan mengarah ke produk yang sama.
country_code	tidak	Kode negara ISO-3166 alpha-2 untuk nomor dalam file (US, DE, OM, …). Dipakai untuk menormalkan nomor tanpa kode negara. Jika tidak diisi, disimpulkan dari file.

API mengembalikan ID tugas. Simpan ID ini dan gunakan untuk memeriksa status tugas.

Respons unggahan

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Periksa status tugas

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

Periksa hingga status menjadi exported. Jangan menganggap pending atau processing sebagai hasil selesai.

Respons pemrosesan

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Respons yang diekspor

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

Kolom hasil

Kolom	Deskripsi	Contoh
number	Nomor telepon dari file yang dikirim.	+14155552671
number_type	Jenis saluran yang dikembalikan untuk nomor tersebut.	mobile
country_code	country_code value returned for the input.	nilai contoh
carrier	Carrier value returned for the number.	Contoh Carrier
underlying_carrier	Carrier value returned for the number.	Contoh Carrier
region	region value returned for the input.	nilai contoh
city	Nilai kota yang dikembalikan untuk input.	nilai contoh

Penanganan file hasil

Unduh file dari result_url hanya setelah tugas diekspor. Pertahankan nama kolom yang dikembalikan saat memproses file.

Kolom respons

Kolom	Deskripsi
created_at	Waktu saat tugas dibuat.
updated_at	Waktu pembaruan status tugas terakhir.
task_id	Pengenal tugas unik.
status	pending, processing, exported, atau failed.
total	Total nilai input yang diproses.
success	Nilai yang berhasil diproses.
failure	Nilai yang gagal diproses.
result_url	URL unduhan saat tugas diekspor.
actual_amount	Jumlah akhir, jika tersedia.
estimated_amount	Jumlah perkiraan yang dikembalikan saat tugas dibuat.

Kode status

Status	Deskripsi
200	Permintaan berhasil.
202	Tugas berhasil dibuat dan biaya perkiraan diterapkan.
400	File tidak valid, jenis tugas tidak didukung, atau entri valid terlalu sedikit.
401	Kunci API tidak ada atau tidak valid.
402	Saldo akun tidak mencukupi.
403	Produk tidak tersedia untuk akun Anda (dihentikan atau hanya untuk pelanggan daftar putih); hubungi dukungan.
404	Tugas tidak ditemukan.
413	File yang diunggah terlalu besar.
500	Kesalahan server internal; coba lagi nanti.
503	Produk sementara tidak tersedia (dijeda untuk pemeliharaan); tidak ada biaya yang dikenakan, coba lagi nanti.

Catatan operasional

• Tugas berjalan secara asinkron; gunakan ID tugas untuk memeriksa status.
• Periksa batas input khusus produk sebelum mengunggah.
• Baris yang gagal dilaporkan dalam hasil ekspor dan tercermin pada penghitung tugas.
• Kolom di atas berdasarkan sample live saat ini dan dapat berubah jika skema ekspor berubah.