Documentation

1. Overview

This document describes the Cloud Aten APIs, which are meant to be used by back-end servers. When using the APIs, requests should be sent with the HTTP header: Content-Type: application/json;charset=utf-8;

1.1 Authentication

To make API calls, send the API key in the X-API-Key HTTP header: X-API-Key: YOUR_API_KEY.

1.2 Unauthorized access

HTTP Status Code: 401

Response Body:

{
    "timestamp": 1545033511912,
    "status": 401,
    "error": "Unauthorized",
    "message": "INVALID_API_KEY",
    "path": "/v1/account/balance"
}

1.3 Request structure

Your platform should receive a response with a 200 HTTP status code.

Basic response value:

Name	Type	Description
code	int	A request is successfully accepted with a code of 0. Otherwise, it indicates that something goes wrong.
msg	String	When successfully requested, success is return. Otherwise, it describes error details.

Other return value:
When the parameter is not found, it will not be included in the JSON returned values, which means the filed is ignored when JSON serialization.

2. SMS API

2.1 Send a message

POST https://api.cloudaten.com/v1/sms/send_messages

curl -X POST 'https://api.cloudaten.com/v1/sms/send_messages' -H 'X-API-Key:YOUR_API_KEY' -H 'Content-Type:application/json' -d '{"mobile":"+447901614024","text":"Hello,world"}'

Required parameters

Parameters	Required	Type	Description	Example
mobile	true	String	Mobile number in E.164 format	+447901614024
text	true	String	SMS body	Hello world
signature	false	String	This parameter is required for Chinese mainland SMS. You must specify an approved signature such as YCSMS. It will be added to the beginning of SMS body and wrapped with 【】, e.g. 【YCSMS】Hello world.	YCSMS
uid	false	String	Your system’s unique ID attached to the message, such as an order number or the serial number.	1234567
callback_url	false	String	Delivery report push url	https://www.example.com/callback

Request Example

{
    "mobile": "+447901614024",
    "text": "hello,world!"
}

Response parameters

Parameters	Required	Type	Description	Example
data	false	The message object	The message object occurs when the request is successfully created.

The message object

Parameters	Required	Type	Description	Example
region_code	true	String	Country code	CN
status	true	String	SMS status.Please see details in appendix	accepted
price	true	float	The price the message was billed with. The price will be billed per message you send.	0.03
count	true	int	Quantity of SMS	1
mobile	true	String	Mobile number	+447901614024
sid	true	String	Unique id in int64 value format	3310228982
create_timestamp	true	timestamp	The timestamp at which this sms is created in milliseconds	1541580135423

Response example:
Accepted

{
    "code": 0,
    "data": {
        "status": "accepted",
        "price": 0.1582,
        "count": 2,
        "mobile": "+447901614024",
        "sid": "3321910440",
        "region_code": "JP",
        "create_timestamp": 1545040926268
    },
    "msg": "SUCCESS"
}

Rejected

{
    "code": 2,
    "msg": "BAD_ARGUMENT The mobile is unverified"
}

2.2 Delivery report

Your platform should respond with a 200 HTTP status code. When our platform doesn’t receive a 200 HTTP status code, we will try to deliver the report again (up to 5 times), which are 1min 10min 60min 24h 72h.

Push method:

POST <callback_url>

curl example：
curl -X POST 'https://YOUR_CALLBACK_URL' -H 'Content-Type: application/json' -d '{"sid":"3310228982","status":"delivered","status_timestamp":1541580135423,"mobile":"+447901614024"}'

Push parameters

Parameters	Required	Type	Description
sid	true	String	SMS id
status	true	String	SMS status
status_timestamp	true	timestamp	The timestamp at which the delivery report for this SMS was received in milliseconds
mobile	true	String	Mobile number
uid	false	String	Your system’s unique ID attached to the message
error_code	false	String
error_msg	false	String

2.3 SMS records

GET https://api.cloudaten.com/v1/sms/list

