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

Parametri di query

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.

Payload della risposta

results

array of object

Mostra attributi secondari

results.id

string

obbligatorio

results.name

string

obbligatorio

results.status

string

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

results.use

string

obbligatorio

results.caseType

string

obbligatorio

Possible values: default, tendlc, tfn-verification

results.definitionVersion

string

results.description

string

obbligatorio

results.additionalFields

object

results.integrationState

object

Mostra attributi secondari

results.integrationState.externalId

string

results.integrationState.status

string

results.integrationState.updatedAt

string

results.integrationState.additionalFields

object

results.tags

array of object

Mostra attributi secondari

results.tags.key

string

results.tags.value

string

results.createdAt

string

obbligatorio

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.

Esempio di codice

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

Payload della risposta

string

obbligatorio

name

string

obbligatorio

status

string

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

use

string

obbligatorio

caseType

string

obbligatorio

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

obbligatorio

additionalFields

object

integrationState

object

Mostra attributi secondari

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

Payload della richiesta

name

string

obbligatorio

use

string

obbligatorio

caseType

string

obbligatorio

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

obbligatorio

additionalFields

object

Payload della risposta

string

obbligatorio

name

string

obbligatorio

status

string

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

use

string

obbligatorio

caseType

string

obbligatorio

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

obbligatorio

additionalFields

object

integrationState

object

Mostra attributi secondari

integrationState.externalId

string

integrationState.status

string

integrationState.updatedAt

string

integrationState.additionalFields

object

Example request

Esempio di codice

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.