Contents

Overview

UrbanBuz is an easy-to-manage cloud-based customer engagement platform that helps businesses capture relevant customer information; incentivize customers based on different behaviors; engage with customers in a personal and relevant manner through different channels (SMS/Email). The cloud-based platform is designed for marketers that enable them to use customer data and engage with their customers without the need for coding or having to deal with different tools and most importantly in real time. Marketers can define their own customer profiles, filter data accordingly, setup automated marketing based on certain behavior and filters, track marketing campaign live, and incentivize customers.

Getting started

Introduction to UrbanBuz API

Application Programming Interfaces (APIs) available with UrbanBuz can be used by businesses across different segments to integrate with UrbanBuz platform. Businesses can use these APIs to manage customer data, sales data, marketing data and so on. User credentials are provided by UrbanBuz to access the APIs. All API calls need to be made using the HTPP protocol to ensure data security. The UrbanBuz APIs are based on Representational State Transfer (REST) standards. REST defines a set of principles for defining Web services, including how a system’s resource states are transferred over HTTP.

About this document

This document is intended for developers who want to use UrbanBuz APIs. This document is based on REST API version 3. It describes how to use REST API to authenticate, make requests, and retrieve data. The APIs use (JavaScript Object Notation) JSON as the default message format. JSON provides a lightweight, simple, and more flexible message format that increases the speed of communication. You need to use standard HTTP methods to access the UrbanBuz APIs. For example, HTTP GET is used by a client application to retrieve a resource, get data from a Web server or to execute a query.

Common HTTP methods for REST are:

  • GET – Retrieve a resource from the server
  • POST – Update a resource on the server
  • PUT – Create a resource state on the server.
  • DELETE – Remove a resource state on the server.

Version information

This document is based on REST API version 3.

Authentication

UrbanBuz uses customized OAuth 1.0b authentication specification with HMAC-SHA1 signature method that requires a Key and Secret. The following sections explain how to generate an OAuth 1.0b HMAC-SHA1 signature for an HTTP request. This signature is required for passing all UrbanBuz APIs as part of an authorized request. UrbanBuz will provide the Key and Secret along with an OAuth connection library that is required to a create a signature for accessing resources via OAuth (currently using PHP).

Collecting the request method and URL

To create a signature, you need to determine the HTTP method and URL of the request. The base URL is the URL to which the request is directed, excluding any query string or hash parameters. Make sure that the “http//” portion of the URL matches the actual request sent to the API.

Base URL:

http://[subdomain].urbanbuz.com

Query Parameter:

All the query parameter values MUST be URL encoded with UTF-8. See the following example:

http://[subdomain].urbanbuz.com/program/account/search?first=MiKe+Kate

Here, the query parameter value Mike+Kate is encoded to result to MiKe%2BKate.

Collecting the parameters

Collect all the parameters included in the request. There are two locations for these additional parameters - the URL (as part of the querystring) and the request body. In addition to the request parameters, authentication parameters such as auth_key, oauth_nonce, oauth_signature_method, and oauth_timestamp should be included. The parameters (request parameter and authentication parameters) are listed as follows: The values need to be encoded into a single string, called the parameter string.

Parameter Value Description
append_payment True This is the request parameter
oauth_key String API key assigned for the branch or program. Example: pIddeizKeygxPDRuaLNt
oauth_nonce String Random alphanumeric string, uniquely generated to allow the server to verify that a request has never been made before. The nonce value is unique across all requests. Example: lxucb66OAp0
oauth_signature_method String Keyed-hash message authentication specification known as HMAC-SHA1 to sign API calls.
oauth_timestamp String Indicates when the request was created.

The following string will be produced with the parameters collected in the table above:

append_payment=true&oauth_key=xvz1evFS4wEEPTGEFPHBog&oauth_nonce=kYjzVBB8Y0ZFab&oauth_signature_method=HMAC-SHA1&oauth_timestamp=123456789

Creating the signature base string

The three request elements such as HTTP method, base URL, and the parameters must be concatenated to make a single string, from which the signature will be generated. This is called the signature base string by the OAuth specification.

  • HTTP method: The HTTP request method
  • Base URL: The URL the request is being sent to. This URL should not include any query parameters
  • Parameter string: String of the parameters in the request (excluding the oauth_signature parameter). Example: append_payment=true,oauth_key=key&oauth_nonce=nonce&oauth_timestamp=123456789

To encode the HTTP method, base URL, and parameter string into a single string:

  1. Convert the HTTP Method to uppercase and set the output string equal to this value.
  2. Append the ‘&’ character to the output string.
  3. Percent encode the URL and append it to the output string.
  4. Append the ‘&’ character to the output string.
  5. Percent encode the parameter string and append it to the output string.


This will produce the following signature base string:

PUT&http%3A%2F%2Fapi.urbanbuz.com%2Ftxn%2Ftransactions%2Fsubmit&append_payment%3Dtrue%

26oauth_key%3Dtest_key%26oauth_nonce%3D8LbvcvYFqqG5RKl1zhr5%26oauth_timestamp%3D123456789

Generating the signature

The signature is calculated by passing the signature base string and signing key to the HMAC-SHA1 hashing algorithm. The generated signature is then added to the request as oauth_signature before sending it to the API.

API Calls

The following sections describe the different API calls of UrbanBuz.

Accounts

Create account

When a customer transacts for the first time, the Create account API call is invoked to create an account for the customer and a unique customer ID is generated for this customer. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Parameter Type Required Description
first String Not mandatory First name of the customer
last String Not mandatory Last name of the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
gender String Not mandatory Gender of the customer
birthdate Date Not mandatory Date of birth of the customer
nationality String Not mandatory Nationality of the customer

Error messages

Error Code Error Message
1004 The following field is not unique
1010 At least one of the following fields is required
EXAMPLE REQUEST:

 POST http://[subdomain].urbanbuz.com/program/accounts
{
	"profile": {
		"phone": "971520000000",
		"email": "john@email.com",
		"first": "John",
		"last": "Samuel",
		"birthdate": "1988-06-06",
		"gender": "M",
		"city": null,
		"country": null,
		"nationality": "India",
		"language": null,
		"businessFields": {
			"maritalStatus": "Married",	
			"residency": "tourist",	
			"ethnicity": "Asian"
		}
	}
}


EXAMPLE RESPONSE:

{
    "status" : "success",
    "account" : {
         "accountId" : "f64f2940-fae4-11e7-8c5f-ef379131"
    }
}

Search for account

This call is executed to search for the customers associated with a program. The customer list is obtained based on the set search criteria.

Request elements

Parameter Type Required Description
first String No First name of the customer
last String No Last name of the customer
phone String No Phone number of the customer
email String No Email ID of the customer
employeeId String No Employee ID of the customer
businessFieldsRequired String Yes Value required in the response
page Integer Yes Search page number
size Integer Yes Number of records to return by page

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/accounts/search?
   first=Jenn&last=C&businessFieldsRequired=title,street1&page=1&size=10


EXAMPLE RESPONSE:

{
  "pageNumber": 1,
  "pageSize": 10,
  "totalCount": 7,
  "data": [
    {
      "phone": "971502188801",
      "email": "jane@gmail.com",
      "accountId": "2a5676fe-0151-435f-b392-131ab2eae0c5",
      "first": "Jennifer",
      "last": "Christi",
      "birthdate": "1987-09-11",
      "profileSet": "2018-03-26 12:44:55 GST",
      "businessFields": {
        "title": "Mr."
    },    
    {
      "phone": "971502188844",
      "email": "jen124@gmail.com",
      "accountId": "e4670b54-4d13-40c3-a49a-64d225231152",
      "first": "Jennie",
      "last": "Cooks",
      "birthdate": "1987-09-11",
      "profileSet": "2018-03-28 06:56:03 GST",
      "businessFields": {
        "street1": "M street"
      }
    }
  ]
}

Get account by ID

This call is executed to obtain the details of customers (which includes details about their loyalty benefits) by their customer IDs. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
loyalty Boolean Yes Flag to indicate to return loyalty information

Error messages

Error Code Error Message
1005 Data Not Found
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/accounts?
    accountId=f64f2940&phone=971520000000&loyalty=true


EXAMPLE RESPONSE:

{
  "profile": {
   "phone": 971520000000,
   "email": "john@email.com",
   "accountId": "f64f2940",
   "first": "John",
   "last": "Samuel",
   "birthdate": "1988-06-06",
   "gender": "M",
   "city": null,
   "country": null,
   "nationality": "India",
   "language": null,
   "businessFields": {
    "title": "Mr.",
    "maritalStatus": "Married",
    "ethnicity": "Asian"
		}
	},
     "loyalty" : {
       "program" : {
         "name"   : "Loyalty Program Name",
          "logo"   : "URL path to image.jpg"
        },
        "tier" : {
          "name"   : "Loyalty tier name",
          "logo"   : "URL path to image.jpg",
          "order"  : 3,
          "expiry" : "2019-09-09 00:00:00",
          "benefits": "Provide the description of the benefits provided"
        },
        "wallets" : [{
           "countryIso" : "AE",
           "countryName": null,
           "currency"   : "AED",
           "point"      : 1575,
           "value"      : 15.75
        }],
       "redeemable": [
        {
         "countryIso": "AE",
         "countryName": null,
         "currency": "AED",
         "point": 1000,
          "value": 10,
                }
         ],
        "expiry": {
        "point": 256,
        "date": "2018-07-03"
    },
       "toNextTier": 200,
       "cumulativeCredit": 12366.27,
       "balanceDetails": [
     {
        "loyaltyPointsGained": 2345,
        "loyaltyPointsRedeemed": 0,
        "loyaltyPointsExpired": 0,
        "expires": "2018-12-31 00:00:00UTC"
      },
      {
        "loyaltyPointsGained": 142,
        "loyaltyPointsRedeemed": 0,
        "loyaltyPointsExpired": 0,
        "expires": "2020-10-15 00:00:00 UTC"
      }
      ]
}

Update account by ID

This call is executed to update the profile of customers by their IDs. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
first String No First name of the customer
last String No Last name of the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
gender String No Gender of the customer
birthdate Date No Date of birth of the customer
nationality String No Nationality of the customer

Error messages

Error Code Error Message
1004 The following field is not unique
1010 At least one of the following fields required
EXAMPLE REQUEST:
PUT http://[subdomain].urbanbuz.com/program/accounts?
accountId=f64f2940-fae4-11e7-8c5f-ef379131
{
	"profile": {
		"phone": "971520000000",
		"email": "john@email.com",
		"first": "John",
		"last": "Samuel",
		"birthdate": "1988-06-06",
		"gender": "M",
		"city": null,
		"country": null,
		"nationality": "India",
		"language": null,
		"businessFields": {
                 "title": "Mr.",
         	  "maritalStatus": "Married",
		    "ethnicity": "Asian"
		}
	}
}

EXAMPLE RESPONSE:


 {
    "status" : "success"
}

Get account mapping

This call is executed to obtain all the brands that the account is associated with.

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as the query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/online/​{token}/brand_mappings 

EXAMPLE RESPONSE:

{
     ​"countryIso"  ​: ​"AE"​, 
     ​"countryName"​ : ​"United Arab Emirates"​,   
  ​   "brandId"​     : ​22​,    
     ​"brandName"​   : ​"Bershka" 
}, 
{    
     ​"countryIso"  ​: ​"AE"​,  
   ​  "countryName" ​: ​"United Arab Emirates"​,  
     ​"brandId"     ​: ​45​,    
     ​"brandName"   ​: ​"Zara" }

}
}

Get account communication preferences

This call is executed to obtain the details about the communication preference (opt-out) set by the account.

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/online/
    ​{token}/communication/preferences 

EXAMPLE RESPONSE:

 {    
    ​"channel"     ​: ​1​, 
    ​"channelName" ​: ​"SMS"​,    
 ​"countryBrandPreferences" ​: [{     
    ​"countryIso"  ​: ​"AE"​,        
    ​"countryName"​ : ​"United Arab Emirates"​,  
       ​"brandId"​     : ​22​,       
    ​"brandName"​   : ​"Bershka"​,     
    ​"communicationCategories" ​: [{     
   ​"optOut"       ​: ​true​,      
  ​ "categoryId"​   : ​8​,       
   ​"categoryName"​ : ​"Newsletter"   
      }]  
   }] 
}

Signup

When a customer accesses the Registration page and submits the registration details by filling in the form, the Signup API call is invoked. If the API response is success, it indicates that the customer is new and gets registered. If the response indicates that the customer is already registered, the customer is provided the option to send an email to confirm identity and to update existing profile.