Request frequency limit:once every minute

curl -X GET 'https://api.cloudaten.com/v1/sms/list?page_size=20' -H 'X-API-Key:YOUR_API_KEY'

Query

Parameters	Required	Type	Description
page_no	true	int	Page index of the results to return. The first page is 1.
page_size	true	int	Number of results per page. Default page size is 20. Max page size is 5000.
from	true	timestamp	Starting time in milliseconds
until	true	timestamp	Ending time in milliseconds
sid	false	String	Other value will be ignored when sid is passed in.

Response parameters

Parameters	Required	Type	Description
count	true	int	Quantity
page_no	true	int	Page index of the results to return. The first page is 1.
page_size	true	int	Number of results per page. Default page size is 20. Max page size is 5000.
data	true	Array	The message object
msg	true	String
code	true	int	Return status

The message object

Parameters	Required	Type	Description	Example
region_code	true	String	Country code	CN
status	true	String	SMS status.Please see details in appendix	accepted
price	true	float	The price the message was billed with. The price will be billed per message you send.	0.03
currency	true	String	Currency code	USD
count	true	int	Quantity of sms	1
mobile	true	String	Mobile number	+447901614024
sid	true	String	Unique id in int64 value format	3310228982
text	true	String	The content of SMS
error_code	false	String	Error code when sms is undeliverable.	YC:NO BALANCE
create_timestamp	true	timestamp	The timestamp at which this sms is created in milliseconds	1541580135423
status_timestamp	false	timestamp	The timestamp at which the delivery report for this sms was received in milliseconds	1541580135423

Response example 1

{
    "code": 0,
    "data": [
        {
            "status": "delivering",
            "price": 0.0087,
            "count": 1,
            "mobile": "15158567221",
            "sid": "3321910100",
            "text": "demoData??????",
            "region_code": "CN",
            "create_timestamp": 1545038673722,
            "status_timestamp": 1545038680937
        }
    ],
    "msg": "SUCCESS",
    "count": 0,
    "page_no": 1,
    "page_size": 1
}

Response example 2 (no data):

{
    "code": 0,
    "data": [],
    "msg": "SUCCESS",
    "count": 0,
    "page_no": 1,
    "page_size": 1
}

3.Voice API

Voice verification code can easily reach recipients who are unable to receive SMS due to various reasons. Via our powerful and reliable Voice API, the voice verification code is able to achieve both high speed and accuracy simultaneously.

Note: Each recipient can only receive one voice call every 30 seconds. The voice OTP will be billed per voice call and automatically repeated twice.

3.1 Send voice code

HTTP request line

POST https://api.cloudaten.com/v1/voice/send

cURL example

curl -X POST 'https://api.cloudaten.com/v1/voice/send' -H 'X-API-Key:YOUR_API_KEY' -H 'Content-Type:application/json' -d '{"mobile":"+447901614024","verification_code":"1234"}'

Request parameters

Parameters	Required	Type	Description	Example
mobile	true	String	Mobile number in E.164 format	+447901614024
verification_code	true	String	Verification code: 4~6 digits	123456
language	false	String	Language code. If not specified, language will be set as en by default. Notably, in certain countries or regions, language will be automatically set as the local language due to the regional restrictions. Other applicable languages: zh: Chinese en: English id: Indonesian vi: Vietnamese tr: Turkish ru: Russian de: German fr: French it: Itailan pt: Portuguese	en
uid	false	String	Your system’s unique ID attached to the message, such as an order number or the serial number.	1234567
callback_url	false	String	Delivery report URL. You need to provide an URL and we will push the updated status report to your server in time.	https://www.example.com/callback

Note:

Voice call templates of different languages are shown in the table below.

