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

Parametry zapytania

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.

Treść odpowiedzi

results

array of object

Pokaż atrybuty podrzędne

results.id

string

wymagane

results.name

string

wymagane

results.status

string

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

results.use

string

wymagane

results.caseType

string

wymagane

Possible values: default, tendlc, tfn-verification

results.definitionVersion

string

results.description

string

wymagane

results.additionalFields

object

results.integrationState

object

Pokaż atrybuty podrzędne

results.integrationState.externalId

string

results.integrationState.status

string

results.integrationState.updatedAt

string

results.integrationState.additionalFields

object

results.tags

array of object

Pokaż atrybuty podrzędne

results.tags.key

string

results.tags.value

string

results.createdAt

string

wymagane

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.

Przykład kodu

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

Treść odpowiedzi

string

wymagane

name

string

wymagane

status

string

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

use

string

wymagane

caseType

string

wymagane

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

wymagane

additionalFields

object

integrationState

object

Pokaż atrybuty podrzędne

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

Treść żądania

name

string

wymagane

use

string

wymagane

caseType

string

wymagane

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

wymagane

additionalFields

object

Treść odpowiedzi

string

wymagane

name

string

wymagane

status

string

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

use

string

wymagane

caseType

string

wymagane

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

wymagane

additionalFields

object

integrationState

object

Pokaż atrybuty podrzędne

integrationState.externalId

string

integrationState.status

string

integrationState.updatedAt

string

integrationState.additionalFields

object

Example request

Przykład kodu

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.