LogoLogo
No-code docsResources
  • 🖥️Welcome to the Bird API Docs
  • API Access
    • Access Policies
    • Access Roles
    • API Authorization
    • Common API usage
  • Conversations API
    • API reference
      • Channel configuration
        • Get conversations configuration
        • Update conversations configuration
      • Conversations messaging
        • Create conversation message
        • List conversation messages
        • Get conversation message
        • Update conversation message
        • Delete conversation message
        • Create pre-signed upload
      • Conversations management
        • Create conversation
        • List conversations
        • Get conversation
        • Update conversation
        • Delete conversation
      • Conversation Participants
        • Add participant to conversation
        • List participants
        • Get participant by ID
        • Get participant by identifier key and value
        • Update participant by ID
        • Update participant by identifier key and value
        • Delete participant
        • List participant conversations by ID
        • List participant conversations by identifier key and value
      • Workspace settings
        • Get antispam setting
        • Update antispam setting
        • Create allow/block rule
        • Get allow/block rule
        • List allow/block rules
        • Update allow/block rule
        • Delete allow/block rule
        • Add allow/block rules in bulk
        • Get allow/block bulk upload status
      • Events
  • Collaborations API
    • API reference
      • Agent Management
      • Team Management
      • Feeds
      • Feed item activity
      • Tags
      • Automation Rules
      • Business Hours
      • Capacity Rules
      • Routing Queues
      • Skills
      • SLA Policies
      • Macros
      • Sender Profiles
      • Ticket fields
  • Channels API
    • Supported channels
      • Programmable WhatsApp
        • Sending WhatsApp messages
        • Customer service window
        • Receiving messages
        • Message interactions
        • WhatsApp ISV integration
          • Setting up your customer workspaces
            • API Access
            • Associating your Facebook solution ID and business ID with your Bird CRM Organization
            • Creating a workspace for your customer
            • Buying a number through Bird
            • Subscribing to channel created webhooks
          • WhatsApp channel onboarding
            • Setting up the WhatsApp Embedded flow
            • Install WhatsApp phone number in Bird CRM
            • Subscribe to channel webhooks
      • Programmable SMS
        • Installing an SMS channel
          • US 10DLC API Installation
          • Toll-Free Numbers Verification API
        • Sending SMS messages
        • Receiving messages
        • Twilio Exit API
          • Using Twilio PHP SDK
          • Using Twilio Go SDK
          • Using Twilio Ruby SDK
        • Sinch Exit API
      • Programmable RCS
        • Sending messages
        • Receiving messages
        • Message interactions
      • Programmable Email
        • Sending Emails
        • Receiving messages
        • Message status
        • Message interactions
      • Programmable Line
        • Sending messages
        • Receiving messages
        • Message interactions
      • Programmable Telegram
        • Sending messages
        • Receiving messages
        • Message interactions
    • Message types
      • Text
      • Images
      • Files
      • List
      • Carousel
      • Template
    • Message status and interactions
      • Message Failure Codes
      • Message Failure Sources
        • SMS Platform Extended Error Codes
    • Send batch messages
    • API reference
      • Channel Groups
      • Messaging
      • Channels management
      • Channel connectors
      • Navigators
      • Compliance Keywords Messages
      • Conversions Sharing
      • Events
    • Rate Limit
  • Voice API
    • Installing a Voice channel
    • Voice Calls API
      • Initiate an outbound call
      • List calls from a channel
      • Get a call
      • Update a call
      • Answer a call
      • Ring a call
      • Hangup a call
      • Play a message in a call
      • Say Text-To-Speech (TTS)
      • Gather DTMF from a call
      • Forward a call
      • Record a Call
      • Record a call session
      • Update a call recording
      • List call recordings of a call
      • Get a call recording
      • Get a call insights
      • Get calls log
    • Recordings API
      • List Recordings
      • Get a Recording
      • Delete a Recording
      • List recording storage metrics
    • Transcriptions API
      • Initiate a Transcription
      • List Transcriptions
      • Get a Transcription
      • Delete a Transcription
    • Voice webhooks
    • Flash Calling API
  • Verify API
    • Verify API: Quick Start
  • Contacts API
    • Tracking Contact Events
      • API Reference
        • Get configuration
        • Track events
    • API reference
      • Manage workspace contacts
        • Create a contact
        • Get a contact
        • List contacts
        • Search contact by identifier
        • Update a contact
        • Create or update a contact by identifier
        • Delete a contact
      • Manage contact identifiers
        • Create contact identifier
        • List contact identifiers
        • Delete contact identifier
      • Manage contact attribute definition
        • Create attribute definition
        • Get attribute definition
        • List attribute definitions
      • Manage contact lists
        • Create a list
        • Get a list
        • List lists
        • Update a list
        • Delete a list
        • Add contacts to a list
        • Get contact list memberships
        • List contacts in a list
        • Remove contacts from a list
      • Lookup
        • Network/Country information for a phone number
  • Numbers API
    • API reference
      • Search Available Numbers
      • Buy a Number
      • List your Numbers
      • Get Long Code Number Details
      • Manage Endpoint Subscriptions
        • Cancel Number Subscription
      • Manage Endpoint Compliance Requirements
        • List Workspace compliace Requirements
        • Get Workspace Compliace Requirements
        • Update Workspace Compliace Requirements
      • 10DLC Compliance
        • Brands - Organization
          • Create a brand
          • List all brands
          • Get a brand
          • Update a brand
          • Delete a brand
          • Create a brand vetting
        • Brands - workspace
          • Create a brand
          • List all brands
          • Get a brand
          • Update a brand
          • Delete a brand
          • Create a brand vetting
          • List brand vettings
        • Campaigns
          • Optional: acting as Reseller
          • Create a campaign
          • List all campaigns
          • Get a campaign
          • Update a campaign
          • Delete a campaign
        • TCR Enums
        • Events
      • Toll-Free Numbers Verification API
      • Long Code Numbers
      • Short Code Numbers
      • Alphanumeric Senders
      • Events
  • Know-Your-Customer (KYC) API
    • List KYC forms
    • Get KYC form
    • Create KYC form entry
    • Update KYC form entry
    • List KYC form entries
    • Get a KYC form entry details
  • Reporting API
    • API reference
      • Channel Metrics
      • Flow Run Metrics
      • Wallet Metrics
      • Campaign Metrics
      • Message Metrics
  • Accounts API
    • API reference
      • Current user
        • Change password
        • Presigned upload
        • Memberships
        • Sessions
        • Configurations
          • Groups
            • Keys
      • IAM policies
      • Organizations
        • Upload media
        • Profile
        • Workspaces
        • Users
        • Access keys
        • Organization roles
        • Organization policies
        • Teams
          • Members
        • Approvals
          • Runs
            • Reviews
        • Configurations
          • Groups
            • Keys
      • Region groups
  • Touchpoints API
    • Supported Projects
      • Whatsapp Approved Message Templates
        • Creating WhatsApp Message templates
          • Text template blocks
          • Blocks Documentation
    • API reference
      • Projects
      • Message Templates
  • Notifications API
    • API Reference
      • Webhook subscriptions
        • Create a webhook subscription
        • List available webhook events
        • Get a webhook subscription
        • List webhook subscriptions
        • Update a webhook subscription
        • Delete a webhook subscription
        • Verifying a webhook subscription
        • Webhook subscription logs
  • Knowledge Base (KB) API
    • API reference
      • Documents
      • Folders
        • Import
      • Search
      • Presigned upload
  • Email API
    • Transmissions
  • Connectivity platform migration guide
    • Channels API and Conversations API
    • Migrating conversations API actions
    • Migrating WhatsApp channels
  • Client SDKs
    • Applications
    • Contact Profiles
      • Signed Identity
    • Push notifications
      • Quick Start
      • Subscribe contacts to push notification campaigns
      • Notification Display Priority
    • Event Tracking
      • Quick Start
      • Track Events
        • App
        • Audiences
        • Conference
        • Ecommerce
        • Hospitality
        • Lists
        • Messaging
        • Payments
        • Subscription
        • Suppressions
        • Survey
        • Web
    • App Inbox
      • Quick Start
      • Usage
      • Subscribe contacts to app inbox campaigns
    • SDK Integration
      • Android SDK
        • Notification Interactions
      • Swift SDK
        • Notification Interactions
      • Web SDK
        • Quick Start
        • Usage
        • API Reference
          • IdentityManager
          • BirdSdkApi
          • BirdTracker
            • Ecommerce
            • Conference
            • Messaging
            • Suppressions
            • Subscription
            • Survey
            • Web
            • Audiences
        • Web Push Notifications
          • Notification Interactions
  • Quickstarts
    • Conversations
    • Send an SMS message
    • Send an Email message
    • Send a WhatsApp message
