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

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

application/json

Responseall of

404

The request did not pass validation

application/json

422

The request did not pass validation

application/json

get

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": "2025-10-03T15:57:09.248Z",
        "additionalFields": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "tags": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "createdAt": "2025-10-03T15:57:09.248Z",
      "updatedAt": "2025-10-03T15:57:09.248Z"
    }
  ],
  "nextPageToken": "text"
}

Get a Use Case

Get workspace use case

get

Get workspace use case

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

useCaseIdstring · uuidRequired

The ID for a useCase

Responses

200

application/json

404

The request did not pass validation

application/json

422

The request did not pass validation

application/json

get

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": "2025-10-03T15:57:09.248Z",
    "additionalFields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "createdAt": "2025-10-03T15:57:09.248Z",
  "updatedAt": "2025-10-03T15:57:09.248Z"
}

Create a Use Case

Creates a new use case for a workspace

post

Creates a new use case for a workspace

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Body

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

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": "2025-10-03T15:57:09.248Z",
    "additionalFields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "createdAt": "2025-10-03T15:57:09.248Z",
  "updatedAt": "2025-10-03T15:57:09.248Z"
}

Example request

curl --location 'https://app.bird.com/api/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."
        ]
    }
}'

Property

Type

Required

Description

name

string

Yes

The name of your use case, e.g. My transactional use case.

use

string

Yes

Type of use case. Choose one of the following: 2FA, ACCOUNT_NOTIFICATION, CUSTOMER_CARE, DELIVERY_NOTIFICATION, FRAUD_ALERT, HIGHER_EDUCATION, MARKETING, POLLING_VOTING, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT

caseType

string

Yes

Type of use case. Use always default for non-10DLC or TFN use cases.

description

string

Yes

Description of your use case.

additionalFields.sample_messages

array of strings

Yes

Message samples (minimal 1), for the use case. Can be used to request content approval at carriers.

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.

Last updated 29 minutes ago

Was this helpful?