Başvuru

NumDetect API başvurusu

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

Öğe	Değer
Temel URL	https://numdetect.com
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.

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

Alan	Tür	Açıklama
`service_type`	string	Toplu ürün kodu; aşağıda listelenen ürünlerden biri.
`country`	string	`US` 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.
`file`	file	Her satırda bir tanımlayıcı bulunan, en fazla `max_file_bytes` (varsayılan 20MB) boyutunda bir `.txt` veya `.csv` dosyası.
`Idempotency-Key`	header	İ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

Telefon Numarası Doğrulamanumber_validation_batchTemiz bir liste, bir sonraki kampanyanın başlangıcıdır. İncelemeye değer kayıtları bulmak için geçerlilik ve aktivasyon sinyallerini kontrol edin, ardından yapılandırılmış sonucu liste temizleme, CRM güncellemeleri ve erişim öncesi kontrollere aktarın; böylece her işlem daha net verilerle başlar.Ürün sayfası
Numara Etkinliğinumber_activity_batchBir sonraki takibin bir etkinlik sinyaliyle başlamasını sağlayın. Tüm numara listesinde yakın tarihli etkinliği bulun, uykudaki kayıtları incelemeye değer numaralardan ayırın ve sonucu yeniden etkinleştirme, segmentasyon ve erişim önceliklerini planlamak için kullanın.Ürün sayfası
Yüksek Değerli Kullanıcılarnumber_high_value_batchÖnce incelemeye değer kayıtları bulun. Hizmet, üyelik ve kampanya önceliklendirmesi için üst segment cihaz özelliklerini yakın tarihli ağ etkinliğiyle birleştirerek true/false biçiminde potansiyel yüksek değerli kullanıcı sinyali döndürür; bu bir tespit sinyalidir, gelir veya satın alma kanıtı değildir.Ürün sayfası
E-ticaret Etkinliğinumber_ecommerce_batchBir sonraki ticari kampanyaya daha odaklı bir kitleyle başlayın. Mevcut e-ticaret etkinlik sinyallerini bulun, kitle ve yeniden pazarlama segmentlerini incelemeye değer kayıtlar etrafında şekillendirin ve sınırı net tutun: sonuç bir sipariş, satın alma niyeti veya platform etkinliği kaydı değildir.Ürün sayfası
Küresel operatör sorgulamacarrier_batchBir telefon listesini yönlendirmeye hazır bağlama dönüştürün. Uluslararası kayıtlara operatör, altyapı operatörü, hat türü, ülke, bölge ve şehir ekleyin, ardından zenginleştirilmiş sonucu yönlendirme, bölgesel analiz, segmentasyon ve CRM güncellemeleri için kullanın.Ürün sayfası

Telefon Numarası Doğrulama

number_validation_batchtelefonGörev başına 500–500.000

Temiz bir liste, bir sonraki kampanyanın başlangıcıdır. İncelemeye değer kayıtları bulmak için geçerlilik ve aktivasyon sinyallerini kontrol edin, ardından yapılandırılmış sonucu liste temizleme, CRM güncellemeleri ve erişim öncesi kontrollere aktarın; böylece her işlem daha net verilerle başlar.

Görev gönder

POST/api/v1/bulk-tasks

İstek

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

Yanıt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Yanıt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Sonuç sütunları

Alan	örnek:	Açıklama
`identifier`	17253100591	Gönderilen numara; ülke koduyla birlikte, artı işareti veya boşluk olmadan yalnızca rakamlardan oluşur (ör. 17253100591) ve sonuçları bir müşteri, potansiyel müşteri veya CRM kaydıyla eşleştirmek için sabit anahtardır. Kaynak listeyi izlemek ve sonuçları toplu olarak geri yazmak için saklayın; bu alan tek başına bir numarayla iletişim kurulabileceğini kanıtlamaz.
`activated`	true	Bu kontrolün döndürdüğü aktivasyon sinyali. Erişimden önce incelemeye değer kayıtları bulmak, temizleme kuyruklarını düzenlemek ve CRM segmentasyonunu desteklemek için kullanın; bunu bir bağlantı veya teslim garantisi olarak görmek yerine onay, kaynak ve etkileşim verileriyle birleştirin. Değerler true veya false'tur.

Numara Etkinliği

number_activity_batchtelefonGörev başına 500–500.000

Bir sonraki takibin bir etkinlik sinyaliyle başlamasını sağlayın. Tüm numara listesinde yakın tarihli etkinliği bulun, uykudaki kayıtları incelemeye değer numaralardan ayırın ve sonucu yeniden etkinleştirme, segmentasyon ve erişim önceliklerini planlamak için kullanın.

Görev gönder

POST/api/v1/bulk-tasks

İstek

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

Yanıt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Yanıt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Sonuç sütunları

