Short Code Numbers

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 API access.

List Short Code Numbers

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

List Workspace Short Code Numbers

get

/workspaces/{workspaceId}/numbers-short-code

Authorizations

useraccessKey

Path parameters

workspaceIdstringrequired

Query parameters

limitinteger · min: 1 · max: 99 · default: 10

Limits the number of results to return

pageTokenstring · max: 8000

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

reverseboolean

Order in which to retrieve the results

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/workspaces/{workspaceId}/numbers-short-code' \
  --header 'Authorization: Bearer jwt'

200

200

{
  "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-02-20T18:56:17.407Z",
      "updatedAt": "2025-02-20T18:56:17.407Z",
      "endpoint": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "long-code-number",
        "instanceId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "provisioningStatus": "provisioned",
        "createdAt": "2025-02-20T18:56:17.407Z",
        "updatedAt": "2025-02-20T18:56:17.407Z",
        "capabilities": [
          {
            "name": "sms",
            "inbound": {
              "status": "active",
              "issues": [
                "subscription-is-not-active"
              ]
            },
            "outbound": {
              "status": "active",
              "supportsDestinations": true,
              "issues": [
                "subscription-is-not-active"
              ],
              "destinationStatuses": {
                "active": 1,
                "inactive": 1,
                "available": 1,
                "unavailable": 1
              }
            }
          }
        ],
        "dependencies": [
          {
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text",
            "type": "connector",
            "capabilities": [
              "voice"
            ]
          }
        ],
        "issues": [
          "subscription-is-not-active"
        ]
      }
    }
  ]
}

OK

Request

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-short-code/" \
     -H 'Authorization: Bearer <your-access-key>'

Response

{
    "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.

Get Workspace Short Code Number

get

/workspaces/{workspaceId}/numbers-short-code/{shortCodeNumberId}

Authorizations

useraccessKey

Path parameters

workspaceIdstringrequired

shortCodeNumberIdstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/workspaces/{workspaceId}/numbers-short-code/{shortCodeNumberId}' \
  --header 'Authorization: Bearer jwt'

200

404

200

{
  "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-02-20T18:56:17.407Z",
  "updatedAt": "2025-02-20T18:56:17.407Z",
  "endpoint": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "long-code-number",
    "instanceId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "provisioningStatus": "provisioned",
    "createdAt": "2025-02-20T18:56:17.407Z",
    "updatedAt": "2025-02-20T18:56:17.407Z",
    "capabilities": [
      {
        "name": "sms",
        "inbound": {
          "status": "active",
          "issues": [
            "subscription-is-not-active"
          ]
        },
        "outbound": {
          "status": "active",
          "supportsDestinations": true,
          "issues": [
            "subscription-is-not-active"
          ],
          "destinationStatuses": {
            "active": 1,
            "inactive": 1,
            "available": 1,
            "unavailable": 1
          }
        }
      }
    ],
    "dependencies": [
      {
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text",
        "type": "connector",
        "capabilities": [
          "voice"
        ]
      }
    ],
    "issues": [
      "subscription-is-not-active"
    ]
  }
}

OK

Request

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-short-code/{shorCodeNumberId}" \
     -H 'Authorization: Bearer <your-access-key>'

Response

{
    "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
                    }
                }
            }
        ]
    }
}