DocumentazioneEngagement Platform API
Sign inGet started
Guides
API

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.
GET
/workspaces/{workspaceId}/numbers
List all purchased numbers assigned to the workspace. This endpoint provides various filtering options, including Country, Number Type and Capabilities.
Parametri di query
limit
integer
Limits the number of results to return.
pageToken
string
The cursor that keeps track of the current position in the results.
reverse
boolean
Reverses the order in which the results are returned.
prefix
string
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.
searchTerm
string
Used to filter for numbers containing the search term.
status
string
The status of the number.
Possible values: active, inactive
type
string
The type of the number.
Possible values: local, national, tollfree, mobile, shortcode
country
string
The country of the number.
sms
string
Include the SMS capability in the search filter.
Possible values: inbound, inbound-only, outbound, outbound-only, any, none, both
voice
string
Include the Voice capability in the search filter.
Possible values: inbound, inbound-only, outbound, outbound-only, any, none, both
mms
string
Include the MMS capability in the search filter.
Possible values: inbound, inbound-only, outbound, outbound-only, any, none, both
fax
string
Include the Fax capability in the search filter.
Possible values: inbound, inbound-only, outbound, outbound-only, any, none, both
Payload della risposta
results
array of object
obbligatorio
Mostra attributi secondari
results.type
string
The type of the number.
Possible values: local, national, tollfree, mobile, shortcode
results.capabilities
object
The capabilities of the number.
Mostra attributi secondari
results.capabilities.sms
object
obbligatorio
Mostra attributi secondari
results.capabilities.sms.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.sms.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.voice
object
obbligatorio
Mostra attributi secondari
results.capabilities.voice.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.voice.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.mms
object
obbligatorio
Mostra attributi secondari
results.capabilities.mms.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.mms.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.fax
object
obbligatorio
Mostra attributi secondari
results.capabilities.fax.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.fax.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.whatsapp
object
Mostra attributi secondari
results.capabilities.whatsapp.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.whatsapp.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.number
string
The phone number in E.164 format.
results.country
string
results.monthlyRecurringPrice
object
Money combines an amount of money with its currency.
Mostra attributi secondari
results.monthlyRecurringPrice.currencyCode
string
obbligatorio
Currency as ISO 4217 code (three digits). An example would be EUR for Euro.
Possible values: EUR, USD, GBP, AUD, SGD, IDR, INR, MXN
results.monthlyRecurringPrice.amount
integer
obbligatorio
results.monthlyRecurringPrice.exponent
integer
obbligatorio
Usually a negative number to specify the exponent for decimal precision. e.g., 1540 * (10^-2) = 15.4
results.complianceRequirements
array of object
Mostra attributi secondari
results.complianceRequirements.name
string
obbligatorio
results.complianceRequirements.type
string
obbligatorio
Possible values: kycForm, useCase, whatsappVerification
results.complianceRequirements.scope
string
obbligatorio
Possible values: number-activation, sms-outbound, whatsapp
results.complianceRequirements.selector
object
Mostra attributi secondari
results.complianceRequirements.selector.scope
string
obbligatorio
results.complianceRequirements.selector.numberType
string
obbligatorio
The type of the number.
Possible values: local, national, tollfree, mobile, shortcode
results.complianceRequirements.selector.countryCode
string
obbligatorio
The country code in ISO 3166-1 alpha-2 format.
results.complianceRequirements.inventoryId
string
results.id
string
obbligatorio
The ID of the number.
results.status
string
obbligatorio
The status of the number.
Possible values: active, inactive
results.subscription
object
Describes status of Number Subscription
Mostra attributi secondari
results.subscription.status
string
The status of the accounting subscription. It can be none, active, canceling, canceled, or planned.
Possible values: none, active, inactive, canceling, canceled, planned
results.subscription.subscribedAt
string
Timestamp (UTC) when the subscription became active.
results.subscription.updatedAt
string
Timestamp (UTC) when the subscription was last updated.
results.subscription.cancelledAt
string
Timestamp (UTC) when the subscription was cancelled.
results.endpointSubscription
object
Mostra attributi secondari
results.endpointSubscription.id
string
obbligatorio
The subscription unique identifier.
results.endpointSubscription.correlationId
string
obbligatorio
The correlation links the subscription to its number. Hence, the correlationId is the numberId.
results.endpointSubscription.status
string
obbligatorio
The status of the accounting subscription. It can be none, active, canceling, canceled, or planned.
Possible values: none, active, inactive, canceling, canceled, planned
results.endpointSubscription.subscribedAt
string
The date and time when the subscription was created.
results.endpointSubscription.updatedAt
string
results.endpointSubscription.canceledAt
string
The date and time when the subscription was canceled.
results.endpointSubscription.startAt
string
The date and time when the subscription should start.
results.endpointSubscription.endAt
string
The date and time when the subscription should end.
results.configurations
object
Mostra attributi secondari
results.configurations.voice
object
Mostra attributi secondari
results.configurations.voice.inbound
object
Mostra attributi secondari
results.configurations.voice.inbound.connectorId
string
results.configurations.voice.inbound.connectorTemplateId
string
results.configurations.voice.inbound.connectorTemplateRef
string
results.configurations.voice.outbound
object
Mostra attributi secondari
results.configurations.voice.outbound.connectorId
string
results.configurations.voice.outbound.connectorTemplateId
string
results.configurations.voice.outbound.connectorTemplateRef
string
results.configurations.sms
object
Mostra attributi secondari
results.configurations.sms.inbound
object
Mostra attributi secondari
results.configurations.sms.inbound.connectorId
string
results.configurations.sms.inbound.connectorTemplateId
string
results.configurations.sms.inbound.connectorTemplateRef
string
results.configurations.sms.outbound
object
Mostra attributi secondari
results.configurations.sms.outbound.connectorId
string
results.configurations.sms.outbound.connectorTemplateId
string
results.configurations.sms.outbound.connectorTemplateRef
string
results.configurations.mms
object
Mostra attributi secondari
results.configurations.mms.inbound
object
Mostra attributi secondari
results.configurations.mms.inbound.connectorId
string
results.configurations.mms.inbound.connectorTemplateId
string
results.configurations.mms.inbound.connectorTemplateRef
string
results.configurations.mms.outbound
object
Mostra attributi secondari
results.configurations.mms.outbound.connectorId
string
results.configurations.mms.outbound.connectorTemplateId
string
results.configurations.mms.outbound.connectorTemplateRef
string
results.configurations.fax
object
Mostra attributi secondari
results.configurations.fax.inbound
object
Mostra attributi secondari
results.configurations.fax.inbound.connectorId
string
results.configurations.fax.inbound.connectorTemplateId
string
results.configurations.fax.inbound.connectorTemplateRef
string
results.configurations.fax.outbound
object
Mostra attributi secondari
results.configurations.fax.outbound.connectorId
string
results.configurations.fax.outbound.connectorTemplateId
string
results.configurations.fax.outbound.connectorTemplateRef
string
results.configurations.whatsapp
object
Mostra attributi secondari
results.configurations.whatsapp.connectorId
string
results.configurations.whatsapp.connectorTemplateId
string
results.configurations.whatsapp.connectorTemplateRef
string
results.createdAt
string
obbligatorio
Timestamp (UTC) when the number was created.
results.updatedAt
string
obbligatorio
Timestamp (UTC) when the number was last updated.
results.activatedAt
string
Timestamp (UTC) of the last time the number was activated.
results.deactivatedAt
string
Timestamp (UTC) of the last time the number was deactivated.
results.deactivatesAt
string
Timestamp (UTC) when the number will be deactivated.
results.requirements
array of object
Mostra attributi secondari
results.requirements.requirement
object
obbligatorio
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.
Mostra attributi secondari
results.requirements.requirement.name
string
obbligatorio
results.requirements.requirement.type
string
obbligatorio
Possible values: kycForm, useCase, whatsappVerification
results.requirements.requirement.scope
string
obbligatorio
Possible values: number-activation, sms-outbound, whatsapp
results.requirements.requirement.selector
object
Mostra attributi secondari
results.requirements.requirement.selector.scope
string
obbligatorio
results.requirements.requirement.selector.numberType
string
obbligatorio
The type of the number.
Possible values: local, national, tollfree, mobile, shortcode
results.requirements.requirement.selector.countryCode
string
obbligatorio
The country code in ISO 3166-1 alpha-2 format.
results.requirements.requirement.inventoryId
string
results.requirements.status
string
obbligatorio
Possible values: ok, pending, not-valid, not-found, error, no-reference
results.requirements.reference
string
obbligatorio
results.requirements.notOkSince
string
Timestamp (UTC) when the number didn't meet the requirement.
results.endpoint
object
A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.
Mostra attributi secondari
results.endpoint.id
string
obbligatorio
The ID of the endpoint.
results.endpoint.type
string
obbligatorio
The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.
Possible values: long-code-number, short-code-number, alpha-number, ip-pool, rcs-google-agent
results.endpoint.instanceId
string
obbligatorio
The unique identifier of the instance.
results.endpoint.name
string
obbligatorio
The name of the endpoint. For some cases it will be the number in international format as string.
results.endpoint.capabilities
array of object
obbligatorio
Mostra attributi secondari
results.endpoint.capabilities.name
string
obbligatorio
Possible values: sms
results.endpoint.capabilities.inbound
object
Mostra attributi secondari
results.endpoint.capabilities.inbound.status
string
obbligatorio
Possible values: active, inactive, available, unavailable
results.endpoint.capabilities.inbound.issues
array of string
results.endpoint.capabilities.outbound
object
Mostra attributi secondari
results.endpoint.capabilities.outbound.status
string
obbligatorio
Possible values: active, inactive, available, unavailable
results.endpoint.capabilities.outbound.destinationStatuses
object
Mostra attributi secondari
results.endpoint.capabilities.outbound.destinationStatuses.active
number
results.endpoint.capabilities.outbound.destinationStatuses.inactive
number
results.endpoint.capabilities.outbound.destinationStatuses.available
number
results.endpoint.capabilities.outbound.destinationStatuses.unavailable
number
results.endpoint.capabilities.outbound.supportsDestinations
boolean
Whether the number supports destinations
results.endpoint.capabilities.outbound.issues
array of string
results.endpoint.dependencies
array of object
The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.
Mostra attributi secondari
results.endpoint.dependencies.type
string
Possible values: connector
results.endpoint.dependencies.connectorId
string
obbligatorio
results.endpoint.dependencies.connectorTemplateRef
string
obbligatorio
results.endpoint.dependencies.capabilities
array of string
results.endpoint.issues
array of string
results.endpoint.provisioningStatus
string
obbligatorio
Possible values: provisioned, provisioning, deprovisioned, deprovisioning
results.endpoint.whatsApp
object
WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.
Mostra attributi secondari
results.endpoint.whatsApp.whatsAppId
string
results.endpoint.whatsApp.status
string
WhatsApp number status
Possible values: unknown, already-exists, installed, verified, not-verified, expired
results.endpoint.whatsApp.stage
string
results.endpoint.whatsApp.attempt
integer
results.endpoint.whatsApp.nextAttemptAt
string
results.endpoint.whatsApp.verificationExpiresAt
string
results.endpoint.whatsApp.requestedCodeAt
string
results.endpoint.whatsApp.createdAt
string
results.endpoint.whatsApp.updatedAt
string
results.endpoint.createdAt
string
obbligatorio
results.endpoint.updatedAt
string
obbligatorio
results.whatsApp
object
WhatsApp number pre-verification details.
Mostra attributi secondari
results.whatsApp.whatsAppId
string
results.whatsApp.status
string
WhatsApp number status
Possible values: unknown, already-exists, installed, verified, not-verified, expired
results.whatsApp.stage
string
results.whatsApp.attempt
integer
results.whatsApp.nextAttemptAt
string
results.whatsApp.verificationExpiresAt
string
results.whatsApp.requestedCodeAt
string
results.whatsApp.createdAt
string
results.whatsApp.updatedAt
string
nextPageToken
string
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.
Esempio di codice
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/numbers' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'