DocumentaciónEngagement Platform API
Sign inGet started
Guides
API

Buying a number through Bird

If you require a number for your customer, these are available to acquire through Bird CRM using our numbers API. Once you purchase the number this will automatically be verified on WhatsApp for use in the embedded signup flow.

Find an available number

If you do not already have a number available in your workspace you can find one to purchase
GET
/organizations/{organizationId}/numbers-stock-items
List all available numbers in stock.
Parámetros de consulta
limit
integer
Limits the number of results to return.
pageToken
string
The cursor that keeps track of the current position in the results.
countryCodes
array
types
array
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.
features
array
The number capabilities, which can be voice, SMS, and MMS for inbound, outbound, or two-way communication, plus WhatsApp.
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.
testing
boolean
Cuerpo de la respuesta
results
array of object
obligatorio
Mostrar atributos secundarios
results.id
string
obligatorio
The unique identifier of the stock item.
results.countryCode
string
obligatorio
The country code in ISO 3166-1 alpha-2 format.
results.type
string
obligatorio
The type of long code number.
Possible values: local, national, toll-free, mobile
results.numberString
string
obligatorio
results.capabilities
object
obligatorio
Capabilities of the phone number. It shows if the phone number supports voice, sms and/or mms.
Mostrar atributos secundarios
results.capabilities.voice
object
obligatorio
Mostrar atributos secundarios
results.capabilities.voice.inbound
boolean
obligatorio
Whether the number supports inbound use cases.
results.capabilities.voice.outbound
boolean
obligatorio
Whether the number supports outbound use cases.
results.capabilities.sms
object
obligatorio
Mostrar atributos secundarios
results.capabilities.sms.inbound
boolean
obligatorio
Whether the number supports inbound use cases.
results.capabilities.sms.outbound
boolean
obligatorio
Whether the number supports outbound use cases.
results.capabilities.mms
object
obligatorio
Mostrar atributos secundarios
results.capabilities.mms.inbound
boolean
obligatorio
Whether the number supports inbound use cases.
results.capabilities.mms.outbound
boolean
obligatorio
Whether the number supports outbound use cases.
results.capabilities.whatsapp
object
Mostrar atributos secundarios
results.capabilities.whatsapp.inbound
boolean
obligatorio
Whether the number supports inbound use cases.
results.capabilities.whatsapp.outbound
boolean
obligatorio
Whether the number supports outbound use cases.
results.monthlyPrice
object
obligatorio
Money combines an amount of money with its currency.
Mostrar atributos secundarios
results.monthlyPrice.currencyCode
string
obligatorio
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.monthlyPrice.amount
integer
obligatorio
results.monthlyPrice.exponent
integer
obligatorio
Usually a negative number to specify the exponent for decimal precision. e.g., 1540 * (10^-2) = 15.4
results.backOrderRequired
boolean
Whether back order is required for this item, available but it is not in the local inventory
results.backOrderStockId
string
The stock id of the back order item, to be used when creating back order
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.
Ejemplo de código
curl -X GET 'https://api.bird.com/organizations/{organizationId}/numbers-stock-items' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Purchase a number

