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"],
      "pricing": {
        "setup_price": { "amount": "0.00995", "currency_code": "USD" },
        "recurring_price": { "amount": "0.00995", "currency_code": "USD" },
        "recurring_period": { "unit": "month", "count": 1 },
        "intervals_per_charge": 12
      }
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}

हर परिणाम में एक pricing ऑब्जेक्ट भी होता है, जिसमें आपके संगठन के लिए कीमत होती है। यह कीमत टैक्स के बिना और आपकी बिलिंग मुद्रा में होती है:

  • setup_price नंबर ऑर्डर करते समय एक बार लिया जाता है। प्रकाशित शुल्क शून्य हो, तो उसका amount "0" होता है। जब कोई सेटअप शुल्क लागू नहीं होता, तब यह फ़ील्ड ख़ुद null होता है। जब भी recurring_price का मान null हो, तब भी यह फ़ील्ड ऐसा ही होता है, क्योंकि उस नंबर को ऑर्डर नहीं किया जा सकता।
  • recurring_price प्रति recurring_period की दर है।
  • intervals_per_charge बताता है कि एक शुल्क में कितने recurring_period का बिल बनता है। टैक्स से पहले आवर्ती शुल्क recurring_price को intervals_per_charge से गुणा करके निकलता है। यह शुल्क तब लिया जाता है जब नंबर आपके वर्कस्पेस को असाइन होता है, और फिर हर नवीनीकरण पर। जिस ऑर्डर को किसी कैरियर का इंतज़ार करना पड़ता है, उसमें नंबर ऑर्डर पूरा होने पर असाइन होता है। एक महीने के recurring_period और intervals_per_charge: 12 के साथ एक बार में 12 महीनों का बिल बनता है।

API संदर्भ में कीमतों के साथ एक उदाहरण परिणाम दिखाया गया है। pricing.recurring_price: null वाला खोज परिणाम कोई आवर्ती कीमत नहीं बताता। ऑर्डर करने से पहले उस देश और नंबर के प्रकार की कीमत तय कराने के लिए सेल्स से संपर्क करें।

डैशबोर्ड और API दोनों संगठन की एक ही कीमत इस्तेमाल करते हैं, जिसमें आपकी बिलिंग मुद्रा में रूपांतरण भी शामिल है। कीमत पढ़ने से कोटेशन तय नहीं होता: बाद के किसी शुल्क से पहले टैरिफ़ या विनिमय दर बदलने पर उसकी राशि बदल सकती है। अगर कीमत नहीं मिल पाती, तो खोज E14009 के साथ 503 लौटाती है। एक्सपोनेंशियल बैकऑफ़ के साथ कीमत को फिर से पढ़ने का प्रयास करें। कीमत न मिल पाने का मतलब कभी यह नहीं होता कि नंबर की कोई कीमत नहीं है।

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

ऑर्डर करने से पहले नंबर अभी भी उपलब्ध है या नहीं, यह पुष्टि करने के लिए उसे 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 recurring 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 बताता है कि कुंजियाँ फिर से प्रयास किए गए ऑर्डर को सुरक्षित कैसे बनाती हैं।

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