Request elements

Parameter Type Required Description
gender String Yes Gender of the customer
first String Yes First name of the customer
last String No Last name of the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
birth_date Date Yes Birth date of the customer
nationality String Yes The nationality the customer belongs to
country String Yes Country of residence of the customer
state_city_emirate String No State or city or Emirate of residence of the customer
home_location String No Area where the customer resides
work_location String No Work location of the customer
pin String Yes A secret pin for identification (Please set a secret

number for identification)

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

 POST http://[subdomain].urbanbuz.com/customer/online/signup
{
    "customer" : {
        "gender"             : "M",
        "first"              : "John",
        "last"               : "Samuel",
        "phone"              : "971520000000",
        "email"              : "john@abc.com",
        "birth_date"         : "1988-06-06"
        "nationality"        : "LB",
        "country"            : "AE",
        "state_city_emirate" : "LB",
        "home_location"      : "Tecom",
        "work_location"      : "Discovery Gardens",
        "pin"                : "1234"
     }
}


EXAMPLE RESPONSE:
{
    "status" : "SUCCESS"
}

Checkin

When a customer logs in to the Registration page, the checkin call is invoked using the phone number or the email ID of the customer. If checkin is successful, the call will retrieve all the details about the customer updated in the system. The checkin call will also return a token that needs to be used when logging in for all subsequent calls to the API.

Request elements

Requires either phone number or email.

Parameter Type Required Description
include_loyalty Boolean Yes True if customer’s loyalty account details need to be fetched.
include_token Boolean Yes True if token is required in the response.
phone* String Yes Phone number of the customer
email* String Yes Email ID of the customer
  • Note: Requires either the phone number or email ID of the customer.
Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/customer/online/
     checkin?include_loyalty=true&include_token=true

{
    "email": "john@samuel@abc.com"
}


