Messaging

Sender IDs

Create Default Sender

Smart Assign

API endpoints for managing default sender settings in a user's account. The Smart Assign Service API automatically selects a compliant SenderID for each country you send to, with an option to set your own default. It also lets you retrieve a list of compliant SenderIDs per country, providing transparency, control, and confidence in SMS delivery.

Download OpenAPI description

default-senders.json

default-senders.yaml

Servers

https://rest.clicksend.com/

Create Default Sender

Request

Creates a new default sender configuration to automate the selection of compliant SenderIDs. By configuring a default sender you no longer need to define the sender_id string when sending SMS messages. The default sender will be picked up automatically.

For more information on Sender IDs, please refer to What is a Sender ID or Sender Number?

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

country_codestringrequired

The country code of the recipient. Must be a valid ISO 3166-1 alpha-2 country code.

Example: "AU"

product_typestringrequired

The type of product for the assignment. Support for additional types coming soon.

Value"SMS"

Example: "SMS"

default_sender_strategiesArray of objects= 1 itemsrequired

Array detailing sender strategies. Must contain exactly 1 element. Multiple strategies support coming soon.

Example: [{"sender_id":"ClickSend","sender_type":"alpha_tag","note":"This is a test default sender"}]

default_sender_strategies[].sender_typestringrequired

The type of sender for this strategy.

Enum"alpha_tag""10DLC""tollfree""own_number""shortcode""longcode""shared_longcode"

default_sender_strategies[].sender_idstringrequired

Unique identifier for the sender. Format varies based on sender_type:

shortcode: Numeric, 3-8 digits.
longcode, tollfree, 10DLC, own_number: 2-15 digits, may include + prefix.
alpha_tag: 3-11 alphanumeric characters, must include at least one letter or +.
shared_longcode: Can be null or empty string.

Important: The sender_id must be in valid format, owned, and has ready to use status for the corresponding sender_type.

default_sender_strategies[].sender_country_codestring

The country code of the sender, using the ISO 3166-1 alpha-2 format (e.g., "US").

This field is required in the following cases:

When sender_type is own_number, longcode, tollfree, or 10DLC
When the sender_id follows the US/Canada number format (starts with +1)

For all other cases, this field is optional.

default_sender_strategies[].notestring<= 200 characters

Optional note providing additional context about the sender strategy.

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "    {
        \"country_code\": \"AU\",
        \"product_type\": \"SMS\",
        \"default_sender_strategies\": [
            {
                \"sender_id\": \"ClickSend\",
                \"sender_type\": \"alpha_tag\",
                \"note\": \"This is a test default sender\"
            }
        ]
    }" \
'https://rest.clicksend.com/v3/senders/default-senders'

Responses

Successful response

Bodyapplication/json

http_codeintegerrequired

HTTP status code of the response.

Example: 200

response_codestringrequired

Code indicating the result of the response.

Example: "SUCCESS"

response_msgstringrequired

Message providing additional information.

Example: "Operation completed successfully"

dataobject(default_sender)required

data.idstringrequired

ID of the default sender.

Example: "f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4"

data.user_idintegerrequired

User ID from the version 3 system.

Example: 123456

data.subaccount_idintegerrequired

Subaccount ID from version 3.

Example: 45678

data.country_codestringrequired

ISO 3166-1 alpha-2 formatted country code.

Example: "AU"

data.product_typestringrequired

Type of product for which the setting is applied.

Value"SMS"

Example: "SMS"

data.default_sender_strategiesArray of objectsnon-emptyrequired

Default sender strategies. Must contain 1 or more objects.

data.default_sender_strategies[].sender_typestringrequired

Type of the sender.

Enum"alpha_tag""10DLC""tollfree""own_number""shortcode""longcode""shared_longcode"

Example: "alpha_tag"

data.default_sender_strategies[].sender_idstringrequired

Identifier for the sender. Must be between 3-20 characters.

Example: "ClickSend"

data.default_sender_strategies[].sender_country_codestring

ISO 3166-1 alpha-2 formatted country code.

Example: null

data.default_sender_strategies[].priorityintegerrequired

Priority level of the sender in the strategy. Must be a positive integer.

Example: 1

data.default_sender_strategies[].statusstringrequired

Status of the sender in the strategy.

Enum"ENABLED""DISABLED"

Example: "ENABLED"