Lanugage Code (ISO 639-1)	Language Name	Voice Content
zh	Chinese	您的验证码是 1-2-3-4
en	English	Your verification code is 1-2-3-4
id	Indonesian	Kode verifikasi Anda adalah 1-2-3-4
vi	Vietnamese	Mã xác minh của bạn là 1-2-3-4
tr	Turkish	Doğrulama kodunuz 1-2-3-4
ru	Russian	Ваш проверочный код 1-2-3-4
de	German	Ihr Bestätigungscode lautet 1-2-3-4
fr	French	Votre code de vérification est 1-2-3-4
it	Italian	Il tuo codice di verifica è 1-2-3-4
pt	Portuguese	O seu código de verificação é 1-2-3-4

Response parameters

Parameters	Required	Type	Description	Example
data	false	The message object	The message object occurs when the request is successfully created.

The message object

Parameters	Required	Type	Description	Example
region_code	true	String	Country code	CN
status	true	String	Message status. Please view details in appendix.	accepted
price	true	float	The price the message was billed with. The price will be billed per message you send.	0.03
count	true	int	Quantity of message	1
mobile	true	String	Mobile number	+447901614024
sid	true	String	Unique id in int64 value format	3310228982
create_timestamp	true	timestamp	The timestamp at which this message is created in milliseconds.	1541580135423

Response example
Accepted

{
    "code": 0,
    "data": {
        "status": "accepted",
        "price": 0.1582,
        "count": 2,
        "mobile": "+447901614024",
        "sid": "3321910440",
        "region_code": "JP",
        "create_timestamp": 1545040926268
    },
    "msg": "SUCCESS"
}

3.2 Voice records

HTTP request line

GET https://api.cloudaten.com/v1/voice/list

cURL example

curl -X GET 'https://api.cloudaten.com/v1/voice/list?page_size=20' -H 'X-API-Key:YOUR_API_KEY'

Query parameters

Parameters	Required	Type	Description
page_no	true	int	Page index of the results to return. The first page is 1.
page_size	true	int	Number of results per page. Default page size is 20. Max page size is 100.
from	true	timestamp	Starting time in milliseconds
until	true	timestamp	Ending time in milliseconds
sid	false	String	Message id

Response parameters

Parameters	Required	Type	Description
count	true	int	Quantity
page_no	true	int	Page index of the results to return. The first page is 1.
page_size	true	int	Number of results per page. Default page size is 20. Max page size is 100.
data	true	Array	The message object
msg	true	String
code	true	int	Return status

The message object

Parameters	Required	Type	Description	Example
region_code	true	String	Country code	CN
status	true	String	SMS status. Please view details in appendix.	accepted
price	true	float	The price the message was billed with. The price will be billed per message you send.	0.03
currency	true	String	Currency code	USD
count	true	int	Quantity of sms	1
mobile	true	String	Mobile number	+447901614024
verification_code	true	String	The verification code your send	123456
sid	true	String	Unique id in int64 value format	3310228982
error_code	false	String	Error code when the message is undeliverable.	YC:NO BALANCE
create_timestamp	true	timestamp	The timestamp at which this sms is created in milliseconds	1541580135423
status_timestamp	false	timestamp	The timestamp at which the delivery report for this message was received in milliseconds.	1541580135423

Response example 1

{
    "code": 0,
    "data": [
        {
            "status": "delivering",
            "price": 0.0087,
            "count": 1,
            "mobile": "15158567221",
            "sid": "3321910100",
            "verification_code": "123456",
            "region_code": "CN",
            "create_timestamp": 1545038673722,
            "status_timestamp": 1545038680937
        }
    ],
    "msg": "SUCCESS",
    "count": 0,
    "page_no": 1,
    "page_size": 1
}

3.3 Voice delivery report

Your platform should respond with a 200 HTTP status code. When our platform doesn’t receive a 200 HTTP status code, we will try to deliver the report again (up to 5 times), which are 1min 10min 60min 24h 72h.

HTTP request line

POST <callback_url>

cURL example
curl -X POST 'https://YOUR_CALLBACK_URL' -H 'Content-Type: application/json' -d '{"sid":"3310228982","status":"delivered","status_timestamp":1541580135423,"mobile":"+447901614024"}'

