Alpha Tags

Messaging

Sender IDs

Alpha Tags

API endpoints for managing alpha tags as sender IDs for messaging services.

Download OpenAPI description

alpha-tags.json

alpha-tags.yaml

Servers

https://rest.clicksend.com/

Request Alpha Tag

Request

Request to register an alpha tag. After requested, the alpha tag will be reviewed by ClickSend and either approved or rejected. Some countries (e.g Australia) require you to submit additional fields due to government mandated compliance checks.

Properties

Name	Type	Required	Restrictions	Description
alpha_tag	string	true	yes	The alpha tag name. Length must be between 3 - 11 characters, can only contain a-z A-Z 0-9 + and must contain at least one non numeric.
reason	string	false	none	Must be one of the following: `Sole Trader Name`, `Company Name`, `Partnership Name`, `Registered Trust Name`, `Co-Operative Name`, `Indigenous Corporation Name`, `Registered Organisation Name`, `Personal Name`, `Trademark`, `Government Agency or Entity`, `Product or Service Name`, `Acronym/Initialism`, `Contraction of Name`, `Third Party`. In case of `Third Party`, we will contact you to collect the relevant information.
countries	array of strings	false	none	List of country codes (e.g., "AU", "US") where the alpha tag is requested. Only supported and required for AU.
businesses	array of objects	false	none	List of business details required for alpha tag registration. Each object contains country, business information, ... Required if `countries` is provided. When `business_relationship` is `ENTITY_ASSOCIATE`, the following partner fields are also required: `partner_business_name`, `partner_abn`, `partner_business_info`, `partner_business_address`, `partner_representative`. These fields are forbidden for any other `business_relationship` value.

Response

The response returns the alpha tag, including a region_statuses object with the status of each scope. When countries includes AU and businesses contains the Australian registration details, both scopes start as PENDING:

{
  "region_statuses": { "GLOBAL": "PENDING", "AU": "PENDING" }
}

If your account already has an alpha tag with the same name that does not include AU, the request adds AU to that alpha tag and returns it. GLOBAL keeps its current status and AU is PENDING.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Security

basicAuth

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

alpha_tagstring

reasonstring

countriesArray of strings= 1 itemsunique

Items Value"AU"

businessesArray of objects= 1 items

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "    {
        \"alpha_tag\": \"Abc123+\",
        \"reason\": \"Sole Trader Name\"
    }" \
'https://rest.clicksend.com/v3/alpha-tags'

Responses

Successful response

Bodyapplication/json

idstring

The unique identifier for the record.

Example: "db630385-cb76-457d-8f16-76df1b394257"

account_idstring

The unique identifier for the account.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

workspace_idstring

The unique identifier for the workspace.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

user_idstring

The unique identifier for the user.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

alpha_tagstring

The alpha tag.

Example: "Abc123"

statusstring

Usually matches region_statuses.GLOBAL, but older Australian alpha tags can show COMPLETE_REGISTRATION here. Use region_statuses for the status of each scope.

Example: "PENDING"

region_statusesobject

The status of each scope of the alpha tag. GLOBAL is always present. A country key, such as AU, is present when the alpha tag includes that country in countries.

Example: {"GLOBAL":"APPROVED","AU":"PENDING"}

reasonstring

The reason for the status.

Example: "Sole Trader Name"

countriesArray of strings or null

List of country codes where the alpha tag is requested. If not provided, it means a global alpha tag.

Example: ["AU"]

created_timestampstring

The timestamp when the record was created. Usually ISO 8601 (e.g. "2021-05-11T01:00:00.123Z"), but returned as a plain string rather than a strict date-time since some older records don't include a UTC offset (e.g. "2024-01-10T10:55:26.818097").

Example: "2021-05-11T01:00:00.123Z"

updated_timestampstring

The timestamp when the record was last updated. Usually ISO 8601 (e.g. "2021-05-11T01:05:00.123Z"), but returned as a plain string rather than a strict date-time since some older records don't include a UTC offset.

Example: "2021-05-11T01:05:00.123Z"

Response

application/json

