Table of Contents

Technology Stack for Web API 4

Credentials for Web API 4

Get Dashboard Data
This service will be called on the home page. This service returns the category and
offers data display into the dashboard. 4
Request Parameter 4
ResponseParameter 5
1.6.2. ResponseParameter 7
1.7.1 Request Parameter 7
1.7.2. Response Parameter 8
1.12.1 Request Parameter 8
1.12.2. Response Parameter 9
1.14.1 Request Parameter 9
1.14.2. Response Parameter 10

Category Offers 11
Get Offers
A list of active offers will be provided which are added to the Roam system. This can be
managed from the Roam System. 11
Request Parameter 11
Response Parameter 11
Offer Details:
This service will be called to fetch offer details. 13
Request Parameter 13
Response Parameter 14
Get Favorite Offer:
This service will be called to fetch user favourite offers. 16
Request parameter 16
Response Parameter 17
Get Nearby Offers:
This service will be called to fetch offers nearby user location. 19
Request parameter 19
Response Parameter 19
Search Offers:
This service will be called to search the offers and get the offers. 20
Request parameter 20
Response Parameter 20
Get Coupon Details:
This service will be called to fetch coupon details. 22
Request parameter 22
Response Parameter 23
 Voucher Redeem:
This service will be called to redeem the voucher. 24
Request parameter 24
Response Parameter 24
Get Country List:
This service will be called to fetch a country list. 25
Request parameter 25
Response Parameter 25
Add Offer Rating and Review:
This service will be called to add an offer rating and review. 26
Request parameter 26
Response Parameter 27

Abbreviations 28

Conventions 28

Status Codes 28
 Technology Stack for Web API

Development Language PHP

Database MYSQL

Request / Response JSON Format

Credentials for Web API

Sandbox BASE URL https://www.roamcorporate.com/frendi/beta/servi

es/v4/

Sandbox API Key frendi

1.1. Get Dashboard Data

This service will be called on the home page. This service returns the category
and offers data display into the dashboard.
1.1.1. Request Parameter
Method URL

POST {{baseurl}}/?xAction=getDashboardData

Type Params Values

POST MSISDN String (CountryCode + Mobile Number)

e.g 971123456789

POST Latitude String

POST Longitude String
POST apikey String
 1.1.2. ResponseParameter
Status Response

200 {
"count":"1",
"msg":"Dashboard data send successfully.",
"categoryData":[
{
"offerCategoryID":"6",
"categoryID":"6",
"categoryTitle":"Category Title",
"categoryImage":"Category Image URL"
}
],
"homesliderData":[
{
"sliderID":"9",
"sliderTitle":"slide Title",
"sliderImage":"slider Image URL",
"redirectPageID":"55",
}
],
"popularOffers":[
{
"isDelivery":"1",
"isDeliveryText":"Delivery",
"favStatus":0,
"merchantName":"Max Vision LLC",
"offerID":"1386",
"merchantID":"3915",
"outletID":"3916,3917,3918",
"offerCategoryID":"25",
"tncID":"411",
"offerTitle":"Offer Title",
"offerTagline":"Offer Tagline",
"offerDesc":"Offer Description",
"offerFromDate":"Offer From Date",
"offerToDate":"Offer To Date",
"offerImage":"Offer Image URl",
"offerListingImage":"Offer ListingImage URl",
"popularImage":"Popular Image",
"discountValue":"33",
"estimatedSaving":"61",
"downloadLimit":"",
"couponCodeQty":"",
"isPopular":"1",
"estimatedSavingText":"Est. Savings - AED 61",
"avgRating":"3.3",
"searchTags":"Optical, eyetest",
 "minDistance":"1967.48 Km"
}
],
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"count": 0,
"msg": "Dashboard data sending failed.
"
}
Different validation errors will return as an "msg" parameter.

1.6. Get User Voucher List :

This service will be called to fetch user voucher details.
.
1.6.1 Request Parameter
Method URL

POST {{baseurl}}/?xAction=getMyVoucherList

Type Params Values

POST MSISDN String