Once you have found an available number, you can purchase it by providing the number (using the unique identifier provided by the endpoint above).
POST
/workspaces/{workspaceId}/numbers-long-code
Assigns Long Code Numbers to the current workspace, charging the wallet for their subscription price. When creating LCNs as a User, all specified Number Stock Items should be reserved.
Cuerpo de la solicitud
numberStockItemIds
array of string
obligatorio
The unique identifiers of the numbers you want to buy. You can buy up to 25 numbers at a time. This operation will incur wallet charges for the numbers. Before buying the number, you must reserve it.
Cuerpo de la respuesta
results
array of object
obligatorio
Mostrar atributos secundarios
results.id
string
obligatorio
The unique identifier of the long code number. The endpoint ID is the same.
results.endpointId
string
obligatorio
The unique identifier of the endpoint. The long conde ID is the same.
results.numberString
string
obligatorio
The phone number in E.164 format.
results.countryCode
string
obligatorio
The country code in ISO 3166-1 alpha-2 format.
results.type
string
The type of long code number.
Possible values: local, national, toll-free, mobile
results.capabilities
object
obligatorio
Capabilities of the phone number. It shows if the phone number supports voice, sms and/or mms.
Mostrar atributos secundarios
results.capabilities.voice
object
obligatorio
Mostrar atributos secundarios
results.capabilities.voice.inbound
boolean
obligatorio
Whether the number supports inbound use cases.
results.capabilities.voice.outbound
boolean
obligatorio
Whether the number supports outbound use cases.
results.capabilities.sms
object
obligatorio
Mostrar atributos secundarios
results.capabilities.sms.inbound
boolean
obligatorio
Whether the number supports inbound use cases.
results.capabilities.sms.outbound
boolean
obligatorio
Whether the number supports outbound use cases.
results.capabilities.mms
object
obligatorio
Mostrar atributos secundarios
results.capabilities.mms.inbound
boolean
obligatorio
Whether the number supports inbound use cases.
results.capabilities.mms.outbound
boolean
obligatorio
Whether the number supports outbound use cases.
results.capabilities.whatsapp
object
Mostrar atributos secundarios
results.capabilities.whatsapp.inbound
boolean
obligatorio
Whether the number supports inbound use cases.
results.capabilities.whatsapp.outbound
boolean
obligatorio
Whether the number supports outbound use cases.
results.createdAt
string
obligatorio
results.updatedAt
string
obligatorio
results.order
object
The order that created this long code number. It contains information such as the capabilities, order status and type.
Mostrar atributos secundarios
results.order.countryCode
string
obligatorio
The country code in ISO 3166-1 alpha-2 format.
results.order.type
string
obligatorio
The type of long code number.
Possible values: local, national, toll-free, mobile
results.order.capabilities
array of string
obligatorio
results.order.prefix
string
results.order.status
string
obligatorio
Possible values: draft, submitted, processing, fulfilled, rejected, cancelled
results.order.createdAt
string
obligatorio
results.order.updatedAt
string
obligatorio
results.deprovisionAt
string
The date and time when the long code number should be deprovisioned.
results.endpoint
object
obligatorio
A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.
Mostrar atributos secundarios
results.endpoint.id
string
obligatorio
The ID of the endpoint.
results.endpoint.type
string
obligatorio
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
obligatorio
The unique identifier of the instance.
results.endpoint.name
string
obligatorio
The name of the endpoint. For some cases it will be the number in international format as string.
results.endpoint.capabilities
array of object
obligatorio
Mostrar atributos secundarios
results.endpoint.capabilities.name
string
obligatorio
Possible values: sms
results.endpoint.capabilities.inbound
object
Mostrar atributos secundarios
results.endpoint.capabilities.inbound.status
string
obligatorio
Possible values: active, inactive, available, unavailable
results.endpoint.capabilities.inbound.issues
array of string
results.endpoint.capabilities.outbound
object
Mostrar atributos secundarios
results.endpoint.capabilities.outbound.status
string
obligatorio
Possible values: active, inactive, available, unavailable
results.endpoint.capabilities.outbound.destinationStatuses
object
Mostrar atributos secundarios
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.
Mostrar atributos secundarios
results.endpoint.dependencies.type
string
Possible values: connector
results.endpoint.dependencies.connectorId
string
obligatorio
results.endpoint.dependencies.connectorTemplateRef
string
obligatorio
results.endpoint.dependencies.capabilities
array of string
results.endpoint.issues
array of string
results.endpoint.provisioningStatus
string
obligatorio
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.
Mostrar atributos secundarios
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
obligatorio
results.endpoint.updatedAt
string
obligatorio
Ejemplo de código
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/numbers-long-code' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
A successful request to this endpoint will start a recurring monthly subscription based on the monthly cost of the number
subscribing-to-channel-created-webhooks.md