ग्राहक API

शुरू करें

API कुंजियाँ में एक Test कुंजी बनाएँ, उसे अपने सर्वर पर रखें, और FAIRVALID_API_KEY तथा FAIRVALID_BASE_URL सेट करें। Test कुंजियाँ आरक्षित @example.com पतों के साथ काम करती हैं। वे किसी प्रदाता को कॉल नहीं करतीं और कोई क्रेडिट उपयोग नहीं करतीं।

curl -X POST "$FAIRVALID_BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY" \
  -H "Idempotency-Key: my-import-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{"emails":["deliverable@example.com","pending@example.com"]}'

प्रोडक्शन के लिए, submit स्कोप वाली Live कुंजी बनाएँ और /api/v1/jobs या /api/v1/verifications का उपयोग करें। जॉब स्टेट और परिणाम पढ़ने के लिए read स्कोप जोड़ें।

नया जॉब HTTP 202 और एक UUID job_id लौटाता है। मेल खाता पुनःप्रयास उसी जॉब के साथ HTTP 200 लौटाता है। प्रतिक्रियाओं में version: v1, brand: FairValid और no-store हेडर शामिल होते हैं।

कुंजियाँ और खर्च सीमाएँ

सर्वर से Authorization: Bearer fv_live_… या Bearer fv_test_… भेजें। पूरे सीक्रेट केवल एक बार दिखाई देते हैं। लाइव कुंजियों में submit, read और balance स्कोप हो सकते हैं। रद्द की गई कुंजी से नए अनुरोध बंद हो जाते हैं। टेस्ट कुंजियाँ केवल अपने सिम्युलेटेड जॉब तक पहुँच सकती हैं।

लाइव कुंजी की आजीवन सीमा में पहले से काटे गए क्रेडिट और स्वीकार की गई अद्वितीय पहचानों के लिए आरक्षित क्रेडिट गिने जाते हैं। यह वर्कस्पेस में क्रेडिट नहीं जोड़ सकती। सीमा से अधिक का नया अनुरोध कोई जॉब बनाए या क्रेडिट रोके बिना HTTP 402 key_cap_reached लौटाता है। सीमा घटाने से नया काम रुक जाता है; स्वीकार किया गया काम जारी रहता है।

लाइव जॉब आपके वर्कस्पेस की सत्यापन कतार और क्रेडिट बैलेंस का उपयोग करते हैं। कुंजी स्कोप, कुंजी सीमाएँ, वर्कस्पेस एक्सेस और प्रोसेसिंग सीमाएँ फिर भी लागू होती हैं। जाँचें प्रोसेसिंग के लिए स्वीकार किए जाने पर वर्कस्पेस क्रेडिट आरक्षित किए जाते हैं; परिणामों पर डैशबोर्ड वाले ही कटौती और वापसी नियम लागू होते हैं।

परिचालन विराम के दौरान, नया लाइव सबमिशन क्रेडिट रोके बिना HTTP 503 live_verification_unavailable लौटा सकता है। बाद में उसी Idempotency-Key के साथ फिर से कोशिश करें।

जॉब्स और नतीजे

curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"
curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"

next_cursor को cursor क्वेरी पैरामीटर के रूप में भेजें। इसमें मूल फ़िल्टर और खोज शामिल होती है। फ़िल्टर हैं all, valid, invalid, catch_all, unknown, still_checking और not_checked। लाइव परिणाम और क्रेडिट स्थितियाँ डैशबोर्ड स्नैपशॉट से मेल खाती हैं। जॉब की स्थिति queued, running, paused, canceling, canceled या completed हो सकती है। टेस्ट जॉब निर्धारित completed, pending, failed या cancelled स्थितियाँ लौटाते हैं।

त्रुटियाँ और सुरक्षित पुनः प्रयास

हर जॉब सबमिशन और लाइव एकल-पता सबमिशन पर 8 से 128 अनुमत अक्षरों, अंकों, बिंदुओं, कोलन, अंडरस्कोर या हाइफ़न वाला Idempotency-Key भेजें। अनिश्चित प्रतिक्रिया मिलने पर उसी API कुंजी, idempotency कुंजी और नॉर्मलाइज़्ड बॉडी के साथ पुनःप्रयास करें। रीप्ले का दायरा API कुंजी तक सीमित है; उस क्रेडेंशियल को बदलकर फिर से सबमिट करने पर एक और रन बन सकता है। बदली हुई बॉडी के साथ idempotency कुंजी का दोबारा उपयोग करने पर HTTP 409 idempotency_conflict लौटता है। नई कुंजी का उपयोग तभी करें जब आप जानबूझकर एक नया रन चाहते हों, जिसमें क्रेडिट कट सकते हैं।

