Numbers

Messaging

Sender IDs

Numbers

API endpoints for managing dedicated numbers as sender IDs for messaging services.

Download OpenAPI description

numbers.json

numbers.yaml

Servers

https://rest.clicksend.com/

View Your Numbers

Request

Get all available dedicated numbers

Parameters

Parameter	In	Type	Required	Description
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number of records per page
q	query	string	false	Filter numbers based on multiple criteria. The query string should be formatted as key-value pairs separated by commas. Available filter keys: `type`, `number_type`, `country`
q2	query	string	false	Filter numbers based on multiple criteria. The query string should be formatted as key-value pairs separated by commas. Available filter keys: `type`
excluding_number_type	query	string	false	Exclude specific number types from the results. Available number types: `shortcode`, `tollfree`, `10DLC`
exclude_10dlc_campaign	query	boolean	false	When set to true, excludes all numbers that are associated with 10DLC campaigns

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

This endpoint requires authentication,more info...

Security

basicAuth

Query

pageinteger>= 1

Page number

Default 1

Example: page=1

limitinteger>= 15

Number of records per page

Default 15

Example: limit=100

qstring

Filter numbers based on multiple criteria. The query string should be formatted as key-value pairs separated by commas. Available filter keys:

type: Message type (e.g., SMS, MMS)
number_type: Number classification (e.g., longcode, shortcode, tollfree, 10DLC)
country: Two-letter country code (e.g., AU, US)

Example: q=type:sms,number_type:longcode,country:AU

q2string

Example: q2=type:mms

excluding_number_typestring

Exclude specific number types from the results. Available number types:

shortcode
tollfree
10DLC

Example: excluding_number_type=10DLC

exclude_10dlc_campaignboolean

When set to true, excludes all numbers that are associated with 10DLC campaigns

Default false

Example: exclude_10dlc_campaign=true

Headers

Content-Typestring

Example: application/json

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/numbers'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here are you dedicated numbers."

dataobject

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are you dedicated numbers.",
  "data": {
    "total": 2,
    "per_page": 15,
    "current_page": 1,
    "last_page": 1,
    "next_page_url": null,
    "prev_page_url": null,
    "from": 1,
    "to": 2,
    "data": [ … ]
  }
}

Purchase Dedicated Number

Request

Buy dedicated number

This endpoint allows you to purchase a dedicated phone number for messaging services. You can optionally include registration data for compliance purposes.

Request Body

Field	Type	Required	Description
dedicated_number	string	true	Phone number to purchase
type	string	true	Service type (sms, mms, voice)
registration_data	object	false	Registration data for compliance (AU SMS/MMS numbers only)

Registration Data Fields (Optional)

Field	Type	Required	Description
business_name	string	true	Name of the business (2 - 100 characters)
business_address	string	true	Business address (5 - 150 characters)
suburb	string	true	Suburb/City (2 - 50 characters)
postcode	string	true	Postal code (2 - 20 characters)
state	string	true	State/Province (2 - 50 characters)
contact_name	string	true	Contact person name (2 - 100 characters)
contact_number	string	true	Contact phone number (valid local or international phone number)
country	string	true	Country code (ISO 3166-1 alpha-2)

Path Parameters

Parameter	In	Type	Required	Description
dedicated_number	path	string	true	Phone number to purchase

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

This endpoint requires authentication,more info...

Security

basicAuth

Path

dedicated_numberstringrequired

Phone number to purchase

Example: +614197651956

Query

typestring

Example: type=sms

Headers

Content-Typestring

Example: application/json

Bodyapplication/jsonrequired

dedicated_numberstringrequired

Phone number to purchase

Example: "+614197651956"

typestringrequired

Service type for the number

Enum"sms""mms""voice"

Example: "sms"

registration_dataobject

Optional registration data for number compliance

Example: {"business_name":"ABD","business_address":"242 Exhibition Street","suburb":"Melbourne","postcode":"3000","state":"Victoria","contact_name":"ABD","contact_number":"+614197651956","country":"AU"}

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
     --header "Content-Type: application/json" \
     --request POST \
     --data '{
       "dedicated_number": "+614197651956",
       "type": "sms",
       "registration_data": {
         "business_name": "ABD",
         "business_address": "242 Exhibition Street",
         "suburb": "Melbourne",
         "postcode": "3000",
         "state": "Victoria",
         "contact_name": "ABD",
         "contact_number": "+614197651956",
         "country": "AU"
       }
     }' \
'https://rest.clicksend.com/v3/numbers/buy/{dedicated_number}'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here is your new number."

