Introduction

This page will help you get started with CITCALL API.

This document will provide instructions on how to integrate CITCALL services by using CITCALL HTTP application programming interface (HTTP API). Use HTTP API for making miscall and sending SMS messages. CITCALL's API is based on REST standards, enabling you to use your browser for accessing URLs. Use any HTTP client in any programming language to interact with our API.

Authorization

The majority of requests to CITCALL’s API require authentication. That can be done in two steps:

1. IP Whitelist

   You can register your IP(s) at our Dashboard on option menu.

2. Authorization Methods

   The majority of requests to CITCALL’s API require authentication. That can be done by setting the Authorization HTTP header. The Authorization header must include a type and the credentials themselves.

   Authorization: <type> <credentials>

   Type	Format	Notes
   Apikey	Citcall Generated Apikey	Recommended
   Basic	Base64 encoded userid and password combination	Not recommended because the password is included in every request.

   API key authorization

   You can find out more about API key creation and management at our Dashboard on API menu.

   Example:

   Authorization header: "Apikey {YOUR_APIKEY}"

   Basic authorization

   Basic authorization type can be used in situations when the API key is not available. For example, API methods for generating API keys should be authenticated with the Basic type.

   In this case, the credentials included in the Authorization header should be a Base64 encoded username and password combination. More formally, basic authentication header can be constructed in two steps:

   • Username and password are concatenated using the colon (:) as a separator username:apikey.
   • The resulting string is encoded using the RFC2045-MIME variant of Base64.
   • Encoded string is added as credentials after the "Basic" type.

Example:

Userid: "citcall"
Password: "citcall"

Concatenated string: "citcall:citcall"

Base64 encoded string: "Y2l0Y2FsbDpjaXRjYWxs"

Authorization header: "Basic Y2l0Y2FsbDpjaXRjYWxs"

API reference

Misscall OTP

{
	"msisdn": "6281234567890",
	"retry": 0
}

				

curl -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: Apikey {YOUR_APIKEY}' \
 -d '{
 	"msisdn":"6281234567890",
 	"retry":"0"
 }' https://citcall.pub/v3/motp

				

<?php
$apikey = '{YOUR_APIKEY}';

$base_url = 'https://citcall.pub';
$version = '/v3';
$action = '/motp';

$url = $base_url . $version . $action ;
$data = array(
	'msisdn' => '6281234567890',
	'retry' => 0
);

$content = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($ch,CURLOPT_POSTFIELDS,$content);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HTTPHEADER,array(
	'Content-Type: application/json',
	'Authorization: Apikey '. $apikey,
	'Content-Length: '.strlen($content))
);
$response  = curl_exec($ch);
$err  = curl_error($ch);

curl_close($ch);

if ($err) {
  echo 'cURL Error #:'. $err;
} else {
  echo $response;
}

				

HttpResponse<String> response =  Unirest.post("https://citcall.pub/v3/motp")
.header("content-type","application/json")
.header("Authorization","Apikey {YOUR_APIKEY}")
.body("{\"msisdn\":\"6281234567890\",\"retry\":\"0\"}")
.asString();

				