POST latitude String
POST longitude String
POST apikey String

1.1.3. 1.6.2. ResponseParameter

Status Response
200 {
"data": [
{
"dateRedemption": "20/12/2019",
"ccExpiredDate": "0000-00-00 00:00:00",
"couponCode": "1HRJW3R0",
"offerID": "37",
"offerTitle": "Buy 1 Get 1 Free",
"redeemBy": "609",
"outletName": "Yas Mall",
"outletAddress": "Abu Dhabi"
}
],
"count": 1,
"msg": "Voucher list."
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"data": [ ],
"count": 0,
"msg": "No record found."
}
Different validation errors will return as an "msg" parameter.

1.7. Get Total Saving:

This service will be called to fetch user total saving details category wise.
.
1.1.4. 1.7.1 Request Parameter
Method URL

POST {{baseurl}}/?xAction=totalSavings

Type Params Values

POST MSISDN Integer

POST latitude String
POST Longitude String
POST apikey String

1.1.5. 1.7.2. Response Parameter

Status Response

200 {
"data": [
{
"categoryTitle": "Category Title",
"categoryImage": "Category Image URL",
"saving": 0
}
],
"count": 1,
"msg": " Total savings data fetched successfully.",
"totalSavings": 0
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"data": [],
"count": 0,
"msg": "No total savings found."
}
Different validation errors will return as an "msg" parameter.

1.12. Save User Feedback

This service will be called to save the user feedback.
.
1.1.6. 1.12.1 Request Parameter
Method URL
POST {{baseurl}}/?xAction=saveFeedback

Type Params Values

POST MSISDN String

POST feedbackContent String
POST latitude String
POST Longitude String
POST apikey String

1.1.7. 1.12.2. Response Parameter

Status Response

200 {
"count": 1,
"msg": "Your Feedback has been submitted successfully."
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"count": 0,
"msg": "Error in saving feedback."
}
Different validation errors will return as an "msg" parameter.

1.14. Add To Favourite

This service will be called to offer an add or remove to user favorite list.
.
1.1.8. 1.14.1 Request Parameter
Method URL
POST {{baseurl}}/?xAction=addToFavorite

Type Params Values

POST MSISDN String

POST offerID Integer
POST favStatus Integer
POST latitude String
POST longitude String
apikey
POST String

1.1.9. 1.14.2. Response Parameter

Status Response

200 {
"count": 1,
"msg": "Offer is added in favourite\list."
}
{
"count": 1,
"msg": "Lumiere Coffee has been removed from your favourite.",
"data": [
{
"offerID": "861",
"userID": "1",
"favStatus": 0
}
]
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"count": 0,
"msg": "Error in adding offer to favourite\list."
}
 Different validation errors will return as an "msg" parameter.

2. Category Offers

2.1. Get Offers

A list of active offers will be provided which are added to the Roam system. This
can be managed from the Roam System.

2.1.1. Request Parameter

Method URL

POST {{baseurl}}/?xAction=getOffers

Type Params Values

POST MSISDN String

POST categoryID Integer
POST offerFilter Integer
POST offerSort Integer
POST latitude String
POST longitude String
POST apikey String

2.1.2. Response Parameter

Status Response