Push parameters

Parameters	Required	Type	Description
sid	true	String	Message id
status	true	String	Message status
status_timestamp	true	timestamp	The timestamp at which the delivery report for this message was received in milliseconds
mobile	true	String	Mobile number
uid	false	String	Your system’s unique ID attached to the message
error_code	false	String
error_msg	false	String

4.Account

4.1 Balance API

GET https://api.cloudaten.com/v1/account/balance

curl -X GET 'https://api.cloudaten.com/v1/account/balance' -H 'X-API-Key:YOUR_API_KEY'

Response parameters

Parameters	Required	Type	Description
currency	true	int	Currency code, for example USD
amount	true	String	Balance in realtime

Response example 1

{
    "code": 0,
    "data": {
        "currency": "USD",
        "amount": 10000010190.07658
    },
    "msg": "SUCCESS"
}

Appendix

Appendix 1.code

Error_code	Error_msg	Description
-101	JSON_PARSE_ERROR	Invalid JSON format.
-100	UNKNOWN_ERROR	Unknown error. Please contact us for technical support.
-3	NO_CURRENCY_SETTING	You have no currency settings.
-2	NO_BASE_PRICE	The price of this destination is not provided.
-1	INVALID_API_KEY	The apikey could not be verified.
0	SUCCESS	The message was successfully accepted for delivery.
1	ARGUMENT_MISSING	Your request is missing the required parameters.
2	BAD_ARGUMENT	The value of parameters is invalid. For example, invalid phone number format
3	NO_BALANCE	Insufficient balance
52	SENSITIVE_WORD	Unwanted content sent to the destination is found.

Appendix 2.status

Status|Description|
—|—|—
Accepted|Cloud Aten has received your API request to send a message|
Failed|The message could not be sent. This can happen for reasons including insufficient balance or invalid channels. Error code: YC:XXX|
Sent|Cloud Aten is in the process of dispatching your message and waiting for delivery report to return.|
Delivered|Cloud Aten has received confirmation of message delivery.|
Undelivered|Failed to return by mobile carrier. Error code：OP:XXX|

Appendix 3.Error_code

Below are the descriptions of codes returned when SMS is undelivered:

Error_code	Error	Description
NO_BALANCE	No balance	Insufficient balance and transaction failed.
YC:NOOP	Invalid channel	Invalid channel. Cloud Aten will not charge the SMS.
UNDELIV_0001	EC_UNKNOWN_SUBSCRIBER	The number does not exist or it has not been assigned to any active subscriber in the operator’s user database.
UNDELIV_0009	EC_ILLEGAL_SUBSCRIBER	Illegal Subscriber
UNDELIV_0032	EC_SM_DELIVERY_FAILURE	SM Delivery Failure
EXPIRED_4100	EC_MESSAGE_CANCELED	The request was received, but has not been sent to the next instance within its validity period, and is expired with the appropriate error code EC_MESSAGE_CANCELED, or the same error code was reverted from the operator.
EXPIRED_1153	EC_NNR_NOTRANSLATIONFORTHISSPECIFICADDRESS	No Translation For This Specific Address
EXPIRED_0027	EC_ABSENT_SUBSCRIBER	The subscriber is offline in the network, as confirmed by the handset’s paging response. This is often due to the handset being switched off.
EXPIRED_0013	EC_CALL_BARRED	The subscriber is set to DND (Do Not Disturb) service, opting out of receiving any service traffic to their number.

Code Samples

Here are code samples for some coding languages.

Attention:

1. YOUR_API_KEY should be replaced with your real API key, which can be found in https://www.cloudaten.com/console/#/app/dashboard.
2. PHONE_NUMBER should be replaced with destination phone number in E.164 format, e.g. +447901614024.

Java

