Sign inGet Started

नंबर खरीदें और रिलीज़ करें

नंबर खरीदने के लिए दो कॉल लगती हैं: पहले किसी देश में बिक्री के लिए उपलब्ध नंबर खोजें, फिर अपनी पसंद का नंबर ऑर्डर करें। यहाँ की हर कॉल के लिए numbers स्कोप वाली API कुंजी चाहिए। किसी संगठन की पहली खरीद से पहले पहचान सत्यापन भी पूरा करना होता है।

किसी देश में खोजें

खोज हमेशा एक ही देश तक सीमित होती है, इसलिए country_code देना ज़रूरी है। खोज को और सीमित करने के लिए number_type, capabilities या राष्ट्रीय अंकों का prefix इस्तेमाल करें।

// The search is always country-scoped, so country_code is required.
const page = await bird.numbers.available.list({
  country_code: "GB",
  capabilities: ["sms", "voice"],
});
for (const candidate of page.data) {
  console.log(candidate.number, candidate.number_type);
}

वह क्षेत्रीय होस्ट इस्तेमाल करें जो आपकी कुंजी के bk_{region}_ प्रीफ़िक्स से मेल खाता हो: https://us1.platform.bird.com या https://eu1.platform.bird.com।

हर परिणाम में केवल वही जानकारी होती है जिसकी ज़रूरत आपको कोई नंबर चुनने के लिए होती है:

कोड उदाहरण
{
  "data": [
    {
      "number": "+447700900123",
      "country_code": "GB",
      "number_type": "mobile",
      "capabilities": ["sms", "voice"]
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}

हमारी अपनी इन्वेंटरी के नंबर पहले लौटाए जाते हैं और उनके पेज सामान्य तरीके से आते हैं। आख़िरी पेज पर ऐसे नंबर भी हो सकते हैं जिन्हें कोई कैरियर उसी समय बिक्री के लिए दे रहा है। इसलिए हो सकता है कि कुछ देर पहले सूची में दिखा नंबर आपके ऑर्डर करने तक बिक चुका हो।

ऑर्डर करने से पहले नंबर अभी भी उपलब्ध है या नहीं, यह पुष्टि करने के लिए उसे GET /v1/numbers/available/{number} से दोबारा पढ़ें। 404 का मतलब है कि नंबर अभी बिक्री के लिए उपलब्ध नहीं है, चाहे किसी कैरियर ने उसे वापस ले लिया हो या हमारी अपनी इन्वेंटरी में वह आरक्षित हो। यह दोबारा जाँच खोज वाली ही numbers_availability दर सीमा में गिनी जाती है। इसलिए हर परिणाम को नहीं, केवल उस नंबर को दोबारा जाँचें जिसे आप ऑर्डर करने वाले हैं।

नंबर ऑर्डर करें

खोज से मिला नंबर POST /v1/numbers/orders को भेजें। फिर से प्रयास के दौरान सुरक्षा के लिए Idempotency देखें।

const order = await bird.numbers.orders.create({ number: "+447700900201" });
// Most orders finish inside the request. One that has to wait on a carrier
// comes back without a number_id. Poll it until it is completed or failed.
if (order.status === "completed") {
  console.log("allocated as", order.number_id);
} else {
  console.log("still", order.status, "; poll", order.id);
}

ज़्यादातर ऑर्डर अनुरोध के भीतर ही पूरे हो जाते हैं और 201 लौटाते हैं, और नंबर उसी समय आपका हो चुका होता है:

कोड उदाहरण
{
  "id": "nor_01m0da22b0e39anhzyhtw3gzdg",
  "number": "+447700900123",
  "country_code": "GB",
  "number_type": "mobile",
  "status": "completed",
  "number_id": "nda_7eqywfwzxwa1za9n8wp7e1xkr8",
  "failure_reason": null,
  "completed_at": "2026-08-19T15:25:56.479320Z",
  "created_at": "2026-08-19T15:25:56.448051Z",
  "updated_at": "2026-08-19T15:25:56.479320Z"
}

इसके बाद के हर काम के लिए number_id ही हैंडल है: नंबर पढ़ना और उसे रिलीज़ करना।

जो ऑर्डर पूरा नहीं हुआ, उसे पोल करें

जिस ऑर्डर को किसी कैरियर का इंतज़ार करना पड़ता है, वह इसके बजाय 202 लौटाता है, और number_id तब भी null रहता है। जब तक status का मान completed या failed न हो जाए, उसे दोबारा पढ़ते रहें।

const order = await bird.numbers.orders.get("nor_01krdgeqcxet5s7t44vh8rt9mg");
// failure_reason says what went wrong, and only ever on a failed order.
console.log(order.status, order.failure_reason ?? "");

अंतिम स्थिति तक पहुँचने से पहले ऑर्डर charging, ordering और pending से होकर गुज़रता है। failed होने पर failure_reason सरल शब्दों में बताता है कि क्या गलत हुआ। पहले से लिया गया सेटअप शुल्क वापस नहीं किया जाता, इसलिए विफल ऑर्डर के बाद भी शुल्क लगा रह सकता है। ऐसा हो तो सपोर्ट से संपर्क करें।

नंबर रिलीज़ करें

रिलीज़ करने पर मासिक शुल्क बंद हो जाता है और नंबर आपके लिए काम करना बंद कर देता है। केवल dedicated नंबर ही रिलीज़ किया जा सकता है, और रिलीज़ किया गया नंबर तुरंत दोबारा बिक्री के लिए उपलब्ध नहीं होता।

// Releasing stops the monthly charge and the number stops working for you.
// Only a dedicated number can be released; a shared one answers E14002.
await bird.numbers.release("nda_01krdgeqcxet5s7t44vh8rt9mg");

सफल रिलीज़ बिना बॉडी के 204 लौटाती है। अगर आप नंबर को उस अवधि के अंत तक रखना चाहते हैं जिसका भुगतान आप कर चुके हैं, तो उसे रिलीज़ करने के बजाय रद्द करें: अपने फ़ोन नंबर प्रबंधित करना दोनों तरीकों को समझाता है।

जब ऑर्डर अस्वीकार हो जाए

लगभग हर विफल खरीद चार तरह की अस्वीकृतियों में से किसी एक के कारण होती है।

E03000 के साथ 402 का मतलब है कि वॉलेट में नंबर के लिए पर्याप्त राशि नहीं है। राशि जोड़ें और फिर से ऑर्डर करें। कोई ऑर्डर नहीं बनता, इसलिए कोई शुल्क नहीं लगता।

412 का मतलब है कि संगठन ने वह पहचान सत्यापन पूरा नहीं किया है जो पहली खरीद के लिए ज़रूरी है। इसे पूरा करें, फिर से प्रयास करें।

409 के साथ E14000 का मतलब है कि जब आप नंबर चुन रहे थे, तभी वह बिक गया। फिर से खोजें और कोई दूसरा नंबर चुनें।

409 के साथ E14001 का मतलब है कि आपके बहुत सारे ऑर्डर पहले से प्रक्रिया में हैं। किसी एक को पूरा होने दें, फिर दोबारा ऑर्डर करें।

अगले कदम

  • नंबरों का अवलोकन बताता है कि किसी नंबर के फ़ील्ड का क्या मतलब है।
  • नंबर API संदर्भ में हर ऑपरेशन और फ़ील्ड का विवरण है।
  • Idempotency बताता है कि कुंजियाँ फिर से प्रयास किए गए ऑर्डर को सुरक्षित कैसे बनाती हैं।

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।