200 {
"count":208,
"data":[
{
"isAppMenu":"0",
"isDelivery":"1",
"isDeliveryText":"Take Away",
 "displayOrder":"0",
"searchTags":"Optical, eyetest",
"offerID":"1388",
"favStatus":0,
"enableLaunchTag":"0",
"offerDesc":"offerDesc",
"launchTag":"",
"isInformative":"0",
"merchantID":"3915",
"outletID":"3916,3917,3918",
"offerCategoryID":"25",
"tncID":"411",
"offerTitle":"Offer Title",
"offerTagline":"Offer Tagline",
"offerFromDate":"01-01-1970",
"offerToDate":"01-01-1970",
"offerImage":"offerImage",
"offerListingImage":"offerImage",
"discountValue":0,
"estimatedSaving":"700",
"estimatedSavingText":"estimatedSavingText",
"downloadLimit":"",
"couponCodeQty":"",
"isPercentage":"0",
"isFeatured":"0",
"isActive":"1",
"status":"1",
"offerDetailTemplate":"0",
"offerBannerTitleOne":"",
"offerBannerTitleTwo":"",
"merchantName":"Max Vision LLC",
"merchantImage":"merchantImage",
"merchantDescription":"",
"avgRating":"4.5",
"searchString":"searchString",
"minDistance":"1967.48 Km",
"location":null,
"offerImageArr":[
"offerImage"
],
"tncDescription":"tncDescription"
},
],
"categoryData": [
{
"offerCategoryID": "1",
"categoryID": "1",
"categoryTitle": "Category title 1",
}
 ],
"categoryFilterData": [
{
"catFilterID": "16",
"filterTitle": ""
}
],

"sortData": [
{
"1": "Highest to Lowest Discount",
"2": "Lowest to Highest Discount",
"3": "Distance",
"4": "Buy 1 Get 1 Offers"
}
],
"msg":"Fetching data from offer is completed successfully."
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"count": 0,
"msg": "No data found."
}

Different validation errors will return as an "msg" parameter.

2.2. Offer Details:

This service will be called to fetch offer details.

2.2.1. Request Parameter

Method URL

POST {{baseurl}}/?xAction=getCategoryOfferDetails
Type Params Values

POST MSISDN String

POST offerID Integer
POST latitude String
POST longitude String
POST apikey String

2.2.2. Response Parameter

Status Response

200 {
"count":1,
"msg":"Fetching data from offer is completed successfully.",
"relatedOffers":[
{
"isAppMenu":"0",
"isDelivery":"1",
"isDeliveryText":"Take Away",
"displayOrder":"0",
"searchTags":"Optical, eyetest",
"offerID":"1388",
"favStatus":0,
"enableLaunchTag":"0",
"offerDesc":"offerDesc",
"launchTag":"",
"isInformative":"0",
"merchantID":"3915",
"outletID":"3916,3917,3918",
"offerCategoryID":"25",
"tncID":"411",
"offerTitle":"Offer Title",
"offerTagline":"Offer Tagline",
"offerFromDate":"01-01-1970",
"offerToDate":"01-01-1970",
"offerImage":"offerImage",
"offerListingImage":"offerImage",
"discountValue":0,
"estimatedSaving":"700",
"estimatedSavingText":"estimatedSavingText",
"downloadLimit":"",
"couponCodeQty":"",
"isPercentage":"0",
"isFeatured":"0",
"isActive":"1",
 "status":"1",
"offerDetailTemplate":"0",
"offerBannerTitleOne":"",
"offerBannerTitleTwo":"",
"merchantName":"Max Vision LLC",
"merchantImage":"merchantImage",
"merchantDescription":"",
"avgRating":"4.5",
"searchString":"searchString",
"minDistance":"1967.48 Km",
"location":null,
"offerImageArr":[
"offerImage"
],
"tncDescription":"tncDescription"
},
],
"data":[
{
"offer object":"offer object",
"location":[
{
"otherDescription":"",
"outletTitle":"Outlet Title",
"outletContactNo":[
{
"contactNo":"contactNo"
}
],
"outletAddress":"Outlet Address",
"latitude":"latitude",
"longitude":"longitude",
"distance":"1967.48 Km",
"outletImage":"outletImage"
},
],
"offerImageArr":[
"offerImage"
],
"tncDescription":"tncDescription"
}
],
"menuImages":[
"menuImages"
],
"popUpMenuImages":[
{
"url":"popUpMenuImages"
}
 ],
"isAppMenu":0,
"reviewRating":[
{
"offerID":"offerID",
"reviewRatingID":"reviewRatingID",
"userID":"userID",
"dateAdded":"dateAdded",
"rating":rating,
"review":"review",
"offerTitle":"Offer Title",
"merchantName":"Merchant Name",
"userName":"User Name"
}
],
"isReviewSubmit":0
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"count": 0,
"msg": "No data found."
}
Different validation errors will return as an "msg" parameter.