dataobject

Example: {"dedicated_number":"+12282060576","country":"US","price_total":"8.98","_price_setup":"22.22","_price_monthly":"11.11","_currency":{"currency_name_short":"USD","currency_prefix_d":"$","currency_prefix_c":"¢","currency_name_long":"US Dollar"}}

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here is your new number.",
  "data": {
    "dedicated_number": "+12282060576",
    "country": "US",
    "price_total": "8.98",
    "_price_setup": "22.22",
    "_price_monthly": "11.11",
    "_currency": { … }
  }
}

View Available Numbers

Request

Get all dedicated numbers by country

Parameters

Parameter	In	Type	Required	Description
country	path	string	true	Country code to search
search	query	string	false	Your search pattern or query.
search_type	query	integer(int32)	false	Your strategy for searching, 0 = starts with, 1 = anywhere, 2 = ends with.
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number of records per page

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

This endpoint requires authentication,more info...

Security

basicAuth

Path

countrystringrequired

Headers

Content-Typestring

Example: application/json

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/numbers/search/{country}'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here are some numbers."

dataArray of objects

Example: [{"country":"AU","country_name":"Australia","dedicated_number":"+61280662298","price_setup":"0.0000","price_monthly":"20.7100","price_total":"20.7100","address_requirement":"local"},{"country":"AU","country_name":"Australia","dedicated_number":"+61280662299","price_setup":"0.0000","price_monthly":"20.7100","price_total":"20.7100","address_requirement":"local"}]

_currencyobject(currency)

The parameters related to currency.

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are some numbers.",
  "data": [
    { … },
    { … }
  ],
  "_currency": {
    "currency_name_short": "AUD",
    "currency_prefix_d": "$",
    "currency_prefix_c": "c",
    "currency_name_long": "Australian Dollars"
  }
}

Register Numbers

Request

This endpoint is currently only available for Canada 10DLC number registration.

Registers a number that requires additional verification information. This endpoint facilitates the registration process for numbers requiring special compliance documentation.

After submission, ClickSend's compliance team will review the registration and notify you of the approval status.

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

This endpoint requires authentication,more info...

Security

basicAuth

Path

number_typestringrequired

The type of number being registered

Example: 10dlc

country_codestring= 2 characters^[A-Z]{2}$required

Two-character ISO country code

Example: US, CA

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

full_namestringrequired

Legal full name of the individual registering the number. Must be a personal name, not a business name.

Example: "John Doe"

company_namestringrequired

Legal business name of the organization requesting registration

Example: "ClickSend"

emailstringrequired

Contact email address for registration communications and notifications

Example: "john.doe@clicksend.com"

website_urlstringrequired

Official business website URL

Example: "https://clicksend.com"

sample_messagestringrequired

Representative example of messages that will be sent using this number

Example: "Get 20% off on your next purchase! Visit our website for details."

primary_use_casestringrequired

Primary intended purpose for the registered number (e.g., Marketing, Notifications, Authentication)

Example: "Marketing"

company_numberstringrequired

Official support phone number of the organization requesting registration

Example: "+1-800-555-0199"

area_codestringrequired

Your area codes, please provide your top 3 area codes in case your 1st choice is not available

Example: "416, 647, 905"

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "    {
        \"full_name\": \"John Doe\",
        \"company_name\": \"Clicksend\",
        \"email\": \"john.doe@clicksend.com\",
        \"website_url\": \"https://clicksend.com\",
        \"sample_message\": \"Get 20% off on your next purchase! Visit our website for details.\",
        \"primary_use_case\": \"Marketing\"
    }" \
'https://rest.clicksend.com/v3/numbers/registrations/number-types/{number_type}/country/{country_code}'

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: "10DLC number registration notification sent successfully."

dataobject or null

Example: null

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Number registration notification sent successfully.",
  "data": null
}

Numbers

View Your Numbers

Request

Parameters

Responses

Was this helpful?

Purchase Dedicated Number

Request

Request Body

Registration Data Fields (Optional)

Path Parameters

Responses

Was this helpful?

View Available Numbers

Request

Parameters

Responses

Was this helpful?

Register Numbers

Request

Responses

Was this helpful?

Numbers

View Your Numbers

Request

Parameters

Responses

Was this helpful?

Purchase Dedicated Number

RequestExpand all

Request Body

Registration Data Fields (Optional)

Path Parameters

Responses

Was this helpful?

View Available Numbers

Request

Parameters

Responses

Was this helpful?

Register Numbers

Request

Responses

Was this helpful?

Request