Alan	örnek:	Açıklama
`identifier`	17253100591	Gönderilen numara; ülke koduyla birlikte, artı işareti veya boşluk olmadan yalnızca rakamlardan oluşur (ör. 17253100591) ve etkinlik sonucunu bir listeye, müşteri veya potansiyel müşteri kaydına geri yazmak için kullanılır. Yalnızca eşleştirme ve izlenebilirlik sağlar; etkinlik zamanı, sıklığı veya etkileşim ayrıntılarını içermez.
`activated`	true	Ekiplerin inceleme önceliklerini belirlemesine, kitle etiketleri oluşturmasına ve yeniden etkinleştirme temposunu planlamasına yardımcı olabilecek mevcut bir etkinlik sinyali. Etkin gün sayısı, sıklık veya belirli bir gözlem zamanı değildir; eksik bir sinyal, birinin hiçbir zaman yanıt vermeyeceği anlamına gelmez. Değerler true veya false'tur.

Yüksek Değerli Kullanıcılar

number_high_value_batchtelefonGörev başına 500–500.000

Önce incelemeye değer kayıtları bulun. Hizmet, üyelik ve kampanya önceliklendirmesi için üst segment cihaz özelliklerini yakın tarihli ağ etkinliğiyle birleştirerek true/false biçiminde potansiyel yüksek değerli kullanıcı sinyali döndürür; bu bir tespit sinyalidir, gelir veya satın alma kanıtı değildir.

Görev gönder

POST/api/v1/bulk-tasks

İstek

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

Yanıt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Yanıt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Sonuç sütunları

Alan	örnek:	Açıklama
`identifier`	17253100591	Gönderilen numara; ülke koduyla birlikte yalnızca rakamlardan oluşur (ör. 12017200001) ve yüksek değer sinyalini yüklenen kayıtla eşleştirmek ve bir CRM veya inceleme kuyruğunda takip etmek için kullanılır. Kimlik, cihaz modeli veya diğer kişisel profil verilerini sağlamaz.
`activated`	true	Üst segment cihaz özelliklerinden ve yakın tarihli ağ etkinliğinden türetilen true/false biçiminde destekleyici bir sinyal. Üyelik, hizmet ve pazarlama ekiplerinin inceleme önceliklerini belirlemesine yardımcı olabilir; ancak gelir, varlık, satın alma kapasitesi veya gerçek harcamayı teyit etmez.

E-ticaret Etkinliği

number_ecommerce_batchtelefonGörev başına 500–500.000

Bir sonraki ticari kampanyaya daha odaklı bir kitleyle başlayın. Mevcut e-ticaret etkinlik sinyallerini bulun, kitle ve yeniden pazarlama segmentlerini incelemeye değer kayıtlar etrafında şekillendirin ve sınırı net tutun: sonuç bir sipariş, satın alma niyeti veya platform etkinliği kaydı değildir.

Görev gönder

POST/api/v1/bulk-tasks

İstek

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

Yanıt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Yanıt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Sonuç sütunları

Alan	örnek:	Açıklama
`identifier`	17253100591	Gönderilen numara; ülke koduyla birlikte, artı işareti veya boşluk olmadan yalnızca rakamlardan oluşur (ör. 17253100591) ve ticari etkinlik sinyalini müşteri, potansiyel müşteri veya kitle kayıtlarıyla ilişkilendirmek için kullanılır. Pazarlama ekiplerinin sonucu kendi onay, gezinme, sipariş ve üyelik verileriyle birleştirmesini sağlar; sipariş veya ürün bilgisi içermez.
`activated`	true	Kitle incelemesini, yeniden pazarlama listesi hazırlığını ve içerik testi planlamasını odaklayabilecek mevcut bir ticari etkinlik sinyali. Bir siparişi, işlem tutarını, satın alma niyetini veya belirli bir platform etkinliğini temsil etmez. Değerler true veya false'tur.

Küresel operatör sorgulama

carrier_batchtelefonGörev başına 500–500.000

Bir telefon listesini yönlendirmeye hazır bağlama dönüştürün. Uluslararası kayıtlara operatör, altyapı operatörü, hat türü, ülke, bölge ve şehir ekleyin, ardından zenginleştirilmiş sonucu yönlendirme, bölgesel analiz, segmentasyon ve CRM güncellemeleri için kullanın.

Görev gönder

POST/api/v1/bulk-tasks

İstek

curl -X POST "https://numdetect.com/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": 509,
    "total": 509,
    "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://numdetect.com/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": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Sonuç sütunları

Alan	örnek:	Açıklama
`identifier`	17253100591	Gönderilen numara; ülke koduyla birlikte, artı işareti veya boşluk olmadan yalnızca rakamlardan oluşur (ör. 17253100591) ve operatör, hat ve coğrafi bağlamı kaynak listeye geri yazmak için eşleştirme anahtarıdır. Yönlendirme, hizmet ve CRM ekiplerinin kontrolü izleyebilmesi, yinelenenleri ele alabilmesi ve doğru müşteri veya potansiyel müşteriyi güncelleyebilmesi için kendi kaynak sütunlarınızı bunun yanında tutun. Bir kaydı tanımlar; numaraya ulaşılabileceğini kanıtlamaz.
`carrier`	T-Mobile	Tanımlanabildiğinde müşteriye yönelik operatör adı. CRM kayıtlarını zenginleştirebilir, hizmet yönlendirmesini destekleyebilir, numara yapısını incelemeye yardımcı olabilir ve bir listenin operatörlere nasıl dağıldığını gösterebilir. Erişilebilirlik veya güncel kullanım kanıtı olarak değil, operasyonel bağlam olarak kullanın. Boş bir değer, bu kontrol için kullanılabilir bir ad dönmediği anlamına gelir; operatör olmadığını kanıtlamaz.
`underlying_carrier`		Tanımlanabildiğinde altyapı ağı operatörü; bayi, sanal operatör ve taşınmış numara bağlamlarını anlamak için kullanışlıdır. Müşteriye yönelik operatörden farklı olabilir ve bu fark, ekiplerin yönlendirme veya sahiplik sorularını araştırmasına yardımcı olabilir. Anlık bir hücresel ağ durumu veya gerçek zamanlı bir bağlantı sinyali değildir.
`number_type`	Fixed Line or Mobile	Dönen hat türü; örneğin mobile, fixed line veya tanımlanabilir başka bir kategori. Mobil ve sabit hat kayıtlarını ayırmak, hizmet yönlendirmesini planlamak, kanal uygunluğunu kontrol etmek ve kullanışlı bir CRM segmenti eklemek için kullanın. Bir bağlantı sonucu değildir; boş veya bilinmeyen bir değeri başarısızlık olarak görmek yerine inceleme için saklayın.
`country_code`	US	Uluslararası listeleri gruplamak, ülke düzeyinde yönlendirme ve iş kuralları uygulamak ve bölgesel raporlar oluşturmak için dönen ülke veya bölge kodu. Bir kişinin mevcut ülkesini, fiziksel konumunu veya uyruğunu değil, numaralandırma bağlamını tanımlar. Sınır ötesi kullanım ve sanal numara durumları kendi müşteri verilerinizle karşılaştırılarak kontrol edilmelidir.
`region`	CA	Mevcut olduğunda bölge, eyalet veya il bağlamı. Pazar kapsamı analizini, bölgesel liste gruplamasını, hizmet atamasını ve operasyon raporlamasını destekleyebilir. Anlık konumdan değil numara ve ağ bağlamından gelir; bu nedenle kullanıcının mevcut bulunduğu bölge olarak okunmamalıdır; eksik veya bölgeler arası değerler olağan iş incelemesi gerektirir.
`city`	LOS ANGELES	Mevcut olduğunda şehir düzeyinde bağlam. Bölgesel raporlamayı iyileştirebilir, liste yapısını ortaya koyabilir, yerelleştirilmiş operasyonları destekleyebilir ve eksik bir CRM alanını doldurabilir. Numara tahsisi, numara taşıma, sanal numaralar ve kaynak farklılıkları şehir düzeyindeki hassasiyeti etkileyebilir; bu nedenle önemli kararlar kullanıcının sağladığı veya mevcut iş kayıtlarıyla karşılaştırılarak kontrol edilmelidir.

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://numdetect.com/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ışı

Toplu görev gönderimleri, işlem başlamadan önce kabul edilir. Yoklamaya devam edip etmeyeceğinize veya bir hatayı ele alıp almayacağınıza karar vermek için dönen görev durumunu kullanın.

Alan	Açıklama
`Kullanıcı başına aynı anda 5 istek`	Bir görev gönderimi bir istek yuvası kullanır. Hesapta kullanılabilir yuva yoksa API, Retry-After ile birlikte 42901 döndürür; bekleyin ve dosyayı yeniden gönderin.
`Beklemek yerine yoklayın`	Görev gönderimi hemen yanıt döndürür. Görev işlenirken durumunu 30 saniyede bir defadan daha sık yoklamayın.
`Görev boyutu ürüne bağlıdır`	Her ürünün görev bölümünde gösterilen kendi minimum ve maksimum dosya boyutu vardır.

Hata kodları

Kod	Açıklama
`40000`	Desteklenmeyen hizmet türü veya çelişen istek alanları
`40001`	Geçersiz JSON gövdesi
`40002`	Geçersiz numara
`40100`	Eksik veya geçersiz API anahtarı
`40200`	Yetersiz bakiye
`42200`	Gönderilen görev mevcut hâliyle kabul edilemedi
`42900`	Bir kullanım kotası tükendi veya tamamlanmamış sipariş sayısı çok fazla
`42901`	Tüm istek yuvaları dolu; devam eden bir istek bittikten sonra gönderin. Reddedilen istek ücretlendirilmez ve bir Retry-After başlığı taşır
`50303`	Hizmet şu anda kapasitesinin sınırında; ücret alınmaz. Retry-After'da belirtilen saniye kadar bekleyin ve aynı isteği yeniden gönderin
`50400`	İstek zaman aşımı süresi içinde tamamlanmadı ve ücretlendirilmez; yeniden deneyin
`50300`	Doğrulama hizmeti bakımda