EXAMPLE RESPONSE:
 {
  "customer": {
    "gender": "F",
    "birth_date": "2012-11-10 00:00:00 UTC",
    "profile_set": true,
    "email": "971552222220@email.com",
    "country_iso": "AE",
    "last": "B",
    "nationality": "IN",
    "user_id": 4357289,
    "phone": "971552222220",
    "first": "Sumaya"
  },
  "loyalty": {
    "program": {
       "name": "Loyalty Program Name",
       "logo": "URL path to image.jpg "
    },
    "tier": {
      "name": "Loyalty Tier 1",
      "logo": "URL path to image.jpg",  
      "tierorder": 1,
      "tierexpiry": "2019-01-01"
         },
    "wallets": [
      {
        "countryIso": "AE",
        "currency": "AED",
        "point": 1575,
        "value": 15.75
      }
    ],
    "redeemable": {
      "point": 1000,
      "value": 10,
      "currency": "AED"
      },
      "expiry": {
        "point": 256,
         "date": "2018-07-03"
         },
         "token": "GEnuH4SLV811"
}

Login with token

Use the login call to retrieve customer details with the token obtained during checkin. The call will retrieve the same details as retrieved through the checkin call. The login call will return all the details about the customer including his/her profile along with the loyalty details (balance, expiry, tier, etc…). Also, the login call will return a session token that needs to be used in all subsequent calls to the API.

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as a query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/api/customers/login
{
    "token" : "abc123"
}

EXAMPLE RESPONSE:

{
    "phone"          : "97155239988007",
    "email"          : "john@abc.com",
    "first"          : "John",
    "last"           : "John Sam",
    "nationality"    : "LB",
    "gender"         : "M",
    "birth_date"     : "1970-12-01",
    "profile_set"    : true,//indicates if customer’s profile is set
    "current_credit" : 12.34, // customer’s loyalty balance
    "expires"        : "Aug 9, 2018 7:48:55 AM",//loyalty balance expiry
    "level"          : 1, // customer’s level
    "label"          : "Blue", // customer’s level name
    "level_expires"  : "Aug 9, 2018 7:48:55 AM",//level expiry
    "token"          : "abc123", // customer’s session token
    "tokenExpires"   : "Aug 12, 2017 12:56:02 PM",//session token expiry
    "refreshToken"   : "abc123"//customer’s refresh token
}

Login with OTP

Customers will receive SMS or Email with a short-code (4 digits) to be used during login. This will redirect to a page to verify the code in order to login. After entering the code, it is submitted along with the email or phone previously entered, through the /login API call. This will retrieve all the details about the customer.

Request elements

Requires either phone number or email.

Parameter Type Required Description
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
code Integer Yes OTP received as communication

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/api/customers/login

{
    "phone" : "971557802482",
    "code"  : "1234"
}

EXAMPLE RESPONSE:

{
    "phone"         : "971557802482",
    "email"         : "john@abc.com",
    "first"         : "John",
    "last"          : "Sam",
    "nationality"   : "LB",
    "gender"        : "M",
    "birth_date"    : "1970-12-01",
    "profile_set"   : true,//indicates if customer’s profile is set
    "current_credit": 12.34,//customer’s loyalty balance
    "expires"       : "Aug 9, 2018 7:48:55 AM",//loyalty balance expiry
    "level"         : 1, // customer’s level
    "label"         : "Blue",//customer’s level name
    "level_expires" : "Aug 9, 2018 7:48:55 AM",//level expiry
    "token"         : "abc123",//customer’s session token
    "tokenExpires"  : "Aug 12, 2017 12:56:02 PM",//session token expiry
    "refreshToken"  : "abc123"//customer’s refresh token
}

Customer profile

Get customer profile

This call is executed to obtain information about registered customer.

Request elements

Parameter Type Required Description
token String Yes Token received as query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/customer/online/abc123/profiles


EXAMPLE RESPONSE:

 {
    "customer" : {
        "gender"             : "M",
        "first"              : "john",
        "last"               : "Hajj Obeid",
        "phone"              : "971557802482",
        "email"              : "John@abc.com",
        "birth_date"         : "1970-12-01"
        "nationality"        : "LB",
        "country"            : "AE",
        "state_city_emirate" : "LB",
        "home_location"      : "Tecom",
        "work_location"      : "Discovery Gardens",
        "pin"                : "1234"
    }
}

Update customer profile

To update user profile, you will receive an email with a link redirecting to the website, along with a token received as a query parameter. This token value needs to be used with the API call to update customer profile and retrieve existing profile to pre-fill the form.

Request elements

Parameter Type Required Description
token String Yes Token received as query parameter
gender String Yes Gender
first String Yes First name
last String No Last name
phone String Yes Phone number
email String Yes Email
birth_date Date Yes Date of birth
nationality String Yes Nationality
country String Yes Country of residence
state_city_emirate String No State or city or emirate of residence
home_location String No Home location
work_location String No Work location

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com/customer/online/abc123/profiles
{
    "customer" : {
        "gender"             : "M",
        "first"              : "John",
        "last"               : "Sam P",
        "phone"              : "971557802482",
        "email"              : "John@abc.com",
        "birth_date"         : "1970-12-01"
        "nationality"        : "LB",
        "country"            : "AE",
        "state_city_emirate" : "LB",
        "home_location"      : "Tecom",
        "work_location"      : "Discovery Gardens",
        "pin"                : "1234"
    }
}

EXAMPLE RESPONSE:
{
    "status" : "SUCCESS"
}

Send Update Profile Email

This call is executed to send an Email after a customer profile is updated.

Request elements

Parameter Type Required Description
email String Yes Email ID of the customer

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com/online/email/update_profile

{
    "email": "abc@urbanbuz.com"
    }

EXAMPLE RESPONSE:

{
    "status" : "SUCCESS"
}

Brands

Get brands

This call is executed to obtain all brands registered with a program.

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/online/brands


EXAMPLE RESPONSE:

{
  "brand_id" ​: ​20​, 
  "name"     ​: ​"Bershka" 
}, 
{ 
 "brand_id" ​: ​21​,
 "name"     ​: ​"Zara" 
}

Get categories

This call is executed to obtain the product categories associated with the brand.

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/online/categories

EXAMPLE RESPONSE:
{
  "id" ​: ​20​, 

  "name" ​: ​"Fashion & Accessories" 

},
 
{ 
"id" ​: ​21​,
 "name"  ​: ​"Beauty&Wellness" 
}

Inventory

Submit item master

This call is executed to create or update an item master.

Request elements

Note: The fields that are not available in the request elements will move under businessFields, as shown in the example request.

Parameter Type Required Description
sku String Yes Alphanumeric code that identifies a product and helps track inventory
name String Yes Name of the product
description String No Detailed description about the product
link String No Link to the product URL (example: e-commerce URL of the product)
image String No Product image URL
brand String No Product brand
gender String No Targeted gender
color String No Product color
country String No Country of origin of the product
inventoryType String No Type of the inventory (example: product/service)
unit String No Type of the unit (example: kg/piece)
unitPrice Decimal No The unit price of the product
businessFields: CATEGORY String No Product category
businessFields: LINE String No Business line of the product

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST

POST http://[subdomain].urbanbuz.com/program/inventory

[
  {
    "sku": "EC-00002-1948574",
    "name": "Apple iPhone Xs",
    "description": "iPhone Xs 256GB Gold",
    "link": "",
    "image": "",
    "brand": "Apple",
    "gender": "UNISEX",
    "color": "Gold",
    "country": "USA",
    "inventoryType": "product",
    "unit": "Piece",
    "unitPrice": "4089",
    "businessFields": {
      "CATEGORY": "Smart Phone",
      "LINE": "Luxury Brand"
    }
  }
]
    
EXAMPLE RESPONSE
 {
     "created":70,
     "updated":20
}

Transaction

Submit transaction

This call is executed to allow to submit new as well as existing transaction. The transaction receipt will be the key for the submission.

Request elements

Parameter Type Required Description
customer.accountId String Yes Unique ID generated for the customer
customer.phone String Yes Phone number of the customer
customer.email String Yes Email ID of the customer
receipt String Yes Transaction’s unique identity
openTime Date Yes Transaction’s open time
closeTime Date Yes Transaction’s time of closing
operatorId String No Cashier’s unique identity
operatorName String No Cashier’s name
deviceId String No POS terminal’s unique identity
deviceName String No POS terminal’s name
billed Decimal Yes Transaction’s gross total
paid Decimal Yes Transaction’s net paid
redeemed Decimal Yes Transaction’s net paid in loyalty redemption
billDiscount Decimal Yes Transaction’s total bill level discount
itemDiscountTotal Decimal Yes Transaction’s total item level discount
billTax Decimal Yes Transaction’s total bill level tax
itemTaxTotal Decimal Yes Transaction’s total item level tax
sku String Yes Line item’s unique identifier
qty Decimal Yes Line item’s quantity
unitPrice Decimal Yes Line item’s gross unit price
payments.name String Yes Currency type (e.g. UAE currency)
payments.typeName String Yes Payment type (e.g. Cash)
payments.amount Decimal Yes Payment amount
payments.referenceId String Yes Unique identity of the voucher if voucher is set to true
redemption Boolean Yes True: Indicates that the voucher is redeemable
voucher Boolean Yes True: Indicates that the voucher has been assigned to the customer

API Validations on the values

Field Description
itemTaxTotal This should be the total of all the taxes in the items (Sum of items.tax*items.qty)
itemDiscountTotal This should be the total of all the discounts in the items (Sum of items.discount.amount*items.qty)
billed This should be a sum of all items, taxes and extras, that is,

Sum(items.unitPrice*qty)+ Sum(extras.amount)+ billTax+ itemTaxTotal

paid This should be billed-billDiscount-itemDiscountTotal-redeemed

Error messages

Error Code Error Message
1004 The following field is not unique
1006 The following fields are invalid
1002 Fields are empty
1007 The following field cannot be updated
EXAMPLE REQUEST

PUT http://[subdomain].urbanbuz.com/transaction/transactions/submit
{
  "customer": {
    "accountId": "03000000252",
    "phone": "971551467246",
    "email": "john@email.com",
  },
  "receipt": "T3HH17E7E1GK113474AQQ4J",
  "operatorId": "111111",
  "openTime": "2018-09-07 20:01:01",
  "closeTime": "2018-09-07 20:01:33",
  "billed": 1260,
  "paid": 1060,
  "redeemed": 200,
  "billDiscount": 0,
  "itemDiscountTotal": 0,
  "billTax": 0,
  "itemTaxTotal": 60,
  "deviceId": "301", 
  "items": [
    {
      "sku": "9999999",
      "name": "Product Name",
      "qty": 1,
      "unitPrice": 1200,
      "tax": 60,
     }
    ],
      "payments": [
          {
        "name": "AED_CURRENCY",
        "typeName": "Cash",
        "referenceId": null,
        "amount": 1060,
       "redemption": false,
        "voucher": false
      },
    {
      "name": "VOUCHER_REDEMPTION",
      "typeName": "Voucher",
      "referenceId": "7kwPsl",
      "amount": 200,
      "redemption": true,
      "voucher": true
    }
   ]
  }
    
EXAMPLE RESPONSE
 {
    "status" : "success"
}

Cancel transaction

This call is executed to allow to cancel/delete an existing transaction. The transaction receipt will be the key for the cancellation.

Request elements

Parameter Type Required Description
receipt String Yes Receipt for the transaction
openTime Date Yes Opentime of the transaction

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

DELETE http://[subdomain].urbanbuz.com/transaction/transactions
{
  "receipt": "123987",
  "openTime": "2017-05-14 10:33:15"
}


EXAMPLE RESPONSE:
class="wikitable"

{
  "status": " SUCCESS"
}

Loyalty

Get loyalty posting by account ID

A loyalty posting is a record of the points credited and debited to an account. This call is executed to obtain the list of points credited and debited to an account, and also the tier details of the member. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST: 
GET http://[subdomain].urbanbuz.com/program/loyalty/
    posting?accountId=f64f2940-fae4-11e7-8c5f-ef697603


EXAMPLE RESPONSE:
[
  {
    "id": 697603,
    "tierOrder": 1,
    "progId": 11,
    "userId": 6459979,
    "triggerId": 11,
    "triggerName": "Visits",
    "tierName": "Tier name",
    "credit": 500,
    "creditValue": 10,
    "debit": 0,
    "debitValue": 0,
    "currency": "AED",
    "postingDate": "2018-05-25 07:30:16 UTC",
    "txnDate": "2018-05-25 00:00:00 UTC",
    "receipt": "585720",
    "branchId": 838,
    "branchName": "Branch name",
    "brandId": 76,
    "brandName": "Brand name",
    "countryIso": "AE",
    "country": "United Arab Emirates",
    "type": 2
}
]

Send OTP and validate redemption

This call is executed to generate OTP for validating the redemption.

Request elements

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
redemption.value BigDecimal Yes Value of the Redemption

Error messages

Error Code Error Message
1006 The following fields are invalid
EXAMPLE REQUEST:
 
POST http://[subdomain].urbanbuz.com/program/accounts/otp/loyalty
{
  "accountId": "ba215440-430d-11e8-842f-0ed5f89f718b",
  "redemption": {
    "value": "16.5"
  }
}

EXAMPLE RESPONSE:

 {
  "status": "success",
  "otp": "2459",
  "redemption": {
    "point": "1650",
    "value": "16.5"
  },
  "loyalty": {
    "program": {
      "name": "Loyalty Program Name",
      "logo": "URL path to image.jpg"
    },
    "tier": {
      "name": "Loyalty Tier 1",
      "logo": "URL path to image.jpg",
      "order": 1,
      "expiry": "2019-01-01"
    },
    "wallets": [
      {
        "countryIso": "AE",
        "currency": "AED",
        "point": 1570,
        "value": 15.75
      }
    ],
      "redeemable": {
      "point": 1000,
      "value": 10,
      "currency": "AED"
  },
   "expiry": {
      "point": 256,
      "date": "2018-07-03"
  },
  "reason": null
}

EXAMPLE RESPONSE (FAILURE)

 {
  "status": "failure",
  "reason": {
    "errorCode": "1017",
    "errorMessage": "Insufficient points"
  },
  "otp": null,
  "loyalty": {
    "program": {
      "name": "Loyalty Program Name",
      "logo": "URL path to image.jpg"
    },
    "tier": {
      "name": "Loyalty Tier 1",
      "logo": "URL path to image.jpg",
      "order": 1,
      "expiry": "2018-01-01"
    },
    "wallets": [
      {
        "countryIso": "AE",
        "currency": "AED",
        "point": 1575,
        "value": 15.75,
        "expiry": "2018-05-03"
      }
    ]
  }
}

Vouchers

Get vouchers of customer

This call is executed to obtain the list of all vouchers associated with a particular customer, which includes Available, Expired, and Already Used vouchers for that customer.

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as a query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:
GET http://[subdomain].urbanbuz.com/online/{token}/vouchers

EXAMPLE RESPONSE:

 {
    "title"   : "Voucher A",
    "icon"    : "https://urbanbuz.com/images/vouchera.jpg",
    "code"    : "7bf147",
    "issued"  : "2018-01-01",
    "expires" : "2018-02-01",
    "value"     : "20",
    "valueType" : "percentage",
    "status"    : "active"
}, {
    "title"     : "Voucher B",
    "icon"      : "https://urbanbuz.com/images/voucherb.jpg",
    "code"      : "e3a962",
    "issued"    : "2017-01-01",
    "expires"   : "2018-01-01",
    "value"     : "100",
    "valueType" : "fixed",
    "status"    : "expired"
}, {
    "title"     : "Voucher C",
    "icon"      : "https://urbanbuz.com/images/voucherc.jpg",
    "code"      : "5b103c",
    "issued"    : "2017-01-01",
    "expires"   : "2018-01-01",
    "value"     : "10",
    "valueType" : "percentage",
    "status"    : "redeemed",
    "redeemed"  : "2017-12-30 12:34:56",
    "redeemedBranch" : {
        "name"       : "Dubai Mall",
        "brandName"  : "Brand A"
    }
}

Get vouchers by account ID

This call is executed to obtain the list of vouchers by account ID. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/vouchers?accountId=f64f2940
    

EXAMPLE RESPONSE:

[{
    "title"     : "Voucher A",
    "icon"      : "https://urbanbuz.com/images/vouchera.jpg",
    "code"      : "7bf147",
    "issued"    : "2018-01-01",
    "expires"   : "2018-02-01",
    "value"     : "20",
    "valueType" : "percentage",
    "status"    : "active"
}, {
    "title"     : "Voucher B",
    "icon"      : "https://urbanbuz.com/images/voucherb.jpg",
    "code"      : "e3a962",
    "issued"    : "2017-01-01",
    "expires"   : "2018-01-01",
    "value"     : "100",
    "valueType" : "fixed",
    "status"    : "expired"
}, {
    "title"     : "Voucher C",
    "icon"      : "https://urbanbuz.com/images/voucherc.jpg",
    "code"      : "5b103c",
    "issued"    : "2017-01-01",
    "expires"   : "2018-01-01",
    "value"     : "10",
    "valueType" : "percentage",
    "status"    : "redeemed",
    "redeemed"  : "2017-12-30 12:34:56",
    "redeemedBranch" : {
        "name"       : "Dubai Mall",
        "brandName"  : "Brand A"
    }
}]

Order

Submit order

This call is executed to allow to submit a new order.

Request elements

Parameter Type Required Description
customer.accountId String Yes Unique ID generated for the customer
customer.phone String Yes Phone number of the customer
customer.email String Yes Email ID of the customer
receipt String Yes Transaction’s unique identity
openTime Date Yes Transaction’s open time
closeTime Date Yes Transaction’s time of closing
operatorId String No Cashier’s unique identity
operatorName String No Cashier’s name
deviceId String No Unique identity of the POS terminal
deviceName String No Name of the POS terminal
billed Decimal Yes Transaction’s gross total
paid Decimal Yes Transaction’s net paid
redeemed Decimal Yes Transaction’s net paid in loyalty redemption
billDiscount Decimal Yes Transaction’s total bill level discount
itemDiscountTotal Decimal Yes Transaction’s total item level discount
billTax Decimal Yes Transaction’s total bill level tax
itemTaxTotal Decimal Yes Transaction’s total item level tax
items.sku String Yes Line item’s unique identifier
items.qty Decimal Yes Line item’s quantity
items.unitPrice Decimal Yes Line item’s gross unit price
items.discount.amount Decimal Yes Line item’s discount amount
payments.typeName String Yes Payment type (e.g. Cash)
payments.amount Decimal Yes Payment amount

Error messages

Error Code Error Message
1004 The following field is not unique
1006 The following fields are invalid
1002 Fields are empty
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com/transaction/orders/submit
{
    "customer" : {
        "accountId"     : "f64f2940-fae4-11e7-8c5f-ef379131"
    },
    "receipt"           : "REC-001",
    "openTime"          : "2018-01-31 11:01:21",
    "closeTime"         : "2018-01-31 11:01:21",
    "operatorId"        : "STAFF001",
    "operatorName"      : "John",
    "salesPersonId"     : "STAFF001",
    "salesPersonName"   : "John",
    "deviceId"          : "POS001",
    "deviceName"        : "Front-desk",
    "billed"            : 105,
    "paid"              : 85,
    "redeemed"          : 0,
    "billDiscount"      : 0,
    "itemDiscountTotal" : 20,
    "billTax"           : 0,
    "itemTaxTotal"      : 5,
    "items" : [{
        "sku"           : "Item A",
        "qty"           : 2,
        "unitPrice"     : 50,
        "tax"           : 5,
        "discount" : {
            "amount"    : 20
        }
    }],
    "payments" : [{
        "typeName"      : "Cash",
        "amount"        : 80
    }],
    "extras" : [{
        "name"      : "Delivery Charge",
        "amount"        : 5
    }]

}

EXAMPLE RESPONSE:

{
    "status" : "success"
}

Update order status

This call is executed to allow to update the status of the order placed (Confirmed/Dispatched/Delivered/Canceled).

Request elements

Parameter Type Required Description
receipt String Yes Transaction’s unique identifier
status Decimal Yes Status of the placed order

Error messages

Error Code Error Message
1004 The following field is not unique
1006 The following fields are invalid
1002 Fields are empty
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com/transaction/orders/status
{
    "receipt"           : "REC-001",
    "status"            : "confirmed"
}

EXAMPLE RESPONSE:
 {
    "status" : "success"
}

Appointment

Submit appointment

This call is executed to allow to submit the appointment that has been made. Validations:

  • Reference number should be mandatory and unique across branches.
  • Customer object should have any of the following identifiers: phone/email/customerId
  • Line items of the appointment should be added to the “items” array of line item object.
  • “Sku” should be mandatory for each line item.

Request elements

Parameter Type Required Description
customer_id String Yes Unique identity assigned to the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
referenceNumber String Yes Reference number for the appointment made
generated Date Yes Date and time when the appointment was made and registered
start Date Yes Start date and time of the appointment
end Date Yes End date and time of the appointment
rebooking Boolean Yes False indicates no rebooking is permitted for the booked appointment
operatorId String Yes ID of the staff who recorded the appointment
operatorName String Yes Name of the staff who recorded the appointment
deviceId String Yes ID of the device that was used to register the appointment
deviceName String Yes Name of the device that was used to register the appointment
status Boolean Yes open/confirmed/closed/canceled/no-show/deleted: Status of the booked appointment
receipt String Yes The appointment receipt
source String Yes The medium through which the appointment was made (online booking)
sku String Yes Unique identifier for the service purchased (appointment)
name String Yes Name of the consulting doctor
duration String Yes Duration of the appointment
consultantId String Yes Unique identity of the consulting doctor
consultantName String Yes Name of the consulting doctor
consultantType String Yes Type of consultant (doctor)

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com//appointments/submit
{
  "customer": {
	"customer_id": "BSNS-10249",
	"phone": "971581111148",
	"email": "jhon2@email.com"
  },
  "referenceNumber": "APPO-2017-10-19-001",
  "generated": "2017-10-22 10:33:15",
"start": "2017-11-14 10:00:00",
  "end": "2017-11-14 11:00:00",
  "rebooking": false,
  "operatorId": "Moo-Foo",
  "operatorName": "Moo Operator",
  "deviceId": "Foo Device",
  "deviceName": "Foo Device Name",
  "status": "open/confirmed/closed/canceled/no-show/deleted",
  "checkin": "2017-05-14 10:33:15",
  "receipt": "BSNS-201705141056",
  "source": "Online Booking",
  "items": [
	{
  	"sku": "DR-CONSU-001",
  	"name": "Doctor Consultant",
  	"start": "2017-11-14 10:00:00",
  	"end": "2017-11-14 11:00:00",
  	"duration": 30,
  	"consultantId": "DR-001",
  	"consultantName": "John",
            "consultantType": "Doctor"
	}
  ]
}
}


EXAMPLE RESPONSE:
 {
    "status" : "success"
}

Update appointment status

This call is executed to change the status of an existing transaction. The reference number will be the key for the update.

Request elements

Parameter Type Required Description
customer_id String Yes Unique identity assigned to the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
referenceNumber String Yes Reference number for the appointment made
checkin String Yes Checkin by the customer
status String Yes Status of the appointment (closed)

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com//appointments/submit
{
 "customer": {
	"customer_id": "BSNS-10249",
	"phone": "971581111148",
	"email": "jhon2@email.com"
  },
  "referenceNumber": "BSNS-201705141033",
  "checkin": "2017-05-14 10:33:15",
  "status": "closed"
}
|}

