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

Get a list of all short code numbers assigned to your workspace. The results can be paginated. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

Query parameters

limitinteger · max: 100Optional

Limits the number of results to return.

Default: 25

pageTokenstringOptional

The cursor that keeps track of the current position in the results.

reversebooleanOptional

Reverses the order in which the results are returned.

Default: false

Responses

200

OK

application/json

nextPageTokenstringOptional

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.

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

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/numbers-short-code HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "nextPageToken": "text",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "endpointId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "dedicated",
      "numberString": "text",
      "countryCode": "US",
      "capabilities": {
        "voice": {
          "inbound": true,
          "outbound": true
        },
        "sms": {
          "inbound": true,
          "outbound": true
        },
        "mms": {
          "inbound": true,
          "outbound": true
        },
        "whatsapp": {
          "inbound": true,
          "outbound": true
        }
      },
      "createdAt": "2026-08-10T21:47:20.647Z",
      "updatedAt": "2026-08-10T21:47:20.647Z",
      "endpoint": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "long-code-number",
        "instanceId": "1551f382-6870-4480-8f9b-f5ab34936288",
        "name": "[phone]",
        "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",
        "whatsApp": {
          "whatsAppId": "text",
          "status": "verified",
          "stage": "text",
          "attempt": 1,
          "nextAttemptAt": "2026-08-10T21:47:20.647Z",
          "verificationExpiresAt": "2026-08-10T21:47:20.647Z",
          "requestedCodeAt": "2026-08-10T21:47:20.647Z",
          "createdAt": "2026-08-10T21:47:20.647Z",
          "updatedAt": "2026-08-10T21:47:20.647Z"
        },
        "createdAt": "2026-08-10T21:47:20.647Z",
        "updatedAt": "2026-08-10T21:47:20.647Z"
      }
    }
  ]
}

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 by id

get

This endpoint returns the previously created short code number by its ID.

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

shortCodeNumberIdstringRequired

Your short code number/endpoint ID.

Example: 65b18a3d-6515-4ee5-bd6d-6d638cf9bc78

Responses

200

OK

application/json

idstring · uuidRequired

endpointIdstring · uuidRequired

typestring · enumRequiredPossible values:

numberStringstringRequired

countryCodestring · iso3166-1Required

The country code in ISO 3166-1 alpha-2 format.

Example: US

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

404

The requested resource was not found.

application/json

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

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/numbers-short-code/{shortCodeNumberId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "endpointId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "dedicated",
  "numberString": "text",
  "countryCode": "US",
  "capabilities": {
    "voice": {
      "inbound": true,
      "outbound": true
    },
    "sms": {
      "inbound": true,
      "outbound": true
    },
    "mms": {
      "inbound": true,
      "outbound": true
    },
    "whatsapp": {
      "inbound": true,
      "outbound": true
    }
  },
  "createdAt": "2026-08-10T21:47:20.647Z",
  "updatedAt": "2026-08-10T21:47:20.647Z",
  "endpoint": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "long-code-number",
    "instanceId": "1551f382-6870-4480-8f9b-f5ab34936288",
    "name": "[phone]",
    "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",
    "whatsApp": {
      "whatsAppId": "text",
      "status": "verified",
      "stage": "text",
      "attempt": 1,
      "nextAttemptAt": "2026-08-10T21:47:20.647Z",
      "verificationExpiresAt": "2026-08-10T21:47:20.647Z",
      "requestedCodeAt": "2026-08-10T21:47:20.647Z",
      "createdAt": "2026-08-10T21:47:20.647Z",
      "updatedAt": "2026-08-10T21:47:20.647Z"
    },
    "createdAt": "2026-08-10T21:47:20.647Z",
    "updatedAt": "2026-08-10T21:47:20.647Z"
  }
}

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