data.default_sender_strategies[].notestring

Note providing additional context about the sender. Maximum length of 200 characters. Optional.

Example: "This is a test default sender"

data.statusstringrequired

Overall status of the default sender.

Enum"ENABLED""DISABLED"

Example: "ENABLED"

data.created_timestampstringrequired

Timestamp of when the default sender was created. Must be in ISO 8601 format.

Example: "2021-08-02T00:00:00Z"

data.updated_timestampstringrequired

Timestamp of the last update to the default sender. Must be in ISO 8601 format.

Example: "2021-08-02T00:00:00Z"

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Operation completed successfully",
  "data": {
    "id": "f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4",
    "user_id": 123456,
    "subaccount_id": 45678,
    "country_code": "AU",
    "product_type": "SMS",
    "default_sender_strategies": [ … ],
    "status": "ENABLED",
    "created_timestamp": "2021-08-02T00:00:00Z",
    "updated_timestamp": "2021-08-02T00:00:00Z"
  }
}

Get List of Default Senders

Request

Retrieve a list of default senders for the current user

Query

offsetstring

Page (offset) to be used for pagination

per_pageinteger[ 1 .. 500 ]

Size of the page in pagination

Default 10

sort_bystring

Parameter to sort the results by

Default "created_timestamp"

sort_directionstring

Direction of sorting

Default "desc"

Enum"asc""desc"

Headers

Content-Typestring

Example: application/json

curl --include \
     --request GET \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/senders/default-senders?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4%238fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1&sort_by=created_timestamp&sort_direction=asc'

Responses

Successful response

Bodyapplication/json

http_codeintegerrequired

HTTP status code of the response.

Example: 200

response_codestringrequired

Code indicating the result of the response.

Example: "SUCCESS"

response_msgstringrequired

Message providing additional information.

Example: "Default senders retrieved successfully"

dataobjectrequired

data.dataArray of objects(default_sender)

List of default senders.

data.per_pageinteger

Number of items per page.

Example: 1

data.self_page_urlstring

URL for the current page.

Example: "https://api.clicksend.com/v4/sender_assignment_settings?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1"

data.next_page_urlstring

URL for the next page.

Example: "https://api.clicksend.com/v4/sender_assignment_settings?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1"

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Operation completed successfully",
  "data": {
    "data": [ … ],
    "per_page": 1,
    "self_page_url": "https://api.clicksend.com/v4/sender_assignment_settings?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1",
    "next_page_url": "https://api.clicksend.com/v4/sender_assignment_settings?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1"
  }
}

Update Default Sender

Request

Updates the details of an existing default sender configuration.

For more information on Sender IDs, please refer to What is a Sender ID or Sender Number?

Path

default_sender_idstringrequired

The ID of the default sender to update

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

default_sender_strategiesArray of objects= 1 itemsrequired

Array detailing sender strategies. Must contain exactly 1 element. Multiple strategies support coming soon.

Example: [{"sender_id":"ClickSend","sender_type":"alpha_tag","note":"This is a test default sender"}]

default_sender_strategies[].sender_typestringrequired

The type of sender for this strategy.

Enum"alpha_tag""10DLC""tollfree""own_number""shortcode""longcode""shared_longcode"

default_sender_strategies[].sender_idstringrequired

Unique identifier for the sender. Format varies based on sender_type:

shortcode: Numeric, 3-8 digits.
longcode, tollfree, 10DLC, own_number: 2-15 digits, may include + prefix.
alpha_tag: 3-11 alphanumeric characters, must include at least one letter or +.
shared_longcode: Can be null or empty string.

Important: The sender_id must be in valid format, owned, and has ready to use status for the corresponding sender_type.

default_sender_strategies[].sender_country_codestring

The country code of the sender, using the ISO 3166-1 alpha-2 format (e.g., "US").

This field is required in the following cases:

When sender_type is own_number, longcode, tollfree, or 10DLC
When the sender_id follows the US/Canada number format (starts with +1)

For all other cases, this field is optional.

default_sender_strategies[].notestring<= 200 characters

Optional note providing additional context about the sender strategy.

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
     --data-binary "{
  \"default_sender_strategies\": [
    {
      \"sender_id\": \"ClickSend\",
      \"sender_type\": \"alpha_tag\",
      \"note\": \"This is a test default sender\"
    }
  ]
}" \
'https://rest.clicksend.com/v3/senders/default-senders/{default_sender_id}'