Send a message

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"mobile\": \"PHONE_NUMBER\",\n    \"text\": \"YOUR_MESSAGE\"\n}");
Request request = new Request.Builder()
  .url("https://api.cloudaten.com/v1/sms/send_messages")
  .method("POST", body)
  .addHeader("X-API-Key", "YOUR_API_KEY")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

OkHttp is used in this snippet. Add it to Maven pom.xml dependencies:

<dependency>
  <groupId>com.squareup.okhttp3</groupId>
  <artifactId>okhttp</artifactId>
  <version>3.14.9</version>
</dependency>

SMS logs

OkHttpClient client = new OkHttpClient().newBuilder().build();
Request request = new Request.Builder()
  .url("https://api.cloudaten.com/v1/sms/list?page_size=20&page_no=1")
  .method("GET", null)
  .addHeader("X-API-Key", "YOUR_API_KEY")
  .build();
Response response = client.newCall(request).execute();

Send voice code

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"mobile\": \"PHONE_NUMBER\",\n    \"verification_code\": \"YOUR_VERIFICATION_CODE\"\n}");
Request request = new Request.Builder()
  .url("https://api.cloudaten.com/v1/voice/send")
  .method("POST", body)
  .addHeader("X-API-Key", "YOUR_API_KEY")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Balance

OkHttpClient client = new OkHttpClient().newBuilder().build();
Request request = new Request.Builder()
  .url("https://api.cloudaten.com/v1/account/balance")
  .method("GET", null)
  .addHeader("X-API-Key", "YOUR_API_KEY")
  .build();
Response response = client.newCall(request).execute();

NodeJs

Send a message

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.cloudaten.com/v1/sms/send_messages',
  'headers': {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "mobile": "PHONE_NUMBER",
    "text": "YOUR_MESSAGE"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

SMS logs

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://api.cloudaten.com/v1/sms/list?page_size=20&page_no=1',
  'headers': {
    'X-API-Key': 'YOUR_API_KEY'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Send voice code

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.cloudaten.com/v1/voice/send',
  'headers': {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "mobile": "PHONE_NUMBER",
    "verification_code": "YOUR_VERIFICATION_CODE",
    "language": "en"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Balance

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://api.cloudaten.com/v1/account/balance',
  'headers': {
    'X-API-Key': 'YOUR_API_KEY'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

PHP

Send a message

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudaten.com/v1/sms/send_messages',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array('mobile' => 'PHONE_NUMBER', 'text' => 'YOUR_MESSAGE')),
  CURLOPT_HTTPHEADER => array(
    'X-API-Key: YOUR_API_KEY',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

SMS logs

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudaten.com/v1/sms/list?page_size=20&page_no=1',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'X-API-Key: YOUR_API_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Send voice code

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudaten.com/v1/voice/send',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array('mobile' => 'PHONE_NUMBER', 'verification_code' => 'YOUR_VERIFICATION_CODE', 'language' => 'en')),
  CURLOPT_HTTPHEADER => array(
    'X-API-Key: YOUR_API_KEY',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Balance

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudaten.com/v1/account/balance',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'X-API-Key: YOUR_API_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

Send a message

import requests
import json

url = "https://api.cloudaten.com/v1/sms/send_messages"

payload = json.dumps({
  "mobile": "PHONE_NUMBER",
  "text": "YOUR_MESSAGE"
})
headers = {
  'X-API-Key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Send voice code

import requests
import json

url = "https://api.cloudaten.com/v1/voice/send"

payload = json.dumps({
  "mobile": "PHONE_NUMBER",
  "verification_code": "YOUR_VERIFICATION_CODE"
})
headers = {
  'X-API-Key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

SMS logs

import requests

url = "https://api.cloudaten.com/v1/sms/list?page_size=20&page_no=1"

payload={}
headers = {
  'X-API-Key': 'YOUR_API_KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Balance

import requests

url = "https://api.Cloudaten.com/v1/account/balance"

payload={}
headers = {
  'X-API-Key': 'YOUR_API_KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)