SMS Use Cases

A quick start to Use Case management

Overview

To programmatically install an SMS channel, the API expects a reference to a use case in the request. For US 10DLC and North American Toll-Free Numbers, the use case entity is created when registering for these types of numbers. For other types of senders, like international phone numbers or alphanumeric senders, you need to create a generic use case. Use cases can be reused for multiple channels (for different senders) when the use case of the channels is the same.

List Use Cases

List use cases for a workspace

get

List use cases for a workspace

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

limitinteger · min: 1 · max: 1000Optional

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

404

The request did not pass validation

application/json

422

The request did not pass validation

application/json

get

/workspaces/{workspaceId}/use-cases

HTTPcURLJavaScriptPython

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

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "status": "created",
      "use": "text",
      "caseType": "default",
      "definitionVersion": "text",
      "description": "text",
      "additionalFields": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "integrationState": {
        "externalId": "text",
        "status": "text",
        "updatedAt": "2026-02-03T15:55:02.553Z",
        "additionalFields": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "tags": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "createdAt": "2026-02-03T15:55:02.553Z",
      "updatedAt": "2026-02-03T15:55:02.553Z"
    }
  ],
  "nextPageToken": "text"
}

Get a Use Case

Get workspace use case

get

Get workspace use case

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

useCaseIdstring · uuidRequired

The ID for a useCase

Responses

200

OK

application/json

404

The request did not pass validation

application/json

422

The request did not pass validation

application/json

get

/workspaces/{workspaceId}/use-cases/{useCaseId}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/use-cases/{useCaseId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "status": "created",
  "use": "text",
  "caseType": "default",
  "definitionVersion": "text",
  "description": "text",
  "additionalFields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "integrationState": {
    "externalId": "text",
    "status": "text",
    "updatedAt": "2026-02-03T15:55:02.553Z",
    "additionalFields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "createdAt": "2026-02-03T15:55:02.553Z",
  "updatedAt": "2026-02-03T15:55:02.553Z"
}

Create a Use Case

Creates a new use case for a workspace

post

Creates a new use case for a workspace

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Body

application/json

namestringRequired

usestringRequired

caseTypestring · enumRequiredDefault: defaultPossible values:

definitionVersionstringOptional

descriptionstringRequired

Responses

202

Use Case was created

application/json

400

The request did not pass validation

application/json

422

The request did not pass validation

application/json

post

/workspaces/{workspaceId}/use-cases

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/use-cases HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 155

{
  "name": "text",
  "use": "text",
  "caseType": "default",
  "definitionVersion": "text",
  "description": "text",
  "additionalFields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "status": "created",
  "use": "text",
  "caseType": "default",
  "definitionVersion": "text",
  "description": "text",
  "additionalFields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "integrationState": {
    "externalId": "text",
    "status": "text",
    "updatedAt": "2026-02-03T15:55:02.553Z",
    "additionalFields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "createdAt": "2026-02-03T15:55:02.553Z",
  "updatedAt": "2026-02-03T15:55:02.553Z"
}

Example request

Request

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/use-cases' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
    "name": "Multi-factor authentication",
    "description": "MFA messages via SMS",
    "use": "2FA",
    "caseType": "default",
    "additionalFields": {
        "sample_messages": [
            "Your login code is 123456."
        ]
    }
}'

Parameter description

The ID returned in the request result can be used as useCaseId value when linking the use case to the number, and in the request to create an SMS channel.