HTTP 401 का मतलब है कि कुंजी मौजूद नहीं है, रद्द कर दी गई है या उसके पास ज़रूरी स्कोप नहीं है। HTTP 422 अमान्य पतों या सूची की सीमाओं के लिए है। टेस्ट बल्क जॉब्स प्रति वर्कस्पेस प्रति घंटे 20 या 30 दिनों में 100 नए जॉब्स के बाद HTTP 429 लौटाते हैं; हूबहू वही अनुरोध दोबारा भेजने पर मूल जॉब ही लौटता है। HTTP 503 का मतलब है कि अनुरोध अस्थायी रूप से उपलब्ध नहीं है; अनिश्चित सबमिशन के बाद मिला 503 यह साबित नहीं करता कि जॉब मौजूद नहीं था, इसलिए उसी idempotency key के साथ दोबारा कोशिश करें। त्रुटियों में एक कोड, संदेश और अनुरोध ID होती है।

मुफ़्त सैंडबॉक्स

टेस्ट कुंजियाँ केवल ये पते स्वीकार करती हैं: deliverable@example.com, undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com और error@example.com। ये valid, invalid, catch-all, unknown, pending और unavailable परिणामों का सिम्युलेशन करती हैं। बल्क टेस्ट जॉब लाइव सत्यापन या क्रेडिट लेजर को छुए बिना स्टेटस, परिणाम, रद्दीकरण और रीप्ले का समर्थन करते हैं।

बल्क सैंडबॉक्स जॉब और उनके रीप्ले रिकॉर्ड 30 दिनों तक रखे जाते हैं। उस अवधि के बाद, नए टेस्ट के लिए नई idempotency key का उपयोग करें।

मूल /api/v1/verifications टेस्ट-कुंजी सिम्युलेटर अपने पुराने 2026-10-01 रिस्पॉन्स संस्करण और camelCase फ़ील्ड का उपयोग करता है। संस्करणयुक्त बल्क सिम्युलेटर के लिए /api/v1/jobs का उपयोग करें।

हस्ताक्षरित वेबहुक

मालिक और मैनेजर भूमिकाएँ job.completed और job.canceled के लिए HTTPS एंडपॉइंट कॉन्फ़िगर करती हैं। टेस्ट पिंग test.ping का उपयोग करता है। जॉब पेलोड में एक स्थायी इवेंट ID, जॉब ID, स्थिति, बिना पतों वाला सारांश, काटे गए/लौटाए गए क्रेडिट की गिनती और परिणाम URL होता है। इनमें कभी भी ईमेल पते या प्रदाता का डेटा शामिल नहीं होता।

FairValid-Webhook-Id, FairValid-Webhook-Timestamp और FairValid-Webhook-Signature पढ़ें। सिग्नेचर fv1= है, जिसके बाद fv1\n{event ID}\n{Unix timestamp}\nके रॉ बाइट्स और उसके ठीक बाद रॉ JSON बॉडी पर लोअरकेस HMAC-SHA256 हेक्स आता है। कॉन्स्टेंट-टाइम तुलना का उपयोग करें। आपकी घड़ी से पाँच मिनट से अधिक अंतर वाले टाइमस्टैम्प अस्वीकार करें और स्थायी स्टोरेज में इवेंट ID के आधार पर डुप्लिकेट हटाएँ।

10 सेकंड के भीतर कोई भी 2xx लौटाएँ। विफल या अनिश्चित डिलीवरी को उसी इवेंट ID के साथ अधिकतम आठ बार दोबारा भेजा जाता है; 30 दिनों का इतिहास देखें या मैन्युअल रूप से दोबारा डिलीवर करें। रीडायरेक्ट और निजी गंतव्य अस्वीकार किए जाते हैं। रोटेशन के बाद नए प्रयासों में नए सीक्रेट का उपयोग होता है। चल रहे प्रयासों के सिग्नेचर सत्यापित करने के लिए पिछला सीक्रेट 24 घंटे तक रखें।

चलाने योग्य उदाहरण

रिपॉज़िटरी में packages/contracts/examples/job.mjsऔर packages/contracts/examples/webhook-receiver.mjs शामिल हैं। जॉब उदाहरण को Node 22 और एक Test कुंजी के साथ चलाएँ। रिसीवर सटीक raw body बाइट्स की जाँच करता है और रोटेशन के दौरान वर्तमान व पिछले दोनों सीक्रेट सत्यापित करता है। प्रोडक्शन में उपयोग से पहले इसके आगे HTTPS लगाएँ और इसके इन-मेमोरी इवेंट-ID सेट को किसी टिकाऊ एटॉमिक स्टोर से बदलें।

FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
  node packages/contracts/examples/job.mjs