EXAMPLE RESPONSE:

 {
    "status" : "success"
}

Campaign

Schedule campaign

Campaigning is done as part of marketing strategy. Campaigns are categorized as generic (Email and SMS) and voucher campaign. This call lets you schedule a campaign for customers as part of marketing either by following your business marketing calendar or by scheduling based on an event of local marketing importance.

Request elements

Parameter Type Required Description
title String Yes Title of the campaign (example: Skin Products Marketing)
channel Number Yes Channel represents SMS or Email ( 1 For SMS and 2 For Email)
countries List Yes List of countries targeted
category String Yes Communication Category ID (This will be shared by UrbanBuz through a lookup values or an API call)
communication.subject String Yes Subject of the Email. Mandatory if the channel is Email
communication.body String Yes Campaign content
communication.senderId String Yes Sender ID of the Campaign (Eg:- Kaya Clinic for SMS , no-reply@kayame.net for Email)
schedule.date Date Yes Date and time of the campaign to be send (Eg: 2018-05-20 15:30:00)
schedule.timeZone String Yes Time zone of the schedule
target String Yes Name of the target file uploaded

Error messages

Error Code Error Message
1002 Fields are empty
1010 At least one of the following fields is required
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/marketing/campaigns
{
  "title": "We Miss you",
  "channel": 2,
  "countries": [
    {
      "countryIso": "AE"
    },
    {
      "countryIso": "KW"
    }
  ],
  "category": "10",
  "communication": {
    "subject": "We Miss You",
    "body": "<p>Dear %%first%% We miss you </p>",
    "senderId": "Kaya"
  },
  "schedule": {
    "date": "2018-05-20 17:30:00",
    "timeZone": "Asia/Dubai"
  },
  "target": "kaya/Campaign_1527683113.csv"
}

