Getting Started Edit

Welcome to ShoutOUT Developer Documentation.

This API document is designed for those interested in developing for our platform.

This API is still under development and will evolve.

APIs Edit

Authentication Edit

You need to be authenticated for all API requests. You can generate an API key in our developer dashboard.

Add the API key to all requests as a header

Nothing will work unless you include this API key

Errors Edit

All errors will return JSON in the following format:

{
  "message": "error message here"
}

Introduction Edit

Integrate Lite API to your application to begin sending and receiving messages to your contacts from your system.

Incoming SMS

Outgoing SMS

Official SDKs Edit

NodeJs

PHP

Framework Libraries Edit

Framework libraries can get you up and running with the ShouOUT APIs quickly and easily in your framework of choice.

LARAVEL

/messages Edit

Send SMS Message (Recommended method)

Parameters

source

Sender mask (Alias)

destinations

Mobile numbers in E.164 format

content

JSON object with key "sms" and the message content in the value

transports

String array, ["sms"]

Message will be logged and can be viewed from the dashboard

Send sms message(s) to the destination addresse(s)

curl --location --request POST 'https://api.getshoutout.com/coreservice/messages' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "source": "ShoutDEMO",
  "destinations": ["94777123456"],
  "content": {
      "sms": "Sent via SMS Gateway"
  },
  "transports": ["sms"]
}'

$.post("https://api.getshoutout.com/coreservice/messages", {
  "source": "ShoutDEMO",
  "destinations": ["+94777123456"],
  "content": {
    "sms":"Sent via SMS Gateway"
  },
  "transports":["sms"]
}, function(data) {
  alert(data);
});

var message = {
  source: 'ShoutDEMO',
  destinations: ['94777123456'],
   content: {
       sms: 'Sent via SMS Gateway'
  },
   transports: ['sms']
};
client.sendMessage(message, (error, result) => {
  if (error) {
      console.error('error ', error);
  } else {
      console.log('result ', result);
  }
});

<?php

require __DIR__ . '/vendor/autoload.php';

use Swagger\Client\ShoutoutClient;

$apiKey = 'XXXXXXXXX.XXXXXXXXX.XXXXXXXXX';

$client = new ShoutoutClient($apiKey,true,false);


$message = array(
    'source' => 'ShoutDEMO',
    'destinations' => ['94777123456'],
    'content' => array(
        'sms' => 'Sent via SMS Gateway'
    ),
    'transports' => ['SMS']
);

try {
    $result = $client->sendMessage($message);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when sending message: ',  $e->getMessage(), PHP_EOL;
}

?>

/messages Edit

Send SMS Message (Use this method only if the POST method can't be used)

Parameters

source

String (Sender mask/alias)

destinations

Array (Array of mobile numbers in E.164 format)

content

String (SMS message content)

apiKeyId

String (ID of the API Key)

Message will be logged and can be viewed from the dashboard

Send sms message(s) to the destination addresse(s)

curl --request GET 'https://api.getshoutout.com/coreservice/messages?source=ShoutDEMO&destinations[]=94777123456&content=Test%20SMS&apiKeyId=xxxxxxx-xxxx-xxx-xxx-xxxxx'

var settings = {
  "url": "https://api.getshoutout.com/coreservice/messages?source=ShoutDEMO&destinations[]=94777123456&content=Test SMS&apiKeyId=xxxxxxx-xxxx-xxx-xxx-xxxxx",
  "method": "GET"
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

/logs/{id} Edit

Get log for message id

Parameters

id

Message id

Message id should be mentioned on the path

curl -X GET 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Apikey <API_KEY>' 
'https://api.getshoutout.com/campaignservice/logs/{id}'

$.get("https://api.getshoutout.com/campaignservice/logs/{id}", {
}, function(data) {
  alert(data);
});

Introduction Edit

Build and manage your contacts and their respective activities using our CRM API service. This enables developers to integrate our CRM to any system or application.

User Registration

1. Merchant submit the customer details to loyalty service using one of the following
   • Hosted registration form
   • Embedded registration form
   • Direct API call
2. Optionally customer receives a SMS or an Email with a welcome message and details of his/her loyalty account

Point Collection

1. Merchant record customer transactions in the PoS system
2. PoS system sends the bill value along with other transaction details to the collect points API endpoint of ShoutOUT Loyalty service
3. ShoutOUT Loyalty service calculate the points for the bill value and accumulate it to the customer points pool
4. Optionally a SMS or an Email is sent to the customer with the details of the transaction and points accumulation.

RESTful API

We have a very simple RESTful API with mainly four endpoints. And all endpoints receives request data as JSON objects.

1. Register User
2. Load User
3. Collect Points
4. Redeem Points

/contacts Edit

Create or update contact(s)

Parameters

user_id

Unique attribute to identify a person in your people list (Ex:- Mobile Number, Email or System Generated User ID)

name

Name of the person

mobile_number

Mobile number of the person in E.164 format

email

Email of the person

tags

String array of tags (Ex:- ["lead","employee"])

Additionally to above default parameters, you can define your own custom parameters

Create or update contact(s)

curl -X POST 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Apikey <API_KEY>' 
-d '[{
 "user_id": "94777123456",
"name": "Duke",
"mobile_number": "94777123456",
"email": "duke@test.com"
}]' 'https://api.getshoutout.com/coreservice/contacts'