Powered by GitBook
On this page

Was this helpful?

  1. Numbers API
  2. API reference

Short Code Numbers

Last updated 10 months ago

Was this helpful?

Overview

A short number (4-6 digits) used for sending and receiving SMS and MMS messages to mobile phones in a single country. Short code numbers are strictly domestic and are not recommended for sending international traffic.

API Access

The following API requests can only be made using a valid access key, and attached to an access role, with an access policy that at least specifies the permissions to the resources outlined in each section below. Learn more about .

List Short Code Numbers

In order to retrieve all short code numbers available in your workspace you can use this request.

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-short-code/" \
     -H 'Authorization: Bearer <your-access-key>'
{
    "results": [
        {
            "id": "uuid",
            "numberString": "string",
            "countryCode": "string",
            "capabilities": {
                "voice": {
                    "inbound": false,
                    "outbound": false
                },
                "sms": {
                    "inbound": true,
                    "outbound": true
                },
                "mms": {
                    "inbound": false,
                    "outbound": false
                }
            },
            "endpointId": "uuid",
            "createdAt": "2023-10-23T12:35:39.339-03:00",
            "updatedAt": "2023-10-23T12:35:39.411-03:00",
            "endpoint": {
                "id": "uuid",
                "type": "short-code-number",
                "instanceId": "uuid",
                "name": "string",
                "createdAt": "2023-10-23T12:35:39.339-03:00",
                "updatedAt": "2023-10-23T12:35:39.382-03:00",
                "capabilities": [
                    {
                        "name": "sms",
                        "inbound": {
                            "status": "active",
                            "subscriptions": [
                                "main"
                            ],
                            "fees": [
                                "setup"
                            ]
                        },
                        "outbound": {
                            "status": "active",
                            "subscriptions": [
                                "main"
                            ],
                            "fees": [
                                "setup"
                            ],
                            "destinationStatuses": {
                                "active": 1
                            }
                        }
                    }
                ]
            }
        },
        {
            "id": "uuid",
            "numberString": "string",
            "countryCode": "string",
            "capabilities": {
                "voice": {
                    "inbound": false,
                    "outbound": false
                },
                "sms": {
                    "inbound": true,
                    "outbound": true
                },
                "mms": {
                    "inbound": false,
                    "outbound": false
                }
            },
            "endpointId": "uuid",
            "createdAt": "2023-10-23T12:35:39.246-03:00",
            "updatedAt": "2023-10-23T12:35:39.246-03:00",
            "endpoint": {
                "id": "uuid",
                "type": "short-code-number",
                "instanceId": "string",
                "name": "string",
                "createdAt": "2023-10-23T12:35:39.246-03:00",
                "updatedAt": "2023-10-23T12:35:39.318-03:00",
                "capabilities": [
                    {
                        "name": "sms",
                        "inbound": {
                            "status": "active",
                            "subscriptions": [
                                "main"
                            ],
                            "fees": [
                                "setup"
                            ]
                        },
                        "outbound": {
                            "status": "active",
                            "subscriptions": [
                                "main"
                            ],
                            "fees": [
                                "setup"
                            ],
                            "destinationStatuses": {
                                "active": 1
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Get a Short Code Number

In order to retrieve the details of a short code number available in your workspace you can use this request.

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-short-code/{shorCodeNumberId}" \
     -H 'Authorization: Bearer <your-access-key>'
{
    "id": "uuid",
    "numberString": "string",
    "countryCode": "string",
    "capabilities": {
        "voice": {
            "inbound": false,
            "outbound": false
        },
        "sms": {
            "inbound": true,
            "outbound": true
        },
        "mms": {
            "inbound": false,
            "outbound": false
        }
    },
    "endpointId": "uuid",
    "createdAt": "2023-10-23T12:35:39.339-03:00",
    "updatedAt": "2023-10-23T12:35:39.411-03:00",
    "endpoint": {
        "id": "uuid",
        "type": "short-code-number",
        "instanceId": "uuid",
        "name": "string",
        "createdAt": "2023-10-23T12:35:39.339-03:00",
        "updatedAt": "2023-10-23T12:35:39.382-03:00",
        "capabilities": [
            {
                "name": "sms",
                "inbound": {
                    "status": "active",
                    "subscriptions": [
                        "main"
                    ],
                    "fees": [
                        "setup"
                    ]
                },
                "outbound": {
                    "status": "active",
                    "subscriptions": [
                        "main"
                    ],
                    "fees": [
                        "setup"
                    ],
                    "destinationStatuses": {
                        "active": 1
                    }
                }
            }
        ]
    }
}
API access

List Workspace Short Code Numbers

get
Authorizations
Path parameters
workspaceIdstringRequired
Query parameters
limitinteger · min: 1 · max: 99Optional

Limits the number of results to return

Default: 10
pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false
Responses
200
OK
application/json
Responseall of
get
GET /workspaces/{workspaceId}/numbers-short-code HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*
200

OK

{
  "nextPageToken": "text",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "endpointId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "dedicated",
      "numberString": "text",
      "countryCode": "text",
      "capabilities": {
        "voice": {
          "inbound": true,
          "outbound": true
        },
        "sms": {
          "inbound": true,
          "outbound": true
        },
        "mms": {
          "inbound": true,
          "outbound": true
        }
      },
      "createdAt": "2025-05-09T03:55:53.642Z",
      "updatedAt": "2025-05-09T03:55:53.642Z",
      "endpoint": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "long-code-number",
        "instanceId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "capabilities": [
          {
            "name": "sms",
            "inbound": {
              "status": "active",
              "issues": [
                "subscription-is-not-active"
              ]
            },
            "outbound": {
              "status": "active",
              "destinationStatuses": {
                "active": 1,
                "inactive": 1,
                "available": 1,
                "unavailable": 1
              },
              "supportsDestinations": true,
              "issues": [
                "subscription-is-not-active"
              ]
            }
          }
        ],
        "dependencies": [
          {
            "type": "connector",
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text",
            "capabilities": [
              "voice"
            ]
          }
        ],
        "issues": [
          "subscription-is-not-active"
        ],
        "provisioningStatus": "provisioned",
        "createdAt": "2025-05-09T03:55:53.642Z",
        "updatedAt": "2025-05-09T03:55:53.642Z"
      }
    }
  ]
}

Get Workspace Short Code Number

get
Authorizations
Path parameters
workspaceIdstringRequired
shortCodeNumberIdstringRequired
Responses
200
OK
application/json
Responseall of
404
Short Code Number not found
application/json
get
GET /workspaces/{workspaceId}/numbers-short-code/{shortCodeNumberId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "endpointId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "dedicated",
  "numberString": "text",
  "countryCode": "text",
  "capabilities": {
    "voice": {
      "inbound": true,
      "outbound": true
    },
    "sms": {
      "inbound": true,
      "outbound": true
    },
    "mms": {
      "inbound": true,
      "outbound": true
    }
  },
  "createdAt": "2025-05-09T03:55:53.642Z",
  "updatedAt": "2025-05-09T03:55:53.642Z",
  "endpoint": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "long-code-number",
    "instanceId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "capabilities": [
      {
        "name": "sms",
        "inbound": {
          "status": "active",
          "issues": [
            "subscription-is-not-active"
          ]
        },
        "outbound": {
          "status": "active",
          "destinationStatuses": {
            "active": 1,
            "inactive": 1,
            "available": 1,
            "unavailable": 1
          },
          "supportsDestinations": true,
          "issues": [
            "subscription-is-not-active"
          ]
        }
      }
    ],
    "dependencies": [
      {
        "type": "connector",
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text",
        "capabilities": [
          "voice"
        ]
      }
    ],
    "issues": [
      "subscription-is-not-active"
    ],
    "provisioningStatus": "provisioned",
    "createdAt": "2025-05-09T03:55:53.642Z",
    "updatedAt": "2025-05-09T03:55:53.642Z"
  }
}
  • Overview
  • API Access
  • List Short Code Numbers
  • GETList Workspace Short Code Numbers
  • Get a Short Code Number
  • GETGet Workspace Short Code Number