EXAMPLE RESPONSE:

 {
    "status" : "success",
    "campaign" : {
         "campaignId" : "f64f2940"
    }
}

Reports

The following sections describe the reporting API calls.

Fetch accounts

This call lets you obtain the list of accounts (with the details of the account) within a given time range.

Request elements

Parameter Type Required Description
start Date Yes Start date and start time of retrieving data
end Date Yes End date and end time of retrieving data

Error messages

Error Code Error Message
1005 No data found in the database for the sent request parameters
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/program/
     reports/accounts?page=1&size=10
{
 "start": "2017-05-14 10:33:15",
"end": "2017-05-14 10:33:15
}


EXAMPLE RESPONSE:

 {
"pageNumber": 1,
"pageSize": 3,
"totalCount": 2242,
"data": [
{
"profile": {
"phone": "971506611149",
"email": null,
"accountId": "ADBC29712",
"first": "Saeed",
"last": "Mohammed Alzaabi",
"birthdate": "1986-04-05",
"gender": "M",
"city": null,
"country": null,
"nationality": null,
"language": null,
"businessFields": {
"title": "Mr.",
"ethnicity": "Asian"
}
},
"originated": {
"brand": "Ghawali",
"name": "Ghawali-DUBAI MALL",
"branchCode": "13003",
"countryName": "United Arab Emirates",
"countryIso": "AE"
}
}
]
}