$.post("https://api.getshoutout.com/coreservice/contacts", [{
  "user_id": "94777123456",
  "name": "Duke",
  "mobile_number": "94777123456",
  "email": "duke@test.com"
}], function(data) {
  alert(data);
});

var contacts = [{
     user_id: '94777123456',
      mobile_number: '94777123456',
      email: 'duke@test.com',
      name: 'Duke',
      tags: ['lead']
      }];

client.createContacts(contacts, (error, result) => {
    if (error) {
       console.error('error ', error);
     } else {
        console.log('result ', result);
    }
});

<?php

require __DIR__ . '/vendor/autoload.php';

use Swagger\Client\ShoutoutClient;

$apiKey = 'XXXXXXXXX.XXXXXXXXX.XXXXXXXXX';

$client = new ShoutoutClient($apiKey,true,false);


$contact = array(
    'mobile_number' => '94777123456',//Required if not specified user_id
    'user_id' => '94777123456',//Optional. if specified, this will be used to generate the contact id, otherwise         mobile_number will be used to generate contact id
    //arbitrary attributes
    'email' => 'duke@test.com',
    'tags' => ['lead'],
    'name' => 'Duke'
);
    $contacts = array($contact);

try {
    $result = $client->createContacts($contacts);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when creating contacts ', $e->getMessage(), PHP_EOL;
}

?>

/activities Edit

Create Activity

Parameters

userId

Userid which was used to create the contact

activityName

Name of the activity

activityData

JSON object with arbitary data

A new event will be created with the activity name if not already created

Create an activity for the user

$.post("https://api.getshoutout.com/coreservice/activities", {
  "userId":"94777123456",
  "activityName":"Test Event",
  "activityData":{
    "param1":"val1"
  }
}, function(data) {
  alert(data);
});

var activity = {
    userId: '94777123456',
    activityName: 'Sample Activity',
    activityData: {
       param1: 'val1',
       param2: 'val2',
       param3: 'val3'
   }
};

client.createActivity(activity, (error, result) => {
    if (error) {
        console.error('error ', error);
    } else {
        console.log('result ', result);
    }
});

<?php

 require __DIR__ . '/vendor/autoload.php';

 use Swagger\Client\ShoutoutClient;

 $apiKey = 'XXXXXXXXX.XXXXXXXXX.XXXXXXXXX';

 $client = new ShoutoutClient($apiKey,true,false);


 $activity = array(
     'userId' => '94777123456',//Required. your account id
     //arbitrary attributes
     'activityName' => 'Sample Activity',
     'activityData' => array(
         'param1' => 'val1',
         'param2' => 'val2',
        'param3' => 'val3'
     )
 );

 try {
     $result = $client->createActivity($activity);
     print_r($result);
 } catch (Exception $e) {
     echo 'Exception when creating activity ', $e->getMessage(), PHP_EOL;
 }

 ?>

Introduction Edit

Easy mobile number verification service available as an API. This service allows an application to easily send a system generated code to a mobile number and verify it programmatically. This can be used for two factor authentication, mobile number verification and one time password (magic passwords) like use cases.

How it Works

1. User provide mobile number to your application
2. Your application make send OTP request to OTP service with mobile number and store the reference id received
3. OTP service send a SMS with a code to the mobile number
4. User provide the received code to your application
5. Your application make verify OTP request to OTP service with code and reference id and receive the verify status

/otp/send Edit

Send One Time Password

Parameters

source

Sender mask (Alias)

destination

Mobile number in E.164 format

content

JSON object with key "sms" and the message content in the value

transport

sms

Make sure you include {{code}} in your message content

