ऑर्डर देना
एक ऑर्डर एक लिस्ट पर एक चेकर चलाता है। हर चेकर के लिए चरण वही हैं।
1. चेकर चुनें
GET /checkers बताता है कि आपका अकाउंट क्या ऑर्डर कर सकता है, आपकी कीमतों पर। हर चेकर का एक id होता है, जैसे whatsapp_status_detection, और वह फ़ोन नंबर, ईमेल या यूज़रनेम लेता है। देखें चेकर।
curl "https://api.talismanleads.io/v1/checkers" \
-H "Authorization: Bearer tl_live_your_key_here"2. अपनी लिस्ट भेजें
100,000 एंट्री और 4 MB तक रिक्वेस्ट में entries के रूप में भेजें। बड़ी लिस्ट के लिए POST /uploads से लिंक माँगें, उस लिंक पर PUT से फ़ाइल भेजें, फिर उसका upload_id इस्तेमाल करें। लिंक 2 घंटे तक चलता है। उस पर अपनी API कुंजी न भेजें।
- फ़ाइल
.txtहोती है जिसमें हर लाइन पर एक एंट्री हो, 200 MB और 10,000,000 एंट्री तक। - फ़ोन नंबर देश के कोड के साथ लिखें, जैसे
+14155550142। - एक फ़ाइल के फ़ोन नंबर एक देश के होने चाहिए: उनमें से कम से कम 90%। मिली-जुली लिस्ट को हर देश के लिए एक फ़ाइल में बाँटें।
- एक भी अमान्य लाइन होने पर पूरी लिस्ट अस्वीकार हो जाती है, और रिस्पॉन्स में उदाहरण दिखते हैं।
- अपलोड की गई फ़ाइल ऑर्डर के लिए 24 घंटे इंतज़ार करती है, फिर हटा दी जाती है।
- आपकी 20 फ़ाइलें या 100 MB एक साथ इंतज़ार में रह सकते हैं, चाहे आप कितनी भी API कुंजियाँ इस्तेमाल करें, और आप दिन में 500 अपलोड कर सकते हैं। जब आप इन सीमाओं से नीचे हों, तो अनुमत किसी भी साइज़ की एक फ़ाइल इनके ऊपर जा सकती है।
लिंक माँगें
curl -X POST "https://api.talismanleads.io/v1/uploads" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"file_name":"list.txt","size_bytes":1048576}'उस पर फ़ाइल भेजें
UPLOAD_URL="PASTE_upload_url_FROM_THE_ANSWER_ABOVE"
curl --upload-file list.txt "$UPLOAD_URL" \
-H "Content-Type: text/plain" \
-w "%{http_code}\n"3. कीमत देखें
POST /estimates एंट्री गिनता है और कीमत निकालता है, और कुछ भी चार्ज नहीं करता। billed_entries का मान entries से ज़्यादा हो सकता है, क्योंकि हर फ़ाइल कम से कम 2,000 के हिसाब से बिल होती है।
curl -X POST "https://api.talismanleads.io/v1/estimates" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'4. ऑर्डर दें
POST /orders आपके बैलेंस से चार्ज करता है और काम को कतार में डालता है। Idempotency-Key भेजें, ताकि रीट्राई से आपसे दो बार चार्ज न हो सके: देखें सुरक्षित रीट्राई। कीमत पक्की करने के लिए expected_charge भेजें, और अगर खर्च इससे अलग हुआ तो ऑर्डर price_changed के साथ अस्वीकार हो जाएगा। रिस्पॉन्स के लिए 5 मिनट तक का समय रखें, क्योंकि बड़ी लिस्ट पढ़ने में समय लगता है।
curl -X POST "https://api.talismanleads.io/v1/orders" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Idempotency-Key: crm-export-2026-11-05" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'5. स्टेटस देखते रहें
हर 30 सेकंड या उससे ज़्यादा के अंतर पर GET /orders/{id} को कॉल करें। बड़ी फ़ाइल पर्दे के पीछे हिस्सों में बँट जाती है, लेकिन ऑर्डर का एक ही स्टेटस और एक ही कुल होता है।
queued- शुरू होने का इंतज़ार कर रहा है।
processing- चल रहा है।
completed- पूरा हुआ, हर हिस्सा हो गया।
partially_completed- पूरा हुआ, कुछ हिस्से फ़ेल रहे। उन हिस्सों का रिफ़ंड होता है: `refunded` बताता है कि कितना वापस आया।
failed- कोई भी हिस्सा नहीं हो सका। चार्ज रिफ़ंड होता है: `refunded` बताता है कि कितना वापस आया।
और स्टेटस जोड़े जा सकते हैं, इसलिए जिस स्टेटस को आप नहीं जानते उसे अभी चल रहा मानें।
curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f" \
-H "Authorization: Bearer tl_live_your_key_here"6. नतीजा लें
GET /orders/{id}/results हर हिस्से के लिए डाउनलोड लिंक देता है, जो 15 मिनट तक मान्य रहता है। नया लिंक कभी भी दोबारा माँगें: नतीजे रखे जाते हैं। फ़ाइल आमतौर पर एक zip होती है जिसमें all.csv, एक स्प्रेडशीट और टेक्स्ट लिस्ट होती हैं, या एक अकेली CSV। कॉलम जोड़े जा सकते हैं, इसलिए उन्हें स्थान से नहीं, नाम से पढ़ें। इन लिंक पर अपनी API कुंजी न भेजें।
curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f/results" \
-H "Authorization: Bearer tl_live_your_key_here"चार्ज और रिफ़ंड
charge वह रकम है जो ऑर्डर देते समय उसकी कीमत थी, और refunded बताता है कि उसमें से कितना वापस आया। जो हिस्सा फ़ेल होता है उसका पूरा रिफ़ंड होता है, और जिस हिस्से की गिनती प्रोवाइडर ने कम की उसका अंतर लौटाया जाता है, उस न्यूनतम तक जिस पर वह हिस्सा बिल होता है। दोनों अपने आप होते हैं।
लगभग एक दिन के अंदर उसी चेकर पर वही लिस्ट, नई Idempotency-Key के साथ, नए ऑर्डर के रूप में फिर से चार्ज होती है, और नए चेक की जगह आपका पिछला नतीजा लौटा सकती है।
दूसरी जगहों से दिए गए ऑर्डर
वेबसाइट पर दिए गए आपके ऑर्डर भी सूची में आते हैं। API ऑर्डर वेबसाइट पर मेरे टास्क में API बैज के साथ दिखते हैं, और Telegram पर कुछ नहीं भेजते, जब तक आप वहाँ इसके लिए न कहें।