# Search Available Numbers

Search available numbers in stock that you can buy to set up an SMS, Voice, or WhatsApp channel. You can filter by country, prefix, number type, and number capabilities.

You can search available numbers using one of the following attributes:

* countryCode: 2-digit ISO code of the country, example: US for the United States, we follow the ISO 3166-1 standard.
* types: types of numbers you are searching for. Check the API spec for allowed values.
* features: the capabilities of the number (sms, mms, voice, whatsapp). Check the API spec for allowed values.
* prefix: the area code of the number, this has to be the area code only without country code, you need to pass the country code as well as the prefix if you're looking to filter for a specific area code.

## GET /workspaces/{workspaceId}/numbers-stock-items

> List all available numbers in stock.

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage a number within a workspace.","name":"numbers"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"queryLimit":{"description":"Limits the number of results to return per page. The default value is 10 and maximum is 99. If the nextPageToken is defined on response, you can use it to get remaining numbers. To know more, refer to the pagination section.\n","in":"query","name":"limit","schema":{"default":10,"maximum":99,"minimum":1,"type":"integer"}},"queryCursor":{"description":"Pagination token that keeps of track of the current position in the list. Use it to query remaining results. If not provided, the first page is returned. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.","in":"query","name":"pageToken","schema":{"maxLength":8000,"type":"string"}},"queryCountryCodes":{"allowEmptyValue":false,"in":"query","name":"countryCodes","schema":{"description":"A 2-digit ISO 3166-1 country code array.","items":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":"array"}},"queryLongCodeNumberTypes":{"allowEmptyValue":false,"description":"The number type depending on its purpose. Local for regional use, national for countrywide use, mobile for mobile networks, or toll-free for caller-free charging.","in":"query","name":"types","schema":{"items":{"$ref":"#/components/schemas/LongCodeNumberType"},"type":"array"}},"queryNumberFeatures":{"allowEmptyValue":false,"description":"The number capabilities, which can be voice, SMS, and MMS for inbound, outbound, or two-way communication, plus WhatsApp.","in":"query","name":"features","schema":{"items":{"$ref":"#/components/schemas/NumberFilterFeature"},"minItems":1,"type":"array"}},"queryNumberPrefix":{"description":"Used to filter numbers by area code. Accepts either bare area code digits (e.g. `205` for Alabama) or a full E.164 prefix (e.g. `+1205`). Partial prefixes are supported for autocomplete use cases (e.g. `+120` matches all numbers in area codes 202, 203, 205, 206, 207, 208, 209). Must be used together with the `countryCodes` filter.","in":"query","name":"prefix","schema":{"maxLength":250,"minLength":1,"type":"string"}},"queryTesting":{"in":"query","name":"testing","schema":{"type":"boolean"}}},"schemas":{"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"LongCodeNumberType":{"type":"string","description":"The type of long code number.","enum":["local","national","toll-free","mobile"]},"NumberFilterFeature":{"type":"string","enum":["voice-outbound","voice-inbound","sms-outbound","sms-inbound","mms-outbound","mms-inbound","whatsapp"]},"NumberStockItem":{"type":"object","required":["id","countryCode","type","numberString","capabilities","monthlyPrice"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the stock item."},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":{"$ref":"#/components/schemas/LongCodeNumberType"},"numberString":{"type":"string"},"capabilities":{"$ref":"#/components/schemas/PhoneNumberCapabilities"},"monthlyPrice":{"$ref":"#/components/schemas/Money"},"backOrderRequired":{"type":"boolean","description":"Whether back order is required for this item, available but it is not in the local inventory"},"backOrderStockId":{"type":"string","description":"The stock id of the back order item, to be used when creating back order","nullable":true}}},"PhoneNumberCapabilities":{"type":"object","description":"Capabilities of the phone number. It shows if the phone number supports voice, sms and/or mms.","required":["voice","sms","mms"],"properties":{"voice":{"$ref":"#/components/schemas/PhoneNumberCapability"},"sms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"mms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"whatsapp":{"$ref":"#/components/schemas/PhoneNumberCapability"}}},"PhoneNumberCapability":{"type":"object","required":["inbound","outbound"],"properties":{"inbound":{"type":"boolean","description":"Whether the number supports inbound use cases."},"outbound":{"type":"boolean","description":"Whether the number supports outbound use cases."}}},"Money":{"type":"object","title":"Money","additionalProperties":false,"description":"Money combines an amount of money with its currency.","nullable":true,"properties":{"currencyCode":{"$ref":"#/components/schemas/Currency"},"amount":{"$ref":"#/components/schemas/Amount"},"exponent":{"$ref":"#/components/schemas/Exponent"}},"required":["currencyCode","amount","exponent"]},"Currency":{"title":"Currency Code","description":"Currency as ISO 4217 code (three digits). An example would be `EUR` for Euro.","type":"string","enum":["EUR","USD","GBP","AUD","SGD","IDR","INR","MXN"]},"Amount":{"type":"integer","format":"int64"},"Exponent":{"description":"Usually a negative number to specify the exponent for decimal precision. e.g., `1540 * (10^-2) = 15.4`","type":"integer","format":"int32","minimum":-10},"pagination":{"properties":{"nextPageToken":{"description":"The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display. To know more, refer to the pagination section.","type":"string"}},"type":"object"},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/numbers-stock-items":{"get":{"operationId":"listNumbersStockItems","summary":"List all available numbers in stock.","parameters":[{"$ref":"#/components/parameters/queryLimit"},{"$ref":"#/components/parameters/queryCursor"},{"$ref":"#/components/parameters/queryCountryCodes"},{"$ref":"#/components/parameters/queryLongCodeNumberTypes"},{"$ref":"#/components/parameters/queryNumberFeatures"},{"$ref":"#/components/parameters/queryNumberPrefix"},{"$ref":"#/components/parameters/queryTesting"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"results":{"items":{"$ref":"#/components/schemas/NumberStockItem"},"type":"array"}},"required":["results"],"type":"object"},{"$ref":"#/components/schemas/pagination"}]}}},"description":"OK"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Invalid filter"}},"tags":["numbers"]}}}}
```