System generated one time passcode will be sent to the mobile number

{
  curl --location --request POST ‘https://api.getshoutout.com/otpservice/send’ \
  --header ‘Content-Type: application/json’ \
  --header ‘Authorization: Apikey XXX.XXX.XXXX’ \
  --data-raw ‘{
   “source”:“ShoutDEMO”,
   “transport”:“sms”,
   “content”:{
     “sms”:“Your code is {{code}}”
   },
   “destination”:“9477xxxxxxx”
 }’
}

$.post("https://api.getshoutout.com/otpservice/send", [{
"source": "ShoutDEMO",
"transport": "sms",
"content": {
  "sms":"Your code is {{code}}"
},
"destination":"9477xxxxxxx"
}], function(data) {
alert(data);
});

/otp/verify Edit

Send One Time Password

Parameters

code

One time password

referenceId

Refence id received in send otp response

If valid successful response will be received

curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Apikey <API_KEY>'
-d '{
  "code": "ABCDE",
  "referenceId": "f437c171-2d08-48c8-a4a2-xxxxxxxx"
}' 'https://api.getshoutout.com/otpservice/verify'

$.post("https://api.getshoutout.com/otpservice/verify", [{
 "code": "ABCDE",
 "referenceId": "f437c171-2d08-48c8-a4a2-xxxxxxxx",
}], function(data) {
 alert(data);
});

Introduction Edit

Loyalty service available as an API. This service allows a merchant to easily integrate a loyalty system to a business which serves customers

User Registration

1. Merchant submit the customer details to loyalty service using one of the following
   • Hosted registration form
   • Embedded registration form
   • Direct API call
2. Optionally customer receives a SMS or an Email with a welcome message and details of his/her loyalty account

Point Collection

1. Merchant record customer transactions in the PoS system
2. PoS system sends the bill value along with other transaction details to the collect points API endpoint of ShoutOUT Loyalty service
3. ShoutOUT Loyalty service calculate the points for the bill value and accumulate it to the customer points pool
4. Optionally a SMS or an Email is sent to the customer with the details of the transaction and points accumulation.

RESTful API

We have a very simple RESTful API with mainly four endpoints. And all endpoints receives request data as JSON objects.

1. Register User
2. Load User
3. Collect Points
4. Redeem Points

Enroll User Edit

Enroll user to the loyalty program

This is a merchant specific endpoint and is created upon request based on the merchant specific parameters

/users/:id Edit

Load user profile

:id is the value of user’s loyalty id

Returns the profile of the user

curl -X GET 
  --header 'Content-Type: application/json' 
  --header 'Accept: application/json' 
  --header 'Authorization: Apikey <API_KEY>' 
  -d '{
   
  }' 'https://api.getshoutout.com/loyaltyservice/users/:id'

$.get("https://api.getshoutout.com/loyaltyservice/users/:id", {
}, function(data) {
  alert(data);
});

/points Collect Edit

Add points to user

Parameters

userId

Loyalty id of the user

activityData

JSON object with required key "bill" or "points" and any other arbitary keys

Make sure you include either bill or points in the activityData object

Points will be calculated by the system and added to the user accordingly

curl -X POST \
  https://api.getshoutout.com/loyaltyservice/points?action=collect \
  -H 'authorization: Bearer <API_KEY>' \
  -H 'content-type: application/json' \
  -d '{
  "userId":"LOYAL-USER-001",
  "activityData":{
    "bill":2350.00,
    "bill_number":"INV-001",
    "employee":"Smith",
    "location":"Main Branch"
  }
}'

$.post("https://api.getshoutout.com/loyaltyservice/points?action=collect", [{
 "user_id": "LOYAL-USER-001",
 "activityData":{
   "bill":2350.00,
   "bill_number":"INV-001",
   "employee":"Smith",
   "location":"Main Branch"
 }
}], function(data) {
 alert(data);
});

/points Redeem Edit

Redeem points from a user

Parameters

userId

Loyalty id of the user

activityData

JSON object with required key "points" and any other arbitary keys

Make sure you include either points in the activityData object

Points will be redeemed from the user’s loyalty account

curl -X POST \
  https://api.getshoutout.com/loyaltyservice/points?action=redeem \
  -H 'authorization: Bearer <API_KEY>' \
  -H 'content-type: application/json' \
  -d '{
  "userId":"LOYAL-USER-001",
  "activityData":{
    "points":17,
    "employee":"Smith",
    "location":"Main Branch"
  }
}'

