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
The ID of the workspace
Limits the number of results to return
10Pagination token that keeps of track of the current position in the list
Order in which to retrieve the results
falseOK
The request did not pass validation
The request did not pass validation
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
The ID of the workspace
The ID for a useCase
OK
The request did not pass validation
The request did not pass validation
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
The ID of the workspace
defaultPossible values: Use Case was created
The request did not pass validation
The request did not pass validation
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."
]
}
}'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
Was this helpful?