var data = JSON.stringify({
  "msisdn": "6281234567890",
  "retry": "0"
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange",function(){
  if(this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://citcall.pub/v3/motp");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("Authorization", "Apikey {YOUR_APIKEY}");

xhr.send(data);

				

The above command returns JSON structured like this:

{
	"rc": 0,
	"trxid": "20170709083044690027711524",
	"msisdn": "+6281234567890",
	"token": "622130401234",
	"gateway": 0
}

				

You can use our API to provide miscall to the MSISDN

HTTP Request

POST https://citcall.pub/v3/motp

OR

POST https://pub.citcall.com/v3/motp

Request structure

To provide miscall using the Citcall API you need to submit a JSON object to the url defined above. The JSON object takes the following properties:

Retry description:

Request Body

Below is a more detailed description of the parameters in the SMS request body (JSON object submitted to the API)

• msisdn

This value is the destination phone number for receive a call. The destination should be submitted following the international format: it should include the country code (the leading + sign can be omitted but this is not an obligation) and the leading 0 of the local format only will send to indonesia country.

• retry

Retry Sequence (0,1,2,3,4).

Response

The response returns the following:

• rc: Respon Code.

Possible status values:

Code	Description
00	Ok
99	wrong method
98	Authorization failed
88	missing parameter
77	userid not found
06	unknown error / failed
34	Service temporary unavilable
76	Wrong Password
66	Maintenance in progress
14	insuficient amount

• trxid: unique message ID automatically generated by Citcall.
• msisdn: End-User mobile number
• token: Number received by the end user.
• gateway: Gateway number for the trial number of time.
• client_id: Your custom identifier for the request. (if exist on request)

SMS

{	
	"msisdn": "6281234567890",
	"senderid": "citcall",
	"text": "Hello World!"
}

				

curl -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: Apikey {YOUR_APIKEY}' \
 -d '{ 	
 	"msisdn":"6281234567890",
	"senderid":"citcall",
 	"text":"Hello World!"
 }' https://citcall.pub/v3/sms

				

<?php
$apikey = '{YOUR_APIKEY}';

$base_url = 'https://citcall.pub';
$version = '/v3';
$action = '/sms';

$url = $base_url . $version . $action;
$data = array(
	'msisdn' => '6281234567890',
	'senderid' => 'citcall',
	'text' => 'Hello World!'
);

$content = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($ch,CURLOPT_POSTFIELDS,$content);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HTTPHEADER,array(
	'Content-Type: application/json',
	'Authorization: Apikey '. $apikey,
	'Content-Length: '.strlen($content))
);
$response  = curl_exec($ch);
$err  = curl_error($ch);

curl_close($ch);

if ($err) {
  echo 'cURL Error #:'. $err;
} else {
  echo $response;
}

				

HttpResponse<String> response =  Unirest.post("https://citcall.pub/v3/sms")
.header("content-type","application/json")
.header("Authorization","Apikey {YOUR_APIKEY}")
.body("{\"msisdn\":\"6281234567890\",\"senderid\":\"citcall\",\"text\":\"Hello World!\"}")
.asString();

				

var data = JSON.stringify({
  "msisdn": "6281234567890",
  "senderid": "citcall",
  "text": "Hello World!"
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange",function(){
  if(this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://citcall.pub/v3/sms");
xhr.setRequestHeader("content-type"", "application/json");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("Authorization", "Apikey {YOUR_APIKEY}");

xhr.send(data);

				

The above command returns JSON structured like this:

{
	"rc": 0,
	"info": "Ok",
	"sms_count": 1,	
	"senderid": "citcall",
	"msisdn": "6281234567890",
	"text": "Hello World!",
	"trxid": "20170530152922",
	"currency": "IDR",
	"price": "450"
}

				

You can use our API to send single SMS requests to deliver your text messages to any country or operator in the World using your Citcall account.

HTTP Request

POST https://citcall.pub/v3/sms

OR

POST https://pub.citcall.com/v3/sms

Request structure

To send a single SMS using the Citcall SMS API you need to submit a JSON object to the url defined above. The JSON object takes the following properties:

Request Body

Below is a more detailed description of the parameters in the SMS request body (JSON object submitted to the API)

• msisdn

This value is the destination phone number for the SMS. The destination should be submitted following the international format: it should include the country code (the leading + sign can be omitted but this is not an obligation) and the leading 0 of the local format only will send to indonesia country.

• senderid

The source value can also be called senderID or TPOA. It is the from address that will be used when delivering the SMS to the handset.It can take different format

• Alphanumeric (example: citcall): this is the case when a source is composed of an alphanumeric string (max 11 characters: letters from the ASCII character set, digits and the space character). Alphanumeric sources are generally used for branded SMS to help the SMS receiver to identify the brand or services which originated the SMS.
• Numeric(example: +62812345678): this the case when a source is composed of a string made purely of digits (max 17 chars). It can also start with the + sign. Numeric sources ar generally used when the originator intends to receive an answer to the SMS as it is interpreted as a regular phone number by the destination handset
NB - Limitations: senderid is only available which is registered for you
• text

The text or the message (or SMS body) is the main part of your SMS: it is what is going to be displayed on the destination handset.

Response

The response returns the following:

• rc: Respon Code.

Possible status values:

Code	Description
00	Ok
99	wrong method
98	Authorization failed
88	missing parameter
77	userid not found
44	senderid closed
06	unknown error / failed
34	Service temporary unavilable
76	Wrong Password
66	Maintenance in progress
14	insuficient amount

• info: This field describes the status code and provides additional information explaining the status.
• sms_count: number of parts in the SMS (based on characters count)
• senderid: senderid from request.
• msisdn: Recipients information.
• text: The text or the message (or SMS body) information.
• trxid: Unique message ID automatically generated by Citcall.
• currency: Billing currency for price.
• price: Price billed by CITCALL for the Transaction.
• client_id: Your custom identifier for the request. (if exist on request)

SMS OTP

{	
	"msisdn": "6281234567890",
	"senderid": "citcall",
	"text": "Hello World!"
}

				

curl -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: Apikey {YOUR_APIKEY}' \
 -d '{ 	
 	"msisdn":"6281234567890",
	"senderid":"citcall",
 	"text":"Hello World!"
 }' https://citcall.pub/v3/smsotp

				

<?php
$apikey = '{YOUR_APIKEY}';

$base_url = 'https://citcall.pub';
$version = '/v3';
$action = '/smsotp';

$url = $base_url . $version . $action;
$data = array(
	'msisdn' => '6281234567890',
	'senderid' => 'citcall',
	'text' => 'Hello World!'
);

$content = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($ch,CURLOPT_POSTFIELDS,$content);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HTTPHEADER,array(
	'Content-Type: application/json',
	'Authorization: Apikey '. $apikey,
	'Content-Length: '.strlen($content))
);
$response  = curl_exec($ch);
$err  = curl_error($ch);

curl_close($ch);

if ($err) {
  echo 'cURL Error #:'. $err;
} else {
  echo $response;
}

				

HttpResponse<String> response =  Unirest.post("https://citcall.pub/v3/smsotp")
.header("content-type","application/json")
.header("Authorization","Apikey {YOUR_APIKEY}")
.body("{\"msisdn\":\"6281234567890\",\"senderid\":\"citcall\",\"text\":\"Hello World!\"}")
.asString();

				

var data = JSON.stringify({
  "msisdn": "6281234567890",
  "senderid": "citcall",
  "text": "Hello World!"
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange",function(){
  if(this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://citcall.pub/v3/smsotp");
xhr.setRequestHeader("content-type"", "application/json");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("Authorization", "Apikey {YOUR_APIKEY}");

xhr.send(data);

				

The above command returns JSON structured like this:

{
	"rc": 0,
	"info": "Ok",
	"sms_count": 1,	
	"senderid": "citcall",
	"msisdn": "6281234567890",
	"text": "Hello World!",
	"trxid": "20170530152922",
	"currency": "IDR",
	"price": "450"
}

				

You can use our API to send single SMS requests to deliver your text messages to any country or operator in the World using your Citcall account.

HTTP Request

POST https://citcall.pub/v3/smsotp

OR

POST https://pub.citcall.com/v3/smsotp

Request structure

To send a single SMS using the Citcall SMS API you need to submit a JSON object to the url defined above. The JSON object takes the following properties:

• Default

Parameter	Type	Description	Required
msisdn	string	Destination phone number	Required
senderid	string	Your Registered Senderid	Required
text	string	SMS body (ie: text of the message)	Required
callback_url	uri	Webhook URL where delivery status for the result will be posted (Overwrites your default account callback URL).	no
client_id	string	Client managed id for the request : your own unique reference	no

Request Body

Below is a more detailed description of the parameters in the SMS request body (JSON object submitted to the API)

• msisdn

This value is the destination phone number for the SMS. The destination should be submitted following the international format: it should include the country code (the leading + sign can be omitted but this is not an obligation) and the leading 0 of the local format only will send to indonesia country.

• senderid

The source value can also be called senderID or TPOA. It is the from address that will be used when delivering the SMS to the handset.It can take different format

• Alphanumeric (example: citcall): this is the case when a source is composed of an alphanumeric string (max 11 characters: letters from the ASCII character set, digits and the space character). Alphanumeric sources are generally used for branded SMS to help the SMS receiver to identify the brand or services which originated the SMS.
• Numeric(example: +62812345678): this the case when a source is composed of a string made purely of digits (max 17 chars). It can also start with the + sign. Numeric sources ar generally used when the originator intends to receive an answer to the SMS as it is interpreted as a regular phone number by the destination handset
NB - Limitations: senderid is only available which is registered for you
• text

The text or the message (or SMS body) is the main part of your SMS: it is what is going to be displayed on the destination handset.

Response

The response returns the following:

• rc: Respon Code.

Possible status values:

Code	Description
00	Ok
99	wrong method
98	Authorization failed
88	missing parameter
77	userid not found
44	senderid closed
06	unknown error / failed
34	Service temporary unavilable
76	Wrong Password
66	Maintenance in progress
14	insuficient amount

• info: This field describes the status code and provides additional information explaining the status.
• sms_count: Array of sent message objects, one object per every message.
• senderid: senderid from request.
• msisdn: Recipients information.
• text: The text or the message (or SMS body) information.
• trxid: Unique message ID automatically generated by Citcall.
• currency: Billing currency for price.
• price: Price billed by CITCALL for the Transaction.
• client_id: Your custom identifier for the request. (if exist on request)

Callback

Callback or Delivery Report (DR) are webhooks for delivery statuses: POST requests sent by the Citcall platform either in JSON format to the callback URL configured for your account.

Whenever a request has a new delivery status associated with the delivery stage it is in, Citcall sends out a POST request with the new status to the callback URL.

You can configure your default callback URL for your account at our Dashboard on API menu.

You can also overwrite the default callback URL on by specifying a different callback_url value in your API requests.

Miscall OTP Callback

Parameters of Miscall OTP Callback:

SMS Callback

Parameters of SMS Callback:

SMS OTP Callback

Parameters of SMS OTP Callback:

Response Code

Appendix

Table of dial code

UI/UX Guideline

You can check our UI/UX guideline for more refference. click here to see our UI/UX guideline.

Code Repository

You can check our GIthub repository to see our sample code. click here to see our repository.

android auto-verify

You can check our GIthub repository to see our sample android auto-verify. click here to see our android auto-verify repository.

android permission guide

You can check our android permission guide. click here to see.