Fetch vouchers

Voucher is a type of a reward provided to customers. You can create vouchers to award your customers based on different criteria and to encourage a certain behavior. This API fetches the voucher issued/redeemed/expired within a given time range.

Request elements

Parameter Type Required Description
start String Yes Start date to fetch the vouchers
end String Yes End date to fetch the vouchers

Response elements

Parameter Type Required Description
code String Yes This is the voucher code
issued Date Yes Issued date of the voucher
redeemed Date No Redeemed date if the voucher is redeemed
expiry Date Yes Expiry date of the voucher
enabled boolean Yes True for enabled, false for disabled
issuedBranch Object Yes Details of the branch issuing the voucher
redeemedBranch Object No Branch details where the voucher was redeemed
campaign Object No Campaign title for which the voucher was issued
reward Object No Reward title for which the voucher was issued
voucher Object Yes Voucher details
voucher.title String Yes Voucher title
valueFixed Integer No Value if it is a fixed value voucher
valueDiscount Integer No Discount in percentage
redeemableBranchList Object No List of branches where voucher can be redeemed
country Object Yes Country for which the voucher was setup
brand Object Yes Brands for which the voucher was setup
customer Object Yes Details of the customer (phone/email/customer ID) to whom the voucher is issued

Error messages

Error Code Error Message
400 Bad request
404 Given Resource not found
EXAMPLE REQUEST:

POST http://api3.urbanbuz.com/program/reports/vouchers?page=1&size=100
{
   "start" : "2018-04-24 16:00:00",
   "end" : "2018-04-24 16:10:00"
}

EXAMPLE RESPONSE:

 {
   "pageNumber": 1,
  "pageSize": 100,
  "totalCount": 8,
  "offset": 0,
  "data": [
    {
      "id": 0,
      "code": "2cJRhV",                  
      "issued": "2018-04-24 16:07:00",    
      "redeemed": null,       
      "expires": "2019-04-24 16:07:00",  
      "enabled": true,
      "issuedBranch": {
         "brand": "Zippy",
         "name": "Dubai Mall",
         "branchCode": "S069",
         "countryIso": "AE",
       },
      "redeemedBranch": null,
      "campaign": {
         "title": "First Shopping voucher"
       }
      "reward": {
         "title": "First Shopping reward"
       },
      "voucher": {
        "title": "AED 100 Voucher UAE",     
        "icon": "https://newcem.urbanbuz.com/upload/images/xxx.png",
        "valueFixed": 0,
        "valueDiscount": 10,                
        "redeemableBranchList": [
         {
         "brand": "Zippy",
         "name": "Dubai Mall",
         "branchCode": "S069",
         "countryIso": "AE",
         },
         {
         "brand": "Zippy",
         "name": "Marina Mall",
         "branchCode": "S052",
         "countryIso": "AE",
        }
        ],
        "country": {
          "countryIso": "AE",
          "countryName": "United Arab Emirates"
        },
        "brands": [
          "Brands",
          "POP"
        ]
      },
      "customer": {  
        "phone": "971507571736",
        "email": "mmm2111@yahoo.com",
        "customerId": "151501"
      }
    }
  ]
}