Responses

Successful response

Bodyapplication/json

http_codeintegerrequired

HTTP status code of the response.

Example: 200

response_codestringrequired

Code indicating the result of the response.

Example: "SUCCESS"

response_msgstringrequired

Message providing additional information.

Example: "Operation completed successfully"

dataobject(default_sender)required

data.idstringrequired

ID of the default sender.

Example: "f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4"

data.user_idintegerrequired

User ID from the version 3 system.

Example: 123456

data.subaccount_idintegerrequired

Subaccount ID from version 3.

Example: 45678

data.country_codestringrequired

ISO 3166-1 alpha-2 formatted country code.

Example: "AU"

data.product_typestringrequired

Type of product for which the setting is applied.

Value"SMS"

Example: "SMS"

data.default_sender_strategiesArray of objectsnon-emptyrequired

Default sender strategies. Must contain 1 or more objects.

data.default_sender_strategies[].sender_typestringrequired

Type of the sender.

Enum"alpha_tag""10DLC""tollfree""own_number""shortcode""longcode""shared_longcode"

Example: "alpha_tag"

data.default_sender_strategies[].sender_idstringrequired

Identifier for the sender. Must be between 3-20 characters.

Example: "ClickSend"

data.default_sender_strategies[].sender_country_codestring

ISO 3166-1 alpha-2 formatted country code.

Example: null

data.default_sender_strategies[].priorityintegerrequired

Priority level of the sender in the strategy. Must be a positive integer.

Example: 1

data.default_sender_strategies[].statusstringrequired

Status of the sender in the strategy.

Enum"ENABLED""DISABLED"

Example: "ENABLED"

data.default_sender_strategies[].notestring

Note providing additional context about the sender. Maximum length of 200 characters. Optional.

Example: "This is a test default sender"

data.statusstringrequired

Overall status of the default sender.

Enum"ENABLED""DISABLED"

Example: "ENABLED"

data.created_timestampstringrequired

Timestamp of when the default sender was created. Must be in ISO 8601 format.

Example: "2021-08-02T00:00:00Z"

data.updated_timestampstringrequired

Timestamp of the last update to the default sender. Must be in ISO 8601 format.

Example: "2021-08-02T00:00:00Z"

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Operation completed successfully",
  "data": {
    "id": "f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4",
    "user_id": 123456,
    "subaccount_id": 45678,
    "country_code": "AU",
    "product_type": "SMS",
    "default_sender_strategies": [ … ],
    "status": "ENABLED",
    "created_timestamp": "2021-08-02T00:00:00Z",
    "updated_timestamp": "2021-08-02T00:00:00Z"
  }
}

Get Default Sender Details

Request

Retrieve detailed information about a specific default sender configuration

Path

default_sender_idstringrequired

The ID of the default sender to retrieve

Headers

Content-Typestring

Example: application/json

curl --include \
     --request GET \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/senders/default-senders/{default_sender_id}'

Responses

Successful response

Bodyapplication/json

http_codeintegerrequired

HTTP status code of the response.

Example: 200

response_codestringrequired

Code indicating the result of the response.

Example: "SUCCESS"

response_msgstringrequired

Message providing additional information.

Example: "Operation completed successfully"

dataobject(default_sender)required

data.idstringrequired

ID of the default sender.

Example: "f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4"

data.user_idintegerrequired

User ID from the version 3 system.

Example: 123456

data.subaccount_idintegerrequired

Subaccount ID from version 3.

Example: 45678

data.country_codestringrequired

ISO 3166-1 alpha-2 formatted country code.

Example: "AU"

data.product_typestringrequired

Type of product for which the setting is applied.

Value"SMS"

Example: "SMS"

data.default_sender_strategiesArray of objectsnon-emptyrequired

Default sender strategies. Must contain 1 or more objects.

data.default_sender_strategies[].sender_typestringrequired

Type of the sender.

Enum"alpha_tag""10DLC""tollfree""own_number""shortcode""longcode""shared_longcode"

Example: "alpha_tag"

data.default_sender_strategies[].sender_idstringrequired

Identifier for the sender. Must be between 3-20 characters.

Example: "ClickSend"

data.default_sender_strategies[].sender_country_codestring

ISO 3166-1 alpha-2 formatted country code.

Example: null