$.post(" https://api.getshoutout.com/loyaltyservice/points?action=redeem\", [{
   "userId":"LOYAL-USER-001",
   "activityData":{
    "points":17,
    "employee":"Smith",
    "location":"Main Branch"
  }
  }], function(data) {
  alert(data);
  });

Introduction Edit

Reward API service available to manage(add new, delete and edit) rewards and allow users to purchase rewards affordable to them from the loyalty program.

/rewards Edit

Create Reward

Parameters

rewardName

Name of the reward

points

Number of points required to redeem the reward

rewardStatus

Status of the reward (0-Unpublished,1-Published)

imageUrls

Array of image urls

Points will be redeemed from the user’s loyalty account

curl -X POST \
  https://api.getshoutout.com/loyaltyservice/rewards/
  -H 'authorization: Bearer <API_KEY>' \
  -H 'content-type: application/json' \
  -d '{
  "name": "rewards",
  "description" : "",
  "type": "voucher",
  "userRedeemable": "false",
  "points": 1,
  "status" : 2,
  "imageUrls": [
  "https://gallery.getshoutout.com/sample.jpeg"
  ],
  "metadata": { 
    "dailyRedemptionLimit":2,
    "amountPerRedemption":2,
    "amountPerRedemptionSeasonal": {
      "value": 2,
      "searchFromDate": "2019-09-09",
      "searchToDate": "2020-02-02"
      },
     "digitalRewardInfo" :{
  	    "type":""
       }
    }
  }'

$.post(" https://api.getshoutout.com/loyaltyservice/rewards/ ", {
  "name": "rewards",
  "description" : "",
  "type": "voucher",
  "userRedeemable": "false",
  "points": 1,
  "status" : 2,
  "imageUrls": [
  "https://gallery.getshoutout.com/sample.jpeg"
  ],
  "metadata": { 
    "dailyRedemptionLimit":2,
    "amountPerRedemption":2,
    "amountPerRedemptionSeasonal": {
      "value": 2,
      "searchFromDate": "2019-09-09",
      "searchToDate": "2020-02-02"
      },
     "digitalRewardInfo" :{
  	    "type":""
       }
    }
  }', function(data) {
alert(data);
});

/rewards Edit

Update Reward

Parameters

rewardId

Reward id

rewardName

Name of the reward

points

Number of points required to redeem the reward

rewardStatus

Status of the reward (0-Unpublished,1-Published)

imageUrls

Array of image urls

Points will be redeemed from the user’s loyalty account

curl -X POST \
  https://api.getshoutout.com/loyaltyservice/rewards/
  -H 'authorization: Bearer <API_KEY>' \
  -H 'content-type: application/json' \
  -d '{
   "_id":"bc0c9680-59be-11e8-82ea-7154ab678cae",
   "metadata" : {
     "amountPerRedemptionSeasonal" :{
       "value" : 1,
       "searchFromDate" : "2019-01-01",
       "searchToDate" : "2020-02-10"
     },
     "digitalRewardInfo" :{
       "type" : "digital"
     }
   }
}'

$.post("https://api.getshoutout.com/loyaltyservice/rewards/", [{
  "_id":"bc0c9680-59be-11e8-82ea-7154ab678cae",
  "metadata" : {
    "amountPerRedemptionSeasonal" :{
      "value" : 1,
      "searchFromDate" : "2019-01-01",
      "searchToDate" : "2020-02-10"
    },
    "digitalRewardInfo" :{
      "type" : "digital"
    }
  }
 }], function(data) {
 alert(data);
 });

/rewards/:id Edit

Delete reward

Reward with the id mentioned on the url will be deleted

curl -X DELETE \
  https://api.getshoutout.com/loyaltyservice/rewards/bc0c9680-59be-11e8-82ea-7154ab678cae \
  -H 'authorization: Bearer <API_KEY>' \
  -H 'content-type: application/json'
}'

$.post("https://api.getshoutout.com/loyaltyservice/rewards/bc0c9680-59be-11e8-82ea-7154ab678cae", [{
 
 }], function(data) {
 alert(data);
 });

/rewards Edit

Get rewards

Points will be redeemed from the user’s loyalty account

curl -X GET \
  https://api.getshoutout.com/loyaltyservice/rewards \
  -H 'authorization: Bearer <API_KEY>' \
  -H 'content-type: application/json'
}'

$.get("https://api.getshoutout.com/loyaltyservice/rewards ", [{
 
 }], function(data) {
 alert(data);
 });