CarrierLookup
Başvuru

CarrierLookup API başvurusu

Tüm uç noktalar tek bir API anahtarını ve tek bir bakiyeyi paylaşır.

ÖğeDeğer
Temel URLhttps://carrierlookup.online
Kimlik doğrulama başlığıX-API-Key: sk_your_api_key
Yanıt zarfı{ code, msg, data }

Fiyatlar burada listelenmez; her ürün başarılı kontrol başına ücretlendirilir. Fiyatlandırmayı görün

Kimlik doğrulama

Ayarlar'da oluşturulan bir API anahtarı kullanın ve bunu her istekle birlikte gönderin.

Kimlik doğrulama başlığı
X-API-Key: sk_your_api_key

API anahtarınızı gizli tutunBu uç noktayı her zaman sunucunuzdan çağırın. Anahtara sahip olan herkes bakiyenizi harcayabilir.

Senkron kontroller

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

Bir telefon numarası veya tek istekte en fazla 100 numara gönderin ve sonucu aynı yanıtta okuyun. Yoklama yok, geri çağırma yok. Belirlenemeyen bir sonuç 42200 koduyla 422 döndürür ve ücretlendirilmez. Çoklu istek girdi sırasını korur, her tanımlayıcıyı bağımsız olarak ücretlendirir ve tamamlanması için 300 saniyesi vardır — tamamlanmazsa isteğin tamamı başarısız olur ve tüm ücretler iade edilir.

Parametreler

AlanTürAçıklama
service_typestringÜrün kodu; aşağıda listelenen ürünlerden biri.
identifierstringTekli kontrol: bir telefon numarası. Sunucu bunu normalleştirir.
identifiersstring[]Çoklu kontrol: 1 ila 100 telefon numarası. Yanıt bu sırayı korur.

Bu gruptaki ürünler

Orijinal Operatör Sorgulama

carriertelefon

Bir numaranın ilk tahsis edildiği operatörü hat türü ve konumuyla birlikte bulun.

Tekli kontrol

POST/api/v1/check
İstek
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"
  }
}
Yanıt alanları
AlanTürAçıklama
carrierstringNumaranın ilk tahsis edildiği operatör. Numara taşıma sonrasındaki güncel operatör değildir.
underlying_carrierstringTahsis edilenden farklı olduğunda sağlayıcının bildirdiği alt operatör; sağlayıcı sunmadığında boş dize.
number_typestringSağlayıcının bildirdiği hat türü; mevcut olmadığında boştur.
country_codestringNumaranın ait olduğu ISO ülke kodu.
regionstringTahsis bölgesi; sağlayıcı sunmadığında boştur.
citystringTahsis şehri; sağlayıcı sunmadığında boştur.

Çoklu kontrol

POST/api/v1/batch-check
İstek
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"] }'
Yanıt
{
  "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
      }
    ]
  }
}
Yanıt alanları
AlanTürAçıklama
existsbooleanBu numaranın bir sonuç üretip üretmediği. false, biçimin geçersiz olduğu, sonucun belirlenemediği veya kontrolün başarısız olduğu anlamına gelir; false olduğunda aşağıdaki alanların hiçbiri bulunmaz.
carrierstringNumaranın ilk tahsis edildiği operatör. Numara taşıma sonrasındaki güncel operatör değildir.
underlying_carrierstringTahsis edilenden farklı olduğunda sağlayıcının bildirdiği alt operatör; sağlayıcı sunmadığında boş dize.
number_typestringSağlayıcının bildirdiği hat türü; mevcut olmadığında boştur.
country_codestringNumaranın ait olduğu ISO ülke kodu.
regionstringTahsis bölgesi; sağlayıcı sunmadığında boştur.
citystringTahsis şehri; sağlayıcı sunmadığında boştur.

Asenkron kontroller

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

Bir dosya yükleyin ve hemen bir görev kimliği alın, ardından bu kimliği başarılı olana kadar kontrol edin. Başarılı yanıt, sonuç indirme bağlantısı olan result_url alanını içerir. Yalnızca iki işlem vardır: gönder ve kontrol et. 30 saniyede bir defadan daha sık yoklama yapmayın.

Parametreler

AlanTürAçıklama
service_typestringToplu ürün kodu; aşağıda listelenen ürünlerden biri.
countrystringUS gibi bir ISO 3166-1 kodu. Numara görevleri için zorunludur: her numara ülke kodunu içermeli ve bu ülkeye ait olmalıdır (uymayan numaralar çıkarılır ve ücretlendirilmez); ayrıca yönlendirmeyi de belirler. Multipart'ta file alanından önce gelmelidir.
filefileHer satırda bir tanımlayıcı bulunan, en fazla max_file_bytes (varsayılan 20MB) boyutunda bir .txt veya .csv dosyası.
Idempotency-Keyheaderİsteğe bağlı, en fazla 128 karakter. Aynı anahtarın tekrar gönderilmesi ikinci bir görev oluşturmak yerine orijinal görevi döndürür.

Bu gruptaki ürünler

Küresel operatör sorgulama

carrier_batchtelefonGörev başına 1.000–500.000

Numaralardan oluşan bir dosyanın tamamını yükleyin: her biri için operatör, alt operatör, hat türü, ülke, bölge ve şehir — gerçek zamanlı operatör sorgulamasıyla aynı alanlar.

Görev gönder

POST/api/v1/bulk-tasks
İstek
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
Yanıt
{
  "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"
  }
}

Görevi kontrol et

GET/api/v1/bulk-tasks/{id}
İstek
curl "https://carrierlookup.online/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
Yanıt
{
  "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"
  }
}
Sonuç sütunları
Alanörnek:Açıklama
identifier17253100591Gönderilen numara; ülke koduyla birlikte, artı işareti veya boşluk olmadan yalnızca rakamlar (ör. 17253100591).
carrierT-MobileNumaranın ilk tahsis edildiği operatör. Numara taşıma sonrasındaki güncel operatör değildir.
underlying_carrierTahsis edilenden farklı olduğunda sağlayıcının bildirdiği alt operatör; sağlayıcı sunmadığında boştur.
number_typeFixed Line or MobileSağlayıcının bildirdiği hat türü, örneğin Fixed Line or Mobile; mevcut olmadığında boştur.
country_codeUSNumaranın ait olduğu ISO ülke kodu.
regionCATahsis bölgesi; sağlayıcı sunmadığında boştur.
cityLOS ANGELESTahsis şehri; sağlayıcı sunmadığında boştur.

Bakiye

GET/api/v1/balance

Mevcut hesap bakiyesini USD mikro birimi cinsinden okuyun. Salt okunurdur: kontrol kaydı oluşturmaz ve ücret almaz.

Bakiye

GET/api/v1/balance
İstek
curl "https://carrierlookup.online/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"
Yanıt
{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Eşzamanlılık, zaman aşımları ve yeniden deneme davranışı

Operatör sorgulamaları senkrondur. Sonucu kabul etmeye mi yoksa daha sonra yeniden denemeye mi karar vereceğinizi döndürülen koda göre belirleyin.

AlanAçıklama
Kullanıcı başına aynı anda 5 istekTekli ve çoklu kontroller bu sınırı paylaşır ve bir çoklu istek, kaç numara içerirse içersin tek bir istek sayılır. Buna ek olarak, hesap başına aynı anda yalnızca bir çoklu kontrol çalışır; ilki bitene kadar ikincisi reddedilir. Herhangi bir sınıra ulaşıldığında ücret alınmadan hemen 42901 kodu ve bir Retry-After başlığı döndürülür — devam eden bir istek bittiğinde yeniden gönderin.
Tekli 60 sn, çoklu 300 snSüre sınırının aşılması ücret alınmadan 50400 kodunu döndürür. Zaman aşımına uğrayan bir çoklu kontrol bütünüyle başarısız olur — kısmi sonuç verilmez ve tutarın tamamı iade edilir.
Bir çoklu kontrol en fazla 100 numara alırSonuçlar gönderim sırasını ve uzunluğunu korur. Hesap başına aynı anda bir çoklu kontrol çalışır; bir önceki grup döndükten sonra sonraki grubu gönderin.

Hata kodları

KodAçıklama
40000Desteklenmeyen hizmet türü veya çelişen istek alanları
40001Geçersiz JSON gövdesi
40002Geçersiz numara
40100Eksik veya geçersiz API anahtarı
40200Yetersiz bakiye
42200Numara şu anda belirlenemedi. Veri döndürülmez ve istek ücretlendirilmez
42900Bir kullanım kotası tükendi veya tamamlanmamış sipariş sayısı çok fazla
42901Beş eşzamanlı istek yuvasının tamamı dolu veya bu hesapta zaten bir çoklu kontrol çalışıyor; devam eden bir istek bittikten sonra gönderin. Reddedilen istek ücretlendirilmez ve bir Retry-After başlığı içerir
50303Hizmet şu anda tam kapasitede; ücret alınmaz. Retry-After saniye kadar bekleyin ve aynı isteği yeniden gönderin
50400Kontrol zaman aşımı süresi içinde tamamlanmadı ve ücretlendirilmez; yeniden deneyin. Grup zaman aşımında grubun tamamı başarısız olur ve tutarın tamamı iade edilir
50300Sorgulama hizmeti bakımda