data.default_sender_strategies[].priorityintegerrequired

Priority level of the sender in the strategy. Must be a positive integer.

Example: 1

data.default_sender_strategies[].statusstringrequired

Status of the sender in the strategy.

Enum"ENABLED""DISABLED"

Example: "ENABLED"

data.default_sender_strategies[].notestring

Note providing additional context about the sender. Maximum length of 200 characters. Optional.

Example: "This is a test default sender"

data.statusstringrequired

Overall status of the default sender.

Enum"ENABLED""DISABLED"

Example: "ENABLED"

data.created_timestampstringrequired

Timestamp of when the default sender was created. Must be in ISO 8601 format.

Example: "2021-08-02T00:00:00Z"

data.updated_timestampstringrequired

Timestamp of the last update to the default sender. Must be in ISO 8601 format.

Example: "2021-08-02T00:00:00Z"

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Operation completed successfully",
  "data": {
    "id": "f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4",
    "user_id": 123456,
    "subaccount_id": 45678,
    "country_code": "AU",
    "product_type": "SMS",
    "default_sender_strategies": [ … ],
    "status": "ENABLED",
    "created_timestamp": "2021-08-02T00:00:00Z",
    "updated_timestamp": "2021-08-02T00:00:00Z"
  }
}

Delete Default Sender

Request

Removes a specified default sender setting. If you don't configure a default sender and leave the sender_id string blank when sending an SMS, Smart Assign will pick the best suitable, compliant, available SenderID for you.

Path

default_sender_idstringrequired

The ID of the default sender to delete

Headers

Content-Typestring

Example: application/json

curl --include \
     --request DELETE \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/senders/default-senders/{default_sender_id}'

Responses

Successful response (No Content)

List Compliant Sender Types

Request

Retrieves the list of compliant sender types for specific countries

Query

filter[product_type]stringrequired

Type of the product

Value"SMS"

Example: filter[product_type]=SMS

filter[country_code][{index}]Array of strings<= 98 items

Array of recipient country codes (ISO 3166-1 alpha-2). If not specified, will get all compliant sender types for all countries. Replace {index} with the appropriate index value.

Example: filter[country_code][0]=US&filter[country_code][1]=AU

curl --include \
     --request GET \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/senders/compliant-sender-types?filter[product_type]=SMS&filter[country_code][0]=AU&filter[country_code][1]=US'

Responses

Successful response

Bodyapplication/json

http_codeintegerrequired

HTTP status code of the response

response_codestringrequired

Code indicating the result of the response

response_msgstringrequired

Message providing additional information

dataobjectrequired

data.dataArray of objectsnon-emptyrequired

data.data[].recipient_country_codestring^[A-Z]{2}$required

ISO 3166-1 alpha-2 formatted country code

data.data[].blocked_sender_typesArray of stringsrequired

List of blocked sender types in recipient country

data.data[].allowed_sender_typesArray of objectsrequired

data.data[].allowed_sender_types[].sender_typestringrequired

Type of sender

Enum"alpha_tag""10DLC""tollfree""own_number""shortcode""longcode""shared_longcode"

data.data[].allowed_sender_types[].allowed_sender_countriesobjectrequired

data.data[].allowed_sender_types[].allowed_sender_countries.globalbooleanrequired

Whether this sender type is allowed sending from any country

data.data[].allowed_sender_types[].allowed_sender_countries.country_codesArray of strings

List of ISO 3166-1 alpha-2 formatted country codes

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Compliant sender types retrieved successfully",
  "data": {
    "data": [ … ]
  }
}

Smart Assign

Create Default Sender

Request

Responses

Was this helpful?

Get List of Default Senders

Request

Responses

Was this helpful?

Update Default Sender

Request

Responses

Was this helpful?

Get Default Sender Details

Request

Responses

Was this helpful?

Delete Default Sender

Request

Responses

Was this helpful?

List Compliant Sender Types

Request

Responses

Was this helpful?

Smart Assign

Create Default Sender

RequestExpand all

Responses

Was this helpful?

Get List of Default Senders

Request

Responses

Was this helpful?

Update Default Sender

RequestExpand all

Responses

Was this helpful?

Get Default Sender Details

Request

Responses

Was this helpful?

Delete Default Sender

Request

Responses

Was this helpful?

List Compliant Sender Types

Request

Responses

Was this helpful?

Request

Request