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

Paramètres de requête

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.

Corps de la réponse

results

array of object

Afficher les attributs enfants

results.id

string

obligatoire

results.name

string

obligatoire

results.status

string

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

results.use

string

obligatoire

results.caseType

string

obligatoire

Possible values: default, tendlc, tfn-verification

results.definitionVersion

string

results.description

string

obligatoire

results.additionalFields

object

results.integrationState

object

Afficher les attributs enfants

results.integrationState.externalId

string

results.integrationState.status

string

results.integrationState.updatedAt

string

results.integrationState.additionalFields

object

results.tags

array of object

Afficher les attributs enfants

results.tags.key

string

results.tags.value

string

results.createdAt

string

obligatoire

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.

Exemple de code

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

Corps de la réponse

string

obligatoire

name

string

obligatoire

status

string

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

use

string

obligatoire

caseType

string

obligatoire

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

obligatoire

additionalFields

object

integrationState

object

Afficher les attributs enfants

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

Corps de la requête

name

string

obligatoire

use

string

obligatoire

caseType

string

obligatoire

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

obligatoire

additionalFields

object

Corps de la réponse

string

obligatoire

name

string

obligatoire

status

string

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

use

string

obligatoire

caseType

string

obligatoire

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

obligatoire

additionalFields

object

integrationState

object

Afficher les attributs enfants

integrationState.externalId

string

integrationState.status

string

integrationState.updatedAt

string

integrationState.additionalFields

object

Example request

Exemple de code

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.