No-code docs

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

OK

application/json
Responseall of
get
/workspaces/{workspaceId}/use-cases
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-27T16:48:12.107Z",
        "additionalFields": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "tags": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "createdAt": "2025-10-27T16:48:12.107Z",
      "updatedAt": "2025-10-27T16:48:12.107Z"
    }
  ],
  "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

OK

application/json
get
/workspaces/{workspaceId}/use-cases/{useCaseId}
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-27T16:48:12.107Z",
    "additionalFields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "createdAt": "2025-10-27T16:48:12.107Z",
  "updatedAt": "2025-10-27T16:48:12.107Z"
}

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
post
/workspaces/{workspaceId}/use-cases
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-27T16:48:12.107Z",
    "additionalFields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "createdAt": "2025-10-27T16:48:12.107Z",
  "updatedAt": "2025-10-27T16:48:12.107Z"
}

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."
        ]
    }
}'

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

Was this helpful?