Fetch transactions

This call lets you obtain the transaction report for the specified time range.


Request elements

Parameter Type Required Description
start Date Yes Start date and time
end Date Yes End date and time

Error messages

Error Code Error Message
1005 Data not found
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/program/
     reports/transactions?page=1&size=10
{
  "start": "2017-05-14 10:33:15",
  "end": "2017-05-14 10:33:15
}

EXAMPLE RESPONSE:

 {
  "pageNumber": 1,
  "pageSize": 1,
  "totalCount": 28,
  "offset": 0,
  "data": [
    {
      "transaction": {
        "receipt": "971552456810-18",
        "openedAt": "2018-01-22 13:59:00",
        "closedAt": null,
        "billed": 210,
        "paid": 100,
        "redeemed": 0,
        "billDiscount": 0,
        "itemDiscountTotal": 0,
        "billTax": 0,
        "itemTaxTotal": 0,
        "operatorId": null,
        "operatorName": null,
        "deviceId": "T004",
        "deviceName": "OASIS COUNTER 1",
        "items": [
          {
            "id": null,
            "sku": "S2597",
            "name": "SUIT2/375",
            "description": null,
            "type": "P",
            "inventoryId": null,
            "inventoryCategoryId": null,
            "qty": 1,
            "unit": null,
            "unitPrice": 60,
            "tax": null,
            "lineAmount": 60,
            "discount": null,
            "customFields": null
          },
          {
            "id": null,
            "sku": "S2600",
            "name": "SUIT2/895",
            "description": null,
            "type": "P",
            "inventoryId": null,
            "inventoryCategoryId": null,
            "qty": 1,
            "unit": null,
            "unitPrice": 100,
            "tax": null,
            "lineAmount": 100,
            "discount": null,
            "customFields": null
          },
          {
            "id": null,
            "sku": "S2599",
            "name": "SUIT2/585",
            "description": null,
            "type": "P",
            "inventoryId": null,
            "inventoryCategoryId": null,
            "qty": 2,
            "unit": null,
            "unitPrice": 25,
            "tax": null,
            "lineAmount": 50,
            "discount": null,
            "customFields": null
          }
        ],
        "payments": [
          {
            "id": null,
            "name": null,
            "typeId": null,
            "typeName": "Master Card",
            "date": null,
            "paymentAt": null,
            "amount": 100,
            "referenceId": null,
            "redemption": false,
            "customFields": null
          }
        ],
        "extras": null,
        "customFields": null
      }
    }
  ]
}

Fetch and export campaigns

This call is executed to retrieve all the details pertaining to a scheduled campaign (SMS campaign or Email campaign) and export these details to obtain the statistics of the scheduled campaigns. The campaign details mainly include:

  • Campaign scheduled date
  • Location where the campaign is scheduled
  • Count of sent, delivered and undelivered campaigns, and so on.


Request elements

Parameter Type Required Description
start Date Yes Start date and start time of the SMS/Email campaign schedule
end Date Yes End date and end time of the SMS/Email campaign schedule
resultEndPoint String Yes The endpoint to update when the result is ready
export Boolean Yes To obtain the statistics of the scheduled campaign in the form of a csv file structure.

Error messages

Error Code Error Message
1005 No data found in the database for the sent request parameters
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/program/reports/campaigns?export=true
{
  "start": "2018-09-10 00:00:00",
  "end": "2018-09-10 23:59:59,
  "resultEndPoint": "https://[subdomain].urbanbuz.com/campaigns/results"
}

'''Example request''' that generates the csv file 
(displaying the details of the campaign) when the parameter value 
'''export''' is set to be '''true'''.

 POST http://company.com/campaigns/results

{
"jobId": "a1fTstz347",
"status": "Generated",
"fileName": Campaign_SMS_a1fTstz347_20180909.csv",
}

EXAMPLE RESPONSE:

{  
  "totalCount": 6,
  "status": "Generating",
  "fileName": "Campaign_SMS_a1fTstz347_20180909.csv",  
  "jobId":1246789454645,
  "data": [
    {
      "campaignId": "a1fTstz347",
      "campaignDescription":"Discount on bags"
      "channel": "SMS",
      "scheduled": "2018-09-09 14:00:00",
      "lastUpdated":"2018-09-10 11:25:00",
      "timeZone": "Asia/Dubai",
      "sent": "15000",
      "delivered": "13000",
      "undelivered": "2000",
      "filters": {
        "location": {
          "country": [{
              "countryIso": "AE",
              "name": "United Arab Emirates"
            }
          ],
          "brand": [{
              "name": "Elann"
            }
          ],
          "profile": [{
              "phoneCountry": "AE"
            },
            {
              "gender": "M"
            }
          ],
          "transaction": [{
              "active": {
                "from": "2017-01-01"
              }
            }
          ]
        }
      }
    }
  ]
}

Status code and error messages

API requests can at times result in errors and return appropriate status code that help you identify the error type.

The following table describes standard error codes returned by the APIs:

Status code Text Description
200 OK Indicates that the request was correct and sent to the core for further processing.
400 Bad request Indicates that the request does not contain all the information/ parameters in order to proceed. This

error is returned from the Resource class. Domain validation errors, missing data, etc. are some examples.

401 Not authorized Indicates that the request was not authorized and cannot proceed. This error code is

returned from Authentication Filter class.

500 Internal server error The server encountered an unexpected condition which prevented it from fulfilling the request.

This need to be analyzed further.

The following table describes the standard error codes returned by UrbanBuz APIs.

Error code Description
1001 The request payload is empty
1002 Certain field values are empty
1003 Internal Server Error
1004 Certain fields are not unique
1005 No data found in the database for the sent request parameters
1009 No data found in the database for the sent request parameters
1010 At least one of the fields required to be filled

Timestamp

Timestamps are returned in the UTC format: YYYY-MM-DDTHH:MM:SSZ