Messaging
/
Sender IDs
/
Smart Assign

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.

Languages
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

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": [ … ]
  }
}