{
  "id": "db630385-cb76-457d-8f16-76df1b394257",
  "account_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "workspace_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "user_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "alpha_tag": "Abc123",
  "status": "PENDING",
  "region_statuses": {
    "GLOBAL": "APPROVED",
    "AU": "PENDING"
  },
  "reason": "Sole Trader Name",
  "countries": [
    "AU"
  ],
  "created_timestamp": "2021-05-11T01:00:00.123Z",
  "updated_timestamp": "2021-05-11T01:05:00.123Z"
}

List Alpha Tags

Request

List your alpha tags.

Security

basicAuth

Query

sort_directionstring

The sort direction for the results. The default value is asc.

Default "asc"

Enum"asc""desc"

Example: sort_direction=asc

page_sizeinteger[ 1 .. 1000 ]

The number of items to return per page. This parameter controls the size of each page of results. The default value is 10.

Default 10

Example: page_size=10

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
'https://rest.clicksend.com/v3/alpha-tags'

Responses

Successful response

Bodyapplication/json

alpha_tagsArray of objects(alpha_tag)

The list of alpha tags.

_metadataobject

The metadata.

Response

application/json

{
  "alpha_tags": [
    { … }
  ],
  "_metadata": {
    "pagination": { … }
  }
}

Get Alpha Tag

Request

Get a specific alpha tag.

Parameters

Parameter	In	Type	Required	Description
alpha_tag_id	path	uuid	true	ID of the alpha tag

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Security

basicAuth

Path

alpha_tag_idstringrequired

Headers

Content-Typestring

Example: application/json

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
'https://rest.clicksend.com/v3/alpha-tags/db630385-cb76-457d-8f16-76df1b394257'

Responses

Successful response

Bodyapplication/json

idstring

The unique identifier for the record.

Example: "db630385-cb76-457d-8f16-76df1b394257"

account_idstring

The unique identifier for the account.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

workspace_idstring

The unique identifier for the workspace.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

user_idstring

The unique identifier for the user.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

alpha_tagstring

The alpha tag.

Example: "Abc123"

statusstring

Usually matches region_statuses.GLOBAL, but older Australian alpha tags can show COMPLETE_REGISTRATION here. Use region_statuses for the status of each scope.

Example: "PENDING"

region_statusesobject

The status of each scope of the alpha tag. GLOBAL is always present. A country key, such as AU, is present when the alpha tag includes that country in countries.

Example: {"GLOBAL":"APPROVED","AU":"PENDING"}

reasonstring

The reason for the status.

Example: "Sole Trader Name"

countriesArray of strings or null

List of country codes where the alpha tag is requested. If not provided, it means a global alpha tag.

Example: ["AU"]

created_timestampstring

Example: "2021-05-11T01:00:00.123Z"

updated_timestampstring

Example: "2021-05-11T01:05:00.123Z"

Response

application/json

{
  "id": "db630385-cb76-457d-8f16-76df1b394257",
  "account_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "workspace_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "user_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "alpha_tag": "Abc123",
  "status": "PENDING",
  "region_statuses": {
    "GLOBAL": "APPROVED",
    "AU": "PENDING"
  },
  "reason": "Sole Trader Name",
  "countries": [
    "AU"
  ],
  "created_timestamp": "2021-05-11T01:00:00.123Z",
  "updated_timestamp": "2021-05-11T01:05:00.123Z"
}

Delete Alpha Tag

Request

Delete a specific alpha tag.

Parameters

Parameter	In	Type	Required	Description
alpha_tag_id	path	uuid	true	ID of the alpha tag

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Security

basicAuth

Path

alpha_tag_idstringrequired

Headers

Content-Typestring

Example: application/json

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request DELETE \
'https://rest.clicksend.com/v3/alpha-tags/db630385-cb76-457d-8f16-76df1b394257'

Responses

Successful response

Bodyapplication/json

Response

application/json

null

Alpha Tags

Request Alpha Tag

Request

Properties

Response

Responses

Was this helpful?

List Alpha Tags

Request

Responses

Was this helpful?

Get Alpha Tag

Request

Parameters

Responses

Was this helpful?

Delete Alpha Tag

Request

Parameters

Responses

Was this helpful?

Alpha Tags

Request Alpha Tag

RequestExpand all

Properties

Response

Responses

Was this helpful?

List Alpha Tags

Request

Responses

Was this helpful?

Get Alpha Tag

Request

Parameters

Responses

Was this helpful?

Delete Alpha Tag

Request

Parameters

Responses

Was this helpful?

Request