# List your Numbers

Get a list of all Long code numbers assigned to your workspace.

You can filter your list of numbers using any of th following attributes:

* countryCode: 2 digit ISO code of the country, example: US for United States, we follow iso3166-1 standard.
* types: types of numbers your are searching for. Check API spec for allowed values.
* capabilities: the capabilities of the number (sms, mms, voice, whatsapp). Check API spec for allowed values..
* numberString: search   numbers by their leading digits. 

## List Numbers in Workspace

> List all purchased numbers assigned to the workspace. This endpoint provides various filtering options, including Country, Number Type and Capabilities.

```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"}},"queryDirection":{"description":"Order in which to retrieve the results. By default, the orders are in ascending order date. To get the results in descending order, set this parameter to true.","in":"query","name":"reverse","schema":{"default":false,"type":"boolean"}},"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"}},"queryNumberSearchTerm":{"description":"Used to filter for numbers containing the search term.","in":"query","name":"searchTerm","schema":{"maxLength":250,"minLength":1,"type":"string"}},"queryNumberStatus":{"allowEmptyValue":true,"description":"The status of the number.","in":"query","name":"status","schema":{"$ref":"#/components/schemas/NumberStatus"}},"queryNumberInventoryType":{"allowEmptyValue":true,"description":"The type of the number.","in":"query","name":"type","schema":{"$ref":"#/components/schemas/NumberInventoryType"}},"queryNumberCountry":{"description":"The country of the number.","in":"query","name":"country","schema":{"format":"iso3166-1","type":"string"}},"queryNumberCapabilitiesSMS":{"allowEmptyValue":true,"description":"Include the SMS capability in the search filter.","in":"query","name":"sms","schema":{"$ref":"#/components/schemas/capabilityDirectionFilter"}},"queryNumberCapabilitiesVoice":{"allowEmptyValue":true,"description":"Include the Voice capability in the search filter.","in":"query","name":"voice","schema":{"$ref":"#/components/schemas/capabilityDirectionFilter"}},"queryNumberCapabilitiesMMS":{"allowEmptyValue":true,"description":"Include the MMS capability in the search filter.","in":"query","name":"mms","schema":{"$ref":"#/components/schemas/capabilityDirectionFilter"}},"queryNumberCapabilitiesFax":{"allowEmptyValue":true,"description":"Include the Fax capability in the search filter.","in":"query","name":"fax","schema":{"$ref":"#/components/schemas/capabilityDirectionFilter"}}},"schemas":{"NumberStatus":{"type":"string","description":"The status of the number.","enum":["active","inactive"]},"NumberInventoryType":{"type":"string","description":"The type of the number.","enum":["local","national","tollfree","mobile","shortcode"]},"capabilityDirectionFilter":{"enum":["inbound","inbound-only","outbound","outbound-only","any","none","both"],"type":"string"},"Number":{"type":"object","required":["id","status","createdAt","updatedAt"],"properties":{"type":{"$ref":"#/components/schemas/NumberInventoryType"},"capabilities":{"$ref":"#/components/schemas/NumberInventoryCapabilities"},"number":{"$ref":"#/components/schemas/PhoneNumber"},"country":{"type":"string","format":"iso3166-1"},"monthlyRecurringPrice":{"$ref":"#/components/schemas/Money"},"complianceRequirements":{"deprecated":true,"type":"array","items":{"$ref":"#/components/schemas/ComplianceRequirement"}},"id":{"type":"string","description":"The ID of the number.","format":"uuid"},"status":{"$ref":"#/components/schemas/NumberStatus"},"subscription":{"$ref":"#/components/schemas/NumberSubscriptionStatus"},"endpointSubscription":{"$ref":"#/components/schemas/EndpointSubscriptionDetails"},"configurations":{"$ref":"#/components/schemas/NumberConfigurations"},"createdAt":{"type":"string","description":"Timestamp (UTC) when the number was created.","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the number was last updated.","nullable":true,"format":"date-time"},"activatedAt":{"type":"string","description":"Timestamp (UTC) of the last time the number was activated.","nullable":true,"format":"date-time"},"deactivatedAt":{"type":"string","description":"Timestamp (UTC) of the last time the number was deactivated.","nullable":true,"format":"date-time"},"deactivatesAt":{"type":"string","description":"Timestamp (UTC) when the number will be deactivated.","nullable":true,"format":"date-time"},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/ComplianceRequirementStatus"}},"endpoint":{"$ref":"#/components/schemas/EndpointFragment"},"whatsApp":{"$ref":"#/components/schemas/WorkspaceWhatsAppNumber"}}},"NumberInventoryCapabilities":{"type":"object","description":"The capabilities of the number.","additionalProperties":false,"required":["sms","voice","mms","fax"],"properties":{"sms":{"$ref":"#/components/schemas/NumberInventoryCapability"},"voice":{"$ref":"#/components/schemas/NumberInventoryCapability"},"mms":{"$ref":"#/components/schemas/NumberInventoryCapability"},"fax":{"$ref":"#/components/schemas/NumberInventoryCapability"},"whatsapp":{"$ref":"#/components/schemas/NumberInventoryCapability"}}},"NumberInventoryCapability":{"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."}}},"PhoneNumber":{"type":"string","description":"The phone number in E.164 format.","minLength":1,"maxLength":30},"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},"ComplianceRequirement":{"description":"Compliance requirement for a number. It may be a KYC form, use case, or WhatsApp verification. In some cases, a destination may require multiple compliance requirements to be satisfied to be able to send traffic.","oneOf":[{"$ref":"#/components/schemas/ComplianceKYCFormRequirement"},{"$ref":"#/components/schemas/ComplianceUseCaseRequirement"},{"$ref":"#/components/schemas/ComplianceWhatsAppVerificationRequirement"}],"discriminator":{"propertyName":"type","mapping":{"kycForm":"#/components/schemas/ComplianceKYCFormRequirement","useCase":"#/components/schemas/ComplianceUseCaseRequirement","whatsappVerification":"#/components/schemas/ComplianceWhatsAppVerificationRequirement"}}},"ComplianceKYCFormRequirement":{"description":"Know Your Customer (KYC) form requirement for a number.","allOf":[{"$ref":"#/components/schemas/ComplianceBaseRequirement"},{"type":"object","required":["selector"],"properties":{"selector":{"type":"object","required":["scope","numberType","countryCode"],"properties":{"scope":{"type":"string"},"numberType":{"$ref":"#/components/schemas/NumberInventoryType"},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"}}}}}]},"ComplianceBaseRequirement":{"type":"object","required":["name","type","scope"],"properties":{"name":{"type":"string"},"type":{"$ref":"#/components/schemas/ComplianceRequirementType"},"scope":{"$ref":"#/components/schemas/ComplianceRequirementScope"}}},"ComplianceRequirementType":{"type":"string","enum":["kycForm","useCase","whatsappVerification"]},"ComplianceRequirementScope":{"type":"string","enum":["number-activation","sms-outbound","whatsapp"]},"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"ComplianceUseCaseRequirement":{"allOf":[{"$ref":"#/components/schemas/ComplianceBaseRequirement"},{"type":"object","required":["selector"],"properties":{"selector":{"type":"object","required":["numberType","countryCode","platform"],"properties":{"numberType":{"$ref":"#/components/schemas/NumberInventoryType"},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"platform":{"type":"string"}}}}}]},"ComplianceWhatsAppVerificationRequirement":{"allOf":[{"$ref":"#/components/schemas/ComplianceBaseRequirement"},{"type":"object","required":["inventoryId"],"properties":{"inventoryId":{"type":"string","format":"uuid"}}}]},"NumberSubscriptionStatus":{"type":"object","title":"NumberSubscriptionStatus","additionalProperties":false,"description":"Describes status of Number Subscription","nullable":true,"properties":{"status":{"type":"string","$ref":"#/components/schemas/AccountingSubscriptionStatus"},"subscribedAt":{"type":"string","description":"Timestamp (UTC) when the subscription became active.","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the subscription was last updated.","nullable":true,"format":"date-time"},"cancelledAt":{"type":"string","description":"Timestamp (UTC) when the subscription was cancelled.","nullable":true,"format":"date-time"}}},"AccountingSubscriptionStatus":{"type":"string","enum":["none","active","inactive","canceling","canceled","planned"],"description":"The status of the accounting subscription. It can be none, active, canceling, canceled, or planned."},"EndpointSubscriptionDetails":{"type":"object","required":["id","correlationId","status"],"properties":{"id":{"type":"string","format":"uuid","description":"The subscription unique identifier."},"correlationId":{"type":"string","format":"uuid","description":"The correlation links the subscription to its number. Hence, the correlationId is the numberId."},"status":{"$ref":"#/components/schemas/AccountingSubscriptionStatus"},"subscribedAt":{"type":"string","format":"date-time","description":"The date and time when the subscription was created."},"updatedAt":{"type":"string","format":"date-time"},"canceledAt":{"type":"string","format":"date-time","description":"The date and time when the subscription was canceled."},"startAt":{"type":"string","format":"date-time","description":"The date and time when the subscription should start."},"endAt":{"type":"string","format":"date-time","description":"The date and time when the subscription should end."}}},"NumberConfigurations":{"type":"object","additionalProperties":false,"properties":{"voice":{"$ref":"#/components/schemas/NumberConfigOptions"},"sms":{"$ref":"#/components/schemas/NumberConfigOptions"},"mms":{"$ref":"#/components/schemas/NumberConfigOptions"},"fax":{"$ref":"#/components/schemas/NumberConfigOptions"},"whatsapp":{"$ref":"#/components/schemas/ConnectorConfiguration"}}},"NumberConfigOptions":{"type":"object","additionalProperties":false,"properties":{"inbound":{"$ref":"#/components/schemas/ConnectorConfiguration"},"outbound":{"$ref":"#/components/schemas/ConnectorConfiguration"}}},"ConnectorConfiguration":{"type":"object","additionalProperties":false,"properties":{"connectorId":{"type":"string","format":"uuid"},"connectorTemplateId":{"type":"string","format":"uuid"},"connectorTemplateRef":{"type":"string","nullable":true}}},"ComplianceRequirementStatus":{"type":"object","required":["requirement","status","reference"],"description":"Compliance requirement status for a number.","properties":{"requirement":{"$ref":"#/components/schemas/ComplianceRequirement"},"status":{"$ref":"#/components/schemas/ComplianceStatus"},"reference":{"type":"string","nullable":true},"notOkSince":{"type":"string","description":"Timestamp (UTC) when the number didn't meet the requirement.","format":"date-time"}}},"ComplianceStatus":{"type":"string","enum":["ok","pending","not-valid","not-found","error","no-reference"]},"EndpointFragment":{"type":"object","description":"A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.","required":["id","type","instanceId","name","capabilities","provisioningStatus","createdAt","updatedAt"],"properties":{"id":{"$ref":"#/components/schemas/EndpointId"},"type":{"$ref":"#/components/schemas/EndpointType"},"instanceId":{"$ref":"#/components/schemas/InstanceId"},"name":{"$ref":"#/components/schemas/EndpointName"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapability"}},"dependencies":{"type":"array","description":"The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.","items":{"$ref":"#/components/schemas/EndpointDependency"}},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}},"provisioningStatus":{"$ref":"#/components/schemas/EndpointProvisioningStatus"},"whatsApp":{"description":"WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.","nullable":true,"$ref":"#/components/schemas/WorkspaceWhatsAppNumber"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"EndpointId":{"type":"string","format":"uuid","description":"The ID of the endpoint."},"EndpointType":{"type":"string","description":"The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.","enum":["long-code-number","short-code-number","alpha-number","ip-pool","rcs-google-agent"]},"InstanceId":{"type":"string","format":"uuid","description":"The unique identifier of the instance."},"EndpointName":{"type":"string","description":"The name of the endpoint. For some cases it will be the number in international format as string."},"EndpointCapability":{"type":"object","description":"The capability of the endpoint. It shows what capabilities the endpoint supports and which direction (inbound, which means receiving messages, and outbound, which means sending messages). Also, it shows the status for that capability/direction combination.","discriminator":{"propertyName":"name","mapping":{"sms":"#/components/schemas/EndpointCapabilitySMS","mms":"#/components/schemas/EndpointCapabilityMMS","voice":"#/components/schemas/EndpointCapabilityVoice","whatsapp":"#/components/schemas/EndpointCapabilityWhatsapp","email":"#/components/schemas/EndpointCapabilityEmail","rcs-google":"#/components/schemas/EndpointCapabilityRcsGoogle"}},"oneOf":[{"$ref":"#/components/schemas/EndpointCapabilitySMS"},{"$ref":"#/components/schemas/EndpointCapabilityMMS"},{"$ref":"#/components/schemas/EndpointCapabilityVoice"},{"$ref":"#/components/schemas/EndpointCapabilityWhatsapp"},{"$ref":"#/components/schemas/EndpointCapabilityEmail"},{"$ref":"#/components/schemas/EndpointCapabilityRcsGoogle"}]},"EndpointCapabilitySMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["sms"]}}}]},"EndpointCapabilityFields":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/EndpointCapabilityName"},"inbound":{"$ref":"#/components/schemas/InboundEndpointCapability"},"outbound":{"$ref":"#/components/schemas/OutboundEndpointCapability"}}},"EndpointCapabilityName":{"type":"string","enum":["voice","sms","mms","whatsapp","email","rcs-google"]},"InboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityStatus":{"type":"string","enum":["active","inactive","available","unavailable"]},"EndpointIssue":{"type":"string","description":"The issue of the endpoint. It indicates what's wrong with the endpoint and the reason why traffic is deactivated in that case.","enum":["subscription-is-not-active","setup-fee-is-not-paid","capability-is-not-supported","compliance-requirement-not-satisfied","brand-not-ready","destination-brand-not-ready","use-case-not-ready","kyc-form-grace-period-has-ended","whatsapp-not-pre-verified"]},"OutboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"destinationStatuses":{"type":"object","properties":{"active":{"type":"number"},"inactive":{"type":"number"},"available":{"type":"number"},"unavailable":{"type":"number"}}},"supportsDestinations":{"type":"boolean","description":"Whether the number supports destinations"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityMMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["mms"]}}}]},"EndpointCapabilityVoice":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["voice"]},"useCaseType":{"$ref":"#/components/schemas/EndpointVoiceUseCaseType"}}}]},"EndpointVoiceUseCaseType":{"type":"string","enum":["contact-centre"]},"EndpointCapabilityWhatsapp":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["whatsapp"]}}}]},"EndpointCapabilityEmail":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["email"]}}}]},"EndpointCapabilityRcsGoogle":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["rcs-google"]}}}]},"EndpointDependency":{"type":"object","discriminator":{"propertyName":"type","mapping":{"connector":"#/components/schemas/EndpointDependencyConnector"}},"oneOf":[{"$ref":"#/components/schemas/EndpointDependencyConnector"}]},"EndpointDependencyConnector":{"type":"object","required":["connectorId","connectorTemplateRef"],"properties":{"type":{"type":"string","enum":["connector"]},"connectorId":{"type":"string","format":"uuid"},"connectorTemplateRef":{"type":"string"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapabilityName"}}}},"EndpointProvisioningStatus":{"type":"string","enum":["provisioned","provisioning","deprovisioned","deprovisioning"]},"WorkspaceWhatsAppNumber":{"type":"object","description":"WhatsApp number pre-verification details.","properties":{"whatsAppId":{"type":"string"},"status":{"$ref":"#/components/schemas/WhatsAppNumberStatus"},"stage":{"type":"string"},"attempt":{"type":"integer"},"nextAttemptAt":{"type":"string","format":"date-time"},"verificationExpiresAt":{"type":"string","format":"date-time","nullable":true},"requestedCodeAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WhatsAppNumberStatus":{"type":"string","description":"WhatsApp number status","enum":["unknown","already-exists","installed","verified","not-verified","expired"]},"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"},"Error":{"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"}}},"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":{"get":{"operationId":"listNumbers","description":"List all purchased numbers assigned to the workspace. This endpoint provides various filtering options, including Country, Number Type and Capabilities.","parameters":[{"$ref":"#/components/parameters/queryLimit"},{"$ref":"#/components/parameters/queryCursor"},{"$ref":"#/components/parameters/queryDirection"},{"$ref":"#/components/parameters/queryNumberPrefix"},{"$ref":"#/components/parameters/queryNumberSearchTerm"},{"$ref":"#/components/parameters/queryNumberStatus"},{"$ref":"#/components/parameters/queryNumberInventoryType"},{"$ref":"#/components/parameters/queryNumberCountry"},{"$ref":"#/components/parameters/queryNumberCapabilitiesSMS"},{"$ref":"#/components/parameters/queryNumberCapabilitiesVoice"},{"$ref":"#/components/parameters/queryNumberCapabilitiesMMS"},{"$ref":"#/components/parameters/queryNumberCapabilitiesFax"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"results":{"items":{"$ref":"#/components/schemas/Number"},"type":"array"}},"required":["results"],"type":"object"},{"$ref":"#/components/schemas/pagination"}]}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Number or workspace not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Invalid filter"}},"summary":"List Numbers in Workspace","tags":["numbers"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/numbers-api/api-reference/list-your-numbers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.