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

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

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

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

**TypeScript**

```typescript
// 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);
}
```

Examples: [TypeScript](/hi-in/dastavez/guides/numbers/buying-numbers.ts.md) · [Python](/hi-in/dastavez/guides/numbers/buying-numbers.py.md) · [Go](/hi-in/dastavez/guides/numbers/buying-numbers.go.md) · [PHP](/hi-in/dastavez/guides/numbers/buying-numbers.php.md) · [cURL](/hi-in/dastavez/guides/numbers/buying-numbers.curl.md)

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

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

```json
{
  "data": [
    {
      "number": "+447700900123",
      "country_code": "GB",
      "number_type": "mobile",
      "capabilities": ["sms", "voice"]
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}
```

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

ऑर्डर करने से पहले यह पुष्टि करने के लिए कि नंबर अभी भी उपलब्ध है, उसे [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number) से वापस पढ़ें। `404` का मतलब है कि वह नंबर वर्तमान में बिक्री के लिए उपलब्ध नहीं है, चाहे कैरियर ने उसे वापस ले लिया हो या हमारी अपनी इन्वेंट्री में वह रिज़र्व हो। री-चेक उसी `numbers_availability` अनुरोध दर सीमा का उपयोग करता है जो सर्च के लिए है, इसलिए हर रिज़ल्ट की बजाय केवल उस उम्मीदवार को री-चेक करें जिसे आप ऑर्डर करने वाले हैं।

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

खोज से प्राप्त नंबर को [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) में पास करें। फिर से प्रयास करने की सुरक्षा के लिए, [Idempotency](/docs/guides/idempotency) देखें।

**TypeScript**

```typescript
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);
}
```

Examples: [TypeScript](/hi-in/dastavez/guides/numbers/buying-numbers.ts.md) · [Python](/hi-in/dastavez/guides/numbers/buying-numbers.py.md) · [Go](/hi-in/dastavez/guides/numbers/buying-numbers.go.md) · [PHP](/hi-in/dastavez/guides/numbers/buying-numbers.php.md) · [MCP](/hi-in/dastavez/guides/numbers/buying-numbers.mcp.md) · [cURL](/hi-in/dastavez/guides/numbers/buying-numbers.curl.md)

अधिकांश ऑर्डर रिक्वेस्ट के भीतर ही पूरे हो जाते हैं और `201` के साथ जवाब देते हैं, नंबर पहले से आपका होता है:

```json
{
  "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` न हो जाए।

**TypeScript**

```typescript
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 ?? "");
```

Examples: [TypeScript](/hi-in/dastavez/guides/numbers/buying-numbers.ts.md) · [Python](/hi-in/dastavez/guides/numbers/buying-numbers.py.md) · [Go](/hi-in/dastavez/guides/numbers/buying-numbers.go.md) · [PHP](/hi-in/dastavez/guides/numbers/buying-numbers.php.md) · [MCP](/hi-in/dastavez/guides/numbers/buying-numbers.mcp.md) · [cURL](/hi-in/dastavez/guides/numbers/buying-numbers.curl.md)

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

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

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

**TypeScript**

```typescript
// 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");
```

Examples: [TypeScript](/hi-in/dastavez/guides/numbers/buying-numbers.ts.md) · [Python](/hi-in/dastavez/guides/numbers/buying-numbers.py.md) · [Go](/hi-in/dastavez/guides/numbers/buying-numbers.go.md) · [PHP](/hi-in/dastavez/guides/numbers/buying-numbers.php.md) · [MCP](/hi-in/dastavez/guides/numbers/buying-numbers.mcp.md) · [cURL](/hi-in/dastavez/guides/numbers/buying-numbers.curl.md)

सफल रिलीज़ बिना बॉडी के `204` के साथ जवाब देता है।

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

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

`402` [`E03000`](/docs/api/errors/E03000) के साथ, यानी वॉलेट में नंबर के लिए पर्याप्त बैलेंस नहीं है। टॉप अप करें और फिर से ऑर्डर करें। कोई ऑर्डर नहीं बनता, इसलिए कुछ भी चार्ज नहीं होता।

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

`409` [`E14000`](/docs/api/errors/E14000) के साथ, यानी जब आप चुन रहे थे तब नंबर बिक गया। फिर से सर्च करें और कोई दूसरा चुनें।

`409` [`E14001`](/docs/api/errors/E14001) के साथ, यानी आपके बहुत सारे ऑर्डर पहले से प्रोसेस में हैं। एक पूरा होने दें, फिर दोबारा ऑर्डर करें।

## अगले कदम

- [Numbers overview](/docs/guides/numbers/overview) बताता है कि किसी नंबर पर मौजूद फ़ील्ड का क्या मतलब है।
- [Numbers API reference](/docs/api/reference/create-numbers-order) हर ऑपरेशन और फ़ील्ड का दस्तावेज़ीकरण करता है।
- [Idempotency](/docs/guides/idempotency) बताता है कि कुंजियाँ फिर से प्रयास किए गए ऑर्डर को कैसे सुरक्षित बनाती हैं।

## Related resources

- [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer)
- [SMS numbers](/sms-api/features/numbers) (product)
- [Number types](/docs/guides/numbers/number-types) (docs)

[Get an implementation brief](/learn/workspace?topic=phone-numbers)