Referensi

CarrierLookup Referensi API

Setiap endpoint berbagi satu kunci API dan satu saldo.

Item	Nilai
URL dasar	https://carrierlookup.online
Header autentikasi	X-API-Key: sk_your_api_key
Amplop respons	{ code, msg, data }

Harga tidak dicantumkan di sini; setiap produk ditagihkan per pemeriksaan yang berhasil. Lihat harga

Autentikasi

Gunakan kunci API yang dibuat di Pengaturan dan kirimkan bersama setiap permintaan.

Header autentikasi

X-API-Key: sk_your_api_key

Jaga kerahasiaan kunci API AndaSelalu panggil endpoint ini dari server Anda. Siapa pun yang memegang kunci dapat menghabiskan saldo Anda.

Pemeriksaan sinkron

POST/api/v1/checkPOST/api/v1/batch-check

Kirim satu nomor telepon, atau hingga 100 nomor dalam satu permintaan, dan baca hasilnya dalam respons yang sama. Tanpa polling, tanpa callback. Hasil yang tidak dapat ditentukan mengembalikan 422 dengan kode 42200 dan tidak ditagih. Permintaan multi mempertahankan urutan input, menagih setiap pengenal secara terpisah, dan memiliki waktu 300 detik untuk selesai — jika tidak, seluruh permintaan gagal dan setiap tagihan dikembalikan.

Parameter

Field	Tipe	Deskripsi
`service_type`	string	Kode produk, salah satu produk yang tercantum di bawah.
`identifier`	string	Pemeriksaan tunggal: satu nomor telepon. Server menormalkannya.
`identifiers`	string[]	Pemeriksaan multi: 1 hingga 100 nomor telepon. Respons mempertahankan urutan ini.

Produk dalam grup ini

Pencarian Operator AslicarrierTemukan operator tempat nomor awalnya dialokasikan, beserta jenis saluran dan lokasinya.Halaman produk

Pencarian Operator Asli

carriertelepon

Temukan operator tempat nomor awalnya dialokasikan, beserta jenis saluran dan lokasinya.

Pemeriksaan tunggal

POST/api/v1/check

Permintaan

curl -X POST "https://carrierlookup.online/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "identifier": "+17253100591",
    "carrier": "T-Mobile",
    "underlying_carrier": "",
    "number_type": "Fixed Line or Mobile",
    "country_code": "US",
    "region": "NV",
    "city": "LAS VEGAS"
  }
}

Field respons

Field	Tipe	Deskripsi
`carrier`	string	Operator tempat nomor awalnya dialokasikan. Bukan operator saat ini setelah porting.
`underlying_carrier`	string	Operator dasar yang dilaporkan penyedia jika berbeda dari operator yang dialokasikan; string kosong jika penyedia tidak menyediakannya.
`number_type`	string	Jenis saluran yang dilaporkan penyedia; kosong jika tidak tersedia.
`country_code`	string	Kode negara ISO asal nomor.
`region`	string	Wilayah alokasi; kosong jika penyedia tidak menyediakannya.
`city`	string	Kota alokasi; kosong jika penyedia tidak menyediakannya.

Pemeriksaan multi

POST/api/v1/batch-check

Permintaan

curl -X POST "https://carrierlookup.online/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifiers": ["+17253100591", "12345"] }'

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "carrier": "T-Mobile",
        "underlying_carrier": "",
        "number_type": "Fixed Line or Mobile",
        "country_code": "US",
        "region": "NV",
        "city": "LAS VEGAS"
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Field respons

Field	Tipe	Deskripsi
`exists`	boolean	Apakah nomor ini menghasilkan hasil. false berarti formatnya tidak valid, hasilnya tidak dapat ditentukan, atau pemeriksaan gagal; jika false, tidak ada field di bawah ini yang disertakan.
`carrier`	string	Operator tempat nomor awalnya dialokasikan. Bukan operator saat ini setelah porting.
`underlying_carrier`	string	Operator dasar yang dilaporkan penyedia jika berbeda dari operator yang dialokasikan; string kosong jika penyedia tidak menyediakannya.
`number_type`	string	Jenis saluran yang dilaporkan penyedia; kosong jika tidak tersedia.
`country_code`	string	Kode negara ISO asal nomor.
`region`	string	Wilayah alokasi; kosong jika penyedia tidak menyediakannya.
`city`	string	Kota alokasi; kosong jika penyedia tidak menyediakannya.

Pemeriksaan asinkron

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Unggah file dan langsung dapatkan ID tugas, lalu periksa ID tersebut sampai berhasil. Respons yang berhasil membawa result_url, tautan unduhan hasil. Hanya ada dua tindakan: kirim dan periksa. Lakukan polling tidak lebih sering dari sekali setiap 30 detik.

Parameter