2.3. Get Favorite Offer:

This service will be called to fetch user favourite offers.

2.3.1. Request parameter

Method URL

POST {{baseurl}}/?xAction=getFavouriteOffer
Type Params Values

POST MSISDN String

POST latitude String
POST longitude String
POST apikey String

2.3.2. Response Parameter

Status Response

200 {
"count": 1,
"msg": "Data fetched successfully.",
"data": [
{
"isAppMenu": "0",
"isDelivery": "0",
"isDeliveryText": "",
"displayOrder": "1102",
"searchTags": "",
"offerID": "682",
"favStatus": "1",
"enableLaunchTag": "0",
"offerDesc": "",
"launchTag": "",
"isInformative": "0",
"merchantID": "669",
"outletID": "outletID",
"offerCategoryID": "3",
"tncID": "0",
"offerTitle": "HOSPITAL UAE",
"offerTagline": "",
"offerFromDate": "01-01-1970",
"offerToDate": "01-01-1970",
"offerImage": "offerImage",
"offerListingImage": "offerListingImage",
"discountValue": 0,
"estimatedSaving": "",
"estimatedSavingText": "",
"downloadLimit": "",
"couponCodeQty": "",
"isPercentage": "0",
 "isFeatured": "0",
"isActive": "1",
"status": "1",
"offerDetailTemplate": "1",
"offerBannerTitleOne": "",
"offerBannerTitleTwo": "",
"merchantName": "Hospitals UAE ",
"merchantImage": "merchantImage",
"merchantDescription": "",
"avgRating": "0.0",
"searchString": "",
"minDistance": "1873.69 Km",
"location": null,
"offerImageArr": [
"hofferImage"
],
"tncDescription": ""
}
]
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"count": 0,
"msg": "No data found."
}
Different validation errors will return as an "msg" parameter.

2.4. Get Nearby Offers:

This service will be called to fetch offers nearby user location.

2.4.1. Request parameter

Method URL
POST {{baseurl}}/?xAction=getNearByOffers

Type Params Values

POST MSISDN String

POST latitude String
POST longitude String
POST apikey String

2.4.2. Response Parameter

Status Response

200 {
"data": [
{
"offerDetails": [
{
"offerID": "offerID",
"offerTitle": "Offer Title",
"offerTagline": "offer Tagline"
}
],
"outletData": {
"outletName": "Outlet Name",
"outletAddress": "Outlet Address",
"latitude": "latitude",
"longitude": "longitude",
"minDistance": "minDistance",
"merchantName": "Merchant Name",
"merchantImage": "Merchant Image URl"
}
}
]
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"count": 0,
"msg": "Please allow location permission."
}
Different validation errors will return as an "msg" parameter.

2.5. Search Offers:

This service will be called to search the offers and get the offers.

2.5.1. Request parameter

Method URL

POST {{baseurl}}/?xAction=searchOffers

Type Params Values

POST MSISDN String

POST searchKey String
POST latitude String
POST longitude String
POST apikey String

2.5.2. Response Parameter

Status Response

200 {
"count":1,
"msg":"Search details.",
"data":[
{
"offerDesc":"Offer Desc",
"merchantID":"607",
"offerCategoryID":"6",
"offerTitle":"Offer Title",
 "offerTagline":"Offer Tagline",
"offerFromDate":"Offer From Date",
"offerToDate":"Offer To Date",
"offerImage":"Offer Image URl",
"offerListingImage":"Offer Listing Image ˇ",
"discountValue":0,
"estimatedSaving":"10",
"estimatedSavingText":"",
"couponCodeQty":"",
"offerDetailTemplate":"0",
"offerBannerTitleOne":"",
"offerBannerTitleTwo":"",
"merchantName":"Merchant Name",
"merchantImage":"Merchant Image URl",
"merchantDescription":"Merchant Description",
"avgRating":"0.0",
"searchString":"special",
"minDistance":"1992.37 Km",
"location":location,
"offerImageArr":[
"Offer Image URl"
],
"tncDescription":"terms & conditions"
}
}
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"count": 0,
"msg": "Search result not found !"
}
Different validation errors will return as an "msg" parameter.
 2.6. Get Coupon Details:
This service will be called to fetch coupon details.

2.6.1. Request parameter

Method URL

POST {{baseurl}}/?xAction=getAppVoucher

Type Params Values

POST MSISDN String

POST offerID Integer
POST latitude String
POST longitude String
POST apikey String
 2.6.2. Response Parameter
Status Response

200 {
"data": [
{
"couponGenerationType": "1",
"offerTitle": "Offer Title",
"offerToDate": "Offer To Date",
"merchantPin": "Merchant Pin",
"userID": "userID",
"merchantName": "Merchant Name",
"merchantImage": "Merchant Image",
"couponCode": "Coupon Code",
"barCode": "Coupon BarCode image"
}
],
"count": 1,
"msg": "Coupon generated successfully."
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"data": [ ],
"count": 0,
"msg": "No data found."
}
Different validation errors will return as an "msg" parameter.
 2.7. Voucher Redeem:
This service will be called to redeem the voucher.

2.7.1. Request parameter

Method URL

POST {{baseurl}}/?xAction=appVoucherRedeem

Type Params Values

POST MSISDN String

POST offerID Integer
POST couponCode String
POST outletPin Integer
POST latitude String
POST longitude String
POST apikey String

2.7.2. Response Parameter

Status Response

200 {
"data": [ ],
"count": 0,
"msg": "Your voucher has been redeemed successfully."
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"data": [ ],
"count": 0,
"msg": "Coupon code already used."
 }
{
"data": [],
"count": 0,
"msg": "Please enter a valid outlet pin."
}
Different validation errors will return as an "msg" parameter.

2.8. Get Country List:

This service will be called to fetch a country list.

2.8.1. Request parameter

Method URL

POST {{baseurl}}/?xAction=getCountryList

Type Params Values

POST MSISDN String

POST latitude String
POST longitude String
POST apikey String

2.8.2. Response Parameter

Status Response

200 {
"count": 1,
"msg": "Country fetched successfully!!",
"data": [
{
"countryID": "1",
"countryName": "Country Name",
"countryCode": "Country Code",
"isdCode": "93",
"countryImage": "Country Image URL"
}
]
}
401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"data": [ ],
"count": 0,
"msg": "Something went wrong!!"
}
Different validation errors will return as an "msg" parameter.

2.9. Add Offer Rating and Review:

This service will be called to add an offer rating and review.

2.9.1. Request parameter

Method URL

POST {{baseurl}}/?xAction=addReviewRating

Type Params Values

POST MSISDN String

POST offerID Integer
POST rating Integer
POST review String
POST latitude String
POST longitude String
POST apikey String
 2.9.2. Response Parameter
Status Response

200 {
"count": 1,
"msg": "Review and rating added successfully."
}

401 {"error":"Bad request: API key is missing."}

402 {"error":"Authentication failure: API key is invalid."}

404 {"error":"Not Found: xAction is missing."}

403 {"error":"Forbidden Error: You don’t have access for this request."}

503 {"error":"Service Unavailable: Requested service is not available."}

800 {
"count": 0,
"msg": "Error in adding review and rating.”
}
Different validation errors will return as an "msg" parameter.
 Glossary

Abbreviations
● Roam Offers System: Roam Offers backend
● Roam Offers App: Roam Offers app
● User: End Consumer
● Status: HTTP status code of response.

Conventions
● All the possible responses are listed under ‘Responses’ for each method. Only one of them
is issued per request server.
● All responses are in JSON format.
● All request parameters are mandatory unless explicitly mentioned in the description.
● Integer will accept only numbers, not strings

Status Codes
All status codes are standard HTTP status codes. The below ones are used in this API.

2XX - Success of some kind

4XX - Error occurred in client’s part
5XX - Error occurred in server’s part
8XX - Validation Error occurred in server’s part

Status Code Description

200 Success

401 Bad request

402 Authentication failure

404 Not Found

403 Forbidden Error

503 Service Unavailable

800 Validation Errors