API dokümantasyonu API v1

Kimlik doğrulama

API keys sayfasında bir anahtar oluşturun, ardından aşağıdaki yer tutucuyu kendi terminalinizde değiştirin. Örnekler yalnızca metindir; kopyalamak hiçbir şey göndermez.

# API origin: https://api.numdetect.com
export NUMDETECT_API_KEY='YOUR_API_KEY'

• Her istekle Authorization: Bearer <key> gönderin. JSON istekleri ayrıca Content-Type: application/json gerektirir. Çerez, CSRF üst bilgisi veya Origin üst bilgisi gerekmez.
• Bir anahtar ürünleri okuyabilir, tekli ve toplu kontroller çalıştırabilir, sonuçlarını okuyabilir ve bakiye geçmişinizi okuyabilir. Hesap ayarları, anahtarlar ve bakiye yüklemeleri yalnızca oturum açılmış panelde yönetilir.
• Örneğin sistem başına bir tane olmak üzere en fazla 10 anahtar oluşturabilir ve istediğinizi anında silebilirsiniz.

Anahtarları sunucu ortamınızda saklayın. Anahtarları URL'lere, ekran görüntülerine, paylaşılan günlüklere veya commit edilmiş kaynak dosyalarına koymayın.

Ürünler

Ürün kimliklerini seçmeden önce güncel kataloğu okuyun. Yanıt, satıştaki her ürünü girdi türü, fiyatlar, toplu minimum ve desteklenen ülkelerle listeler.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/products" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

single ve bulk, ürünün o kontrol türü için şu an kullanılabilir olup olmadığını belirtir. countries, tüm ülkeler için ["*"], ülke kodlarının listesi veya e-posta ürünleri için boştur. Fiyatlar kontrol başına USD micros cinsindendir.

Tekli kontrol

POST /api/v1/checks bir telefon numarası veya bir e-posta adresi ile ürün kimliklerinin listesini alır. İstek, her ürün yanıtlayana kadar bekler (yaklaşık 45 saniyeye kadar) ve tamamlanmış kontrolü döndürür.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+12025550147","products":["whatsapp","telegram"]}'

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","products":["apple_email","spotify_email"]}'

Telefon numaralarını + ülke koduyla yazın. Ülke kodu olmayan bir numara için isteğe "country": "GB" (bir ISO ülke kodu) ekleyin.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks/$CHECK_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Toplu kontrol

POST /api/v1/bulk-jobs bir dosyayı multipart form data olarak yükler. Dosya ülke başına bir listeye bölünür ve her ülke seçtiğiniz her ürün tarafından kontrol edilir.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "[email protected]" \
  -F "products=whatsapp,telegram" \
  -F "input_kind=phone" \
  -F "max_cost=50000000" \
  -F "column=0" \
  -F "header=true"

• file: UTF-8 CSV veya düz metin, en fazla 100 MB ve 1.000.000 satır. Diğer sütunlar korunur ve sonuç dosyasında geri verilir.
• input_kind phone veya email olur. column, numaraların bulunduğu 0 tabanlı sütundur (varsayılan 0); header=true ilk satırı atlar.
• country (isteğe bağlı), ülke kodu olmadan yazılmış telefon numaraları için kullanılır. + veya 00 ile başlayan numaralar kendi ülkelerini korur.
• max_cost, ödemeyi kabul ettiğiniz azami tutardır, USD micros cinsindendir. İşin maliyeti daha yüksek olacaksa ya da bakiyeniz yetersizse iş reddedilir ve hiçbir şey ücretlendirilmez.

Toplu iş durumu ve sonuçları

status completed, failed veya cancelled olana kadar işi okuyun. Büyük listeler biraz zaman alabilir; bu yüzden bir iki dakikada bir sorgulayın veya webhook kullanın.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Sonuç dosyasını indirin

result_ready true olduğunda GET /result, 10 dakika geçerli bir indirme bağlantısı döndürür. Bağlantının kendisi anahtar gerektirmez. Tekrar indirmeniz gerektiğinde yeni bir bağlantı isteyin.

url=$(curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/result" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" | jq -r .url)
curl --fail --silent --show-error --output result.csv "$url"

result.csv her özgün satırı özgün sırasıyla korur ve numdetect_status (valid, duplicate veya invalid), numdetect_country ile ürün başına yes, no, unknown, unsupported, failed veya cancelled değerli bir sütun ekler.

Çalışan bir işi iptal edin

Henüz kontrol edilmemiş ülkeler durdurulur ve bunlar için bloke edilen tutar bakiyenize döner.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Webhook'lar

Bir toplu iş bittiğinde haberdar olmak için hesap ayarları sayfasında bir webhook URL'si belirleyin. Biten her iş için bir HTTPS POST göndeririz:

{
  "type": "bulk_job.finished",
  "data": {
    "id": "10000000-0000-4000-8000-000000000003",
    "status": "completed",
    "total_rows": 1000,
    "valid_rows": 982,
    "charged": 245500,
    "completed_at": "2026-11-11T08:30:00Z"
  }
}

Her istek webhook-id, webhook-timestamp ve webhook-signature üst bilgilerini taşır. İmza, v1 ve ardından imzalama gizli anahtarınızla (whsec_…, önekten sonrası Base64) "<webhook-id>.<webhook-timestamp>.<body>" değerinin Base64 HMAC-SHA256 çıktısıdır. Gövdeye güvenmeden önce karşılaştırın.

Herhangi bir 2xx durumuyla yanıtlayın. Başarısız teslimatlar birkaç dakika arayla birkaç kez yeniden denenir. Yeniden denenen bir teslimat iki kez gelebileceğinden webhook-id'yi benzersiz kabul edin.

Ücretler ve bakiye

Tekli kontrol, kesin yanıt veren her ürün için kendi fiyatı kadar ücretlendirilir. Unknown ve failed yanıtlar ücretsizdir.

Toplu iş, gönderdiğinizde maliyetini bloke eder: her ülke ve ürün için max(geçerli numaralar, ürünün toplu minimumu) × toplu fiyat. Tamamlanan liste, unknown satırlar dahil tam olarak ücretlendirilir. Başarısız olan veya iptal edilen liste bakiyenize iade edilir. Yinelenen ve geçersiz satırlar ile bir ürünün desteklemediği ülkeler ücretsizdir.

Tutarlar tam sayı USD micros cinsindendir: 1 USD = 1.000.000 micros.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/balance-logs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

POST /checks ve POST /bulk-jobs bir Idempotency-Key üst bilgisi gerektirir (en fazla 128 karakter). Her yeni istek için yeni bir anahtar kullanın. Yanıt kaybolursa aynı isteği aynı anahtarla yeniden gönderin: ikinci bir ücret yerine ilk sonucu alırsınız.

Hatalar

Hatalar {error: {code, message, request_id}} biçimini kullanır. message yerine sabit code ile eşleştirin ve destekle iletişime geçerken request_id ekleyin.

API key'inizi alınToplu kontrollerWebhook ayarlarıFaturalama