SMS Use Cases

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

GET

/workspaces/{workspaceId}/use-cases

List use cases for a workspace

Abfrageparameter

limit

integer

Limits the number of results to return.

pageToken

string

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

reverse

boolean

Reverses the order in which the results are returned.

Antwort-Payload

results

array of object

Untergeordnete Attribute anzeigen

results.id

string

erforderlich

results.name

string

erforderlich

results.status

string

Possible values: created, cancelled, error, deleted, declined, approved

results.use

string

erforderlich

results.caseType

string

erforderlich

Possible values: default, tendlc, tfn-verification

results.definitionVersion

string

results.description

string

erforderlich

results.additionalFields

object

results.integrationState

object

Untergeordnete Attribute anzeigen

results.integrationState.externalId

string

results.integrationState.status

string

results.integrationState.updatedAt

string

results.integrationState.additionalFields

object

results.tags

array of object

Untergeordnete Attribute anzeigen

results.tags.key

string

results.tags.value

string

results.createdAt

string

erforderlich

results.updatedAt

string

nextPageToken

string

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

Codebeispiel

curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/use-cases' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Get a Use Case

GET

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

Get workspace use case

Antwort-Payload

string

erforderlich

name

string

erforderlich

status

string

Possible values: created, cancelled, error, deleted, declined, approved

use

string

erforderlich

caseType

string

erforderlich

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

erforderlich

additionalFields

object

integrationState

object

Untergeordnete Attribute anzeigen

integrationState.externalId

string

integrationState.status

string

integrationState.updatedAt

string

integrationState.additionalFields

object

Create a Use Case

POST

/workspaces/{workspaceId}/use-cases

Creates a new use case for a workspace

Anfrage-Payload

name

string

erforderlich

use

string

erforderlich

caseType

string

erforderlich

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

erforderlich

additionalFields

object

Antwort-Payload

string

erforderlich

name

string

erforderlich

status

string

Possible values: created, cancelled, error, deleted, declined, approved

use

string

erforderlich

caseType

string

erforderlich

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

erforderlich

additionalFields

object

integrationState

object

Untergeordnete Attribute anzeigen

integrationState.externalId

string

integrationState.status

string

integrationState.updatedAt

string

integrationState.additionalFields

object

Example request

Codebeispiel

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

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.