Field	Tipe	Deskripsi
`service_type`	string	Kode produk massal, salah satu produk yang tercantum di bawah.
`country`	string	Kode ISO 3166-1 seperti `US`. Wajib untuk tugas nomor: setiap nomor harus menyertakan kode negaranya dan berasal dari negara ini (nomor yang tidak memenuhi akan dikecualikan dan tidak ditagihkan); juga menentukan perutean. Dalam multipart, field ini harus berada sebelum `file`.
`file`	file	File `.txt` atau `.csv` dengan satu pengenal per baris, hingga `max_file_bytes` (default 20MB).
`Idempotency-Key`	header	Opsional, hingga 128 karakter. Mengirim ulang kunci yang sama mengembalikan tugas asli alih-alih membuat tugas kedua.

Produk dalam grup ini

Pencarian operator globalcarrier_batchUnggah satu file berisi nomor: operator, operator dasar, jenis saluran, negara, wilayah, dan kota untuk setiap nomor — kolom yang sama dengan pencarian operator real-time.Halaman produk

Pencarian operator global

carrier_batchtelepon1.000–500.000 per tugas

Unggah satu file berisi nomor: operator, operator dasar, jenis saluran, negara, wilayah, dan kota untuk setiap nomor — kolom yang sama dengan pencarian operator real-time.

Kirim tugas

POST/api/v1/bulk-tasks

Permintaan

curl -X POST "https://carrierlookup.online/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=carrier_batch \
  -F country=US \
  -F file=@numbers.txt

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Periksa tugas

GET/api/v1/bulk-tasks/{id}

Permintaan

curl "https://carrierlookup.online/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Kolom hasil

Field	contoh:	Deskripsi
`identifier`	17253100591	Nomor yang dikirim dalam bentuk digit polos dengan kode negara, tanpa tanda plus atau spasi (mis. 17253100591).
`carrier`	T-Mobile	Operator tempat nomor awalnya dialokasikan. Bukan operator saat ini setelah porting.
`underlying_carrier`		Operator dasar yang dilaporkan penyedia jika berbeda dari operator yang dialokasikan; kosong jika penyedia tidak menyediakannya.
`number_type`	Fixed Line or Mobile	Jenis saluran yang dilaporkan penyedia, seperti Fixed Line or Mobile; kosong jika tidak tersedia.
`country_code`	US	Kode negara ISO asal nomor.
`region`	CA	Wilayah alokasi; kosong jika penyedia tidak menyediakannya.
`city`	LOS ANGELES	Kota alokasi; kosong jika penyedia tidak menyediakannya.

Saldo

GET/api/v1/balance

Baca saldo akun saat ini dalam mikro USD. Hanya-baca: tidak membuat catatan pemeriksaan dan tidak menagih apa pun.

Saldo

GET/api/v1/balance

Permintaan

curl "https://carrierlookup.online/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Konkurensi, batas waktu, dan perilaku percobaan ulang

Pencarian operator bersifat sinkron. Gunakan kode yang dikembalikan untuk memutuskan apakah akan menerima hasil atau mencoba lagi nanti.

Field	Deskripsi
`5 permintaan berjalan per pengguna`	Pemeriksaan tunggal dan multi berbagi batas ini, dan satu permintaan multi dihitung sebagai satu permintaan berapa pun jumlah nomor yang dibawanya. Selain itu, hanya satu pemeriksaan multi per akun yang berjalan pada satu waktu; pemeriksaan multi kedua ditolak sampai yang pertama selesai. Mencapai salah satu batas akan langsung mengembalikan kode 42901 tanpa tagihan, disertai header Retry-After — kirim ulang setelah permintaan yang sedang berjalan selesai.
`60 dtk tunggal, 300 dtk multi`	Melebihi batas waktu mengembalikan kode 50400 tanpa tagihan. Pemeriksaan multi yang melewati batas waktu gagal secara keseluruhan — tanpa hasil parsial, dan seluruh jumlahnya dikembalikan.
`Pemeriksaan multi menerima hingga 100 nomor`	Hasil mempertahankan urutan dan jumlah seperti yang dikirim. Satu pemeriksaan multi per akun berjalan dalam satu waktu; kirim batch berikutnya setelah batch sebelumnya kembali.

Kode error

Kode	Deskripsi
`40000`	Tipe layanan tidak didukung atau field permintaan saling bertentangan
`40001`	Body JSON tidak valid
`40002`	Nomor tidak valid
`40100`	Kunci API tidak ada atau tidak valid
`40200`	Saldo tidak mencukupi
`42200`	Nomor tidak dapat ditentukan saat ini. Tidak ada data yang dikembalikan dan permintaan tidak ditagih
`42900`	Kuota penggunaan habis, atau terlalu banyak pesanan yang belum selesai
`42901`	Kelima slot permintaan yang sedang berjalan sudah terisi, atau pemeriksaan multi sudah berjalan di akun ini; kirim setelah permintaan yang sedang berjalan selesai. Permintaan yang ditolak tidak ditagih dan menyertakan header Retry-After
`50303`	Layanan sedang mencapai kapasitas penuh; tidak ditagih. Tunggu selama detik Retry-After lalu kirim ulang permintaan yang sama
`50400`	Pemeriksaan tidak selesai dalam batas waktunya dan tidak ditagihkan; coba lagi. Batas waktu batch membuat seluruh batch gagal dan seluruh jumlah dikembalikan
`50300`	Pemeliharaan layanan pencarian