NAV
shell ruby python javascript

Introduction

Welcome to the Hong Leong Yamaha Motor - Loyalty Management System (LMS) API! The API provides a RESTful interface. You can use the LMS API endpoints to interact with LMS resources like members, merchants, points, transactions, campaigns, ...

The API accepts JSON encoded requests and returns JSON content. The UTF-8 character encoding is used throughout.

Response Structure

The API is organised around resources (members, merchants, transactions, ...).

Collection

Sample response

{
  "count": 2,
  "nextPageToken": "eyJjb250YWN0SWQiOnsicyI6Ijc5YTRkZDFhLTU0ZDEtNDMyMS05ODBmLTIyNDI2ODk2NzcyMSJ9LCJjcmVhdGVUaW1lIjp7InMiOiIyMDIxLTAyLTEyVDExOjA1OjM1LjI2N1oifSwiYXBwSWQiOnsicyI6IjJkMDdkZjI3LWNjOWUtNDUzMy1hMzIxLWRmY2ZlMDQ5YTZlYSJ9fQ==",
  "data": [
    {
   "id": "edc3fd41-6770-4210-bf0a-e608b93d2e64",
   "currentTier": "member",
   "membershipNumber": "124-4752-188",
   "memberSince": "2020-02-07",
   "name": "Kuning bin Mayang",
   "gender": "male",
   "dateOfBirth": "7/25/1972",
   "email": "kuning.mayang@gmail.com",
   "mobile": {
     "countryCode": "+60",
     "mobileNumber": "0390764779"
   },
   "mobileVerifiedStatus": "notVerified",
   "address": {
   "addressLine1": "125 Jln Cheras Batu 11 Kampung Baru China",
   "addressLine2": "43200 Cheras 43200 Malaysia Cheras 43200 Malaysia",
   "postCode": "43200",
   "city": "Cheras",
   "state": "Selangor"
   },
   "cards": [{
    "id": "03ef5095-03f9-4b3e-a526-a6bf0001c1d1",
    "cardNumber": "124475213188",
    "issuedOn": "2021-01-29T09:58:44.635Z"
   }]
  }
  ]
}

A collection response is encapsulated in the data object that contains an array of results. The count and nextPageToken parameters are also present to handle pagination.

Resource

Sample response

{
    "id": "e7e3b4d6-8ee8-4b15-b57c-4f2a43190553",
    "username": "githika",
    "membershipNumber": "995-1175-260",
    "name": "Githika Ramesh",
    "profileImageName": "sample1",
    "tier": "owner",
    "cards": [
        {
            "id": "573db3d9-2efd-4b56-acad-07706682129e",
            "cardNumber": "843664669622",
            "issuedOn": "2021-04-27",
            "cardType": "virtual"
        },
        {
            "id": "4071e25d-0f29-44de-84b7-fd5488d0e498",
            "cardNumber": "123456789012",
            "issuedOn": "2021-04-28",
            "cardType": "physical"
        }
    ],
    "mobile": {
        "countryCode": "+60",
        "mobileNumber": "0390764779"
    },
    "addresses": [
        {
            "addressLine1": "125 Jln Cheras Batu 11 Kampung Baru China",
            "addressLine2": "43200 Cheras 43200 Malaysia Cheras 43200 Malaysia",
            "postCode": "43200",
            "city": "Cheras",
            "state": "Selangor",
            "addressType": "Home"
        }
    ],
    "gender": "female",
    "email": "githika.ramesh@hummingwave.com",
    "dateOfBirth": "1972-07-25",
    "mobileVerifiedStatus": "verified",
    "emailVerifiedStatus": "notVerified",
    "bikes": [
        {
            "id": "c398fdf0-3d5e-42db-9795-184eed980bfa",
            "plateNumber": "1234567",
            "icNumber": "691206-10-5331",
            "vocVerificationMode": "manual",
            "status": "pending"
        }
    ]
}

A resource response - as in GET /member/{member-id} - is not encapsulated.

Authentication

Authorisation with Bearer Token

Endpoints are authorised with an access token using the Bearer Token mechanism. Access tokens are short-lived, with a TTL of an hour. Use the Sign-In endpoint to get an access token and a refresh token. There are separate Sign-In endpoints for members, merchants and ops users.

A fresh access token can be obtained with the Refresh Token endpoint using the refresh token.

Authorisation with API Key

Endpoints that come into play when a user is not signed in use the API Key mechanism for authorisation. Add this authorization credentials to the header of the HTTP request.

key: "x-api-key"

value: <API key>

Errors

In all cases, the API will return an HTTP Status Code that indicates the nature of the failure (below). A response body in JSON format containing additional information.

In the event of a server error the response body will contain an error phrase. The phrase is used by the developer team to quickly look up the incident that caused the server error.

The most common status codes are:

Code Meaning Description
200 Success The request executed successfully. If data was requested, it will be available at the top level of the response body.
201 Created (for object creation) Its information is available in the data field at the top level of the response body. The API URL where the object can be retrieved is also returned in the Location header of the response.
400 Bad request This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of the request and try again. The error phrase will have additional information.
401 Unauthorized A valid authentication token was not provided with the request, so the API could not associate a user with the request.
403 Forbidden The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you try to read or write to objects or properties that the user does not have access to.
404 Not found Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.
405 Method not allowed This action (HTTP verb) is not allowed for the resource.
409 Conflict When a request conflicts with the current state of the server. As an example, the server will return this code for a request to sign-up a user with an email address when a user with the email address already exists.
423 Locked The resource is locked. For example, a member sign-in may be disabled for period of time due to too many failed sign-in attempts.
429 Too many requests You have exceeded one of the enforced rate limits in the API. See the documentation on rate limiting for more information.
500 Internal server error There was a problem with the LMS server.

Mozilla maintains a good description of HTTP response codes.

Rate Limits

The API design has a provision for rate limits. The limit can be set per user per month, and the rate of requests allowed per second. The exact limit will be decided closer to go-live.

Versions

The API will be versioned. Any changes will be reflected only in newer versions, so users on an older version will not be affected by changes.

Gzip

The API compresses content of a size greater than 850 bytes. API requests should include the Accept-Encoding header with a value of gzip, deflate, and identity.

Data Types

The API uses the following data types.

Type Description
String A simple quoted string, following standard JSON rules as specified in the JSON spec.
Number An integer or a decimal number, transmitted as a JSON number. Hexadecimal formats are not supported.
Boolean A JSON boolean, the value being true or false.
Array A JSON array. Each element contains a payload that will be described.
Date Date in the ISO 8601 format. (Example: 2020-03-06)
Time Time in UTC in the ISO 8601 format with millisecond precision. (Example: 2020-03-06T09:58:44.635Z)
UUID A UUID string, preferably a version 4 UUID. Example: f30ccccf-54a8-49bf-b3e4-6eee274810ab.

Pagination

API endpoints that return a large number of results are paginated.

Endpoints have a limit parameter. While the parameter is optional, requests should specify the limit for faster responses. Endpoints return a maximum of 1,000 results if the limit is not specified.

Paginated results return a nextPageToken parameter. It can be used to get the next page of results. The absence pf

Postman Collection

A Postman collection of the API is available at ****.

Members

Resource

{
    "id": "e7e3b4d6-8ee8-4b15-b57c-4f2a43190553",
    "username": "githika",
    "membershipNumber": "995-1175-260",
    "name": "Githika Ramesh",
    "profileImageName": "sample1",
    "tier": "owner",
    "cards": [
        {
            "id": "573db3d9-2efd-4b56-acad-07706682129e",
            "cardNumber": "843664669622",
            "issuedOn": "2021-04-27",
            "cardType": "virtual"
        },
        {
            "id": "4071e25d-0f29-44de-84b7-fd5488d0e498",
            "cardNumber": "123456789012",
            "issuedOn": "2021-04-28",
            "cardType": "physical"
        }
    ],
    "mobile": {
        "countryCode": "+60",
        "mobileNumber": "0390764779"
    },
    "addresses": [
        {
            "addressLine1": "125 Jln Cheras Batu 11 Kampung Baru China",
            "addressLine2": "43200 Cheras 43200 Malaysia Cheras 43200 Malaysia",
            "postCode": "43200",
            "city": "Cheras",
            "state": "Selangor",
            "addressType": "Home",
            "defaultStatus": "defaultAddress"
        }
    ],
    "gender": "female",
    "email": "githika.ramesh@hummingwave.com",
    "dateOfBirth": "1972-07-25",
    "mobileVerifiedStatus": "verified",
    "emailVerifiedStatus": "notVerified",
    "bikes": [
        {
            "id": "c398fdf0-3d5e-42db-9795-184eed980bfa",
            "plateNumber": "1234567",
            "icNumber": "691206-10-5331",
            "vocVerificationMode": "manual",
            "status": "pending"
        }
    ]
}

Get multiple members

GET /members

Get a member

GET /members/{id}/profile

Member Sign-up

POST /members/sign-up

Member Sign-in

POST /members/sign-in

A member signs in with a username, mobileDetails, google, facebook or apple.

Sample Input Parameters for username 

{
   "credentialType": "username",
   "credentials": { 
    "username": "githika",
    "hashedPassword": "43f997e9b08a715ddedf1ac8c8d7fa388d45fca154359b4e553a62b92c5a7fdec4decf7e886da4b418345541ee53564bb1c32a750da65332fd8f896852149379"
   }
}

Sample Input Parameters for mobile

{
  "credentialType": "mobileNumber",
  "credentials": {
    "mobileDetails": {
      "mobile": {
        "mobileNumber": "8139921556",
        "countryCode": "+91"
      },
      "otp": "123456",
      "bypassCode": "123456"
    }
  }
}

Sample Input Parameters for Facebook

{
  "credentialType": "facebook",
  "credentials": {
    "facebook": {
      "faceBookId": "ac7ac68f-1b78-4a91-b8c3-b7cfea9de00e",
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJnaXRoaWthLnJhbWVzaEBodW1taW5nd2F2ZS5jb20iLCJpc3MiOiJITFlNIExNUyIsInR5cGUiOiJFbWFpbCBWZXJpZmljYXRpb24iLCJleHAiOjE2MjI2NDQxNjcsImlhdCI6MTYyMDA1MjE2NywiZW1haWwiOiJnaXRoaWthLnJhbWVzaEBodW1taW5nd2F2ZS5jb20iLCJqdGkiOiJkMzc5ZWExMy0wN2M0LTQzMGUtYjdmMC03MjIyMWU0NTEyYjUiLCJ0aW1lc3RhbXAiOiIyMDIxLTA1LTAzVDE0OjI5OjI3LjA1NTIwMloifQ.si6hPKo30gpvt1u3CYTOVjCaYIFa7ouOKIVCuS7nJNk",
      "name": "Githika",
      "gender": "female"
    }
  }
}

Sample Input Parameters for Google

{
  "credentialType": "google",
  "credentials": {
    "google": {
      "googleId": "3e9e449e-df88-4110-9bf0-f8dbbe1f631b",
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJnaXRoaWthLnJhbWVzaEBodW1taW5nd2F2ZS5jb20iLCJpc3MiOiJITFlNIExNUyIsInR5cGUiOiJFbWFpbCBWZXJpZmljYXRpb24iLCJleHAiOjE2MjI2NDQxNjcsImlhdCI6MTYyMDA1MjE2NywiZW1haWwiOiJnaXRoaWthLnJhbWVzaEBodW1taW5nd2F2ZS5jb20iLCJqdGkiOiJkMzc5ZWExMy0wN2M0LTQzMGUtYjdmMC03MjIyMWU0NTEyYjUiLCJ0aW1lc3RhbXAiOiIyMDIxLTA1LTAzVDE0OjI5OjI3LjA1NTIwMloifQ.si6hPKo30gpvt1u3CYTOVjCaYIFa7ouOKIVCuS7nJNk",
      "name": "Githika"
    }
  }
}

Sample Input Parameters for Apple

{
  "credentialType": "apple",
  "credentials": {
    "apple": {
      "appleId": "d68a9d68-4fc8-4280-829d-cef977e4f143",
      "token": "eyJraWQiOiJZdXlYb1kiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwcGxlaWQuYXBwbGUuY29tIiwiYXVkIjoibXkuY29tLnlhbWFoYS1tb3Rvci5ZYW1haGEtQ3VzdG9tZXItaU9TIiwiZXhwIjoxNjE5ODc3MDA5LCJpYXQiOjE2MTk3OTA2MDksInN1YiI6IjAwMTg0Ny5hNDI5MGM2MDFhMDU0OThkOTE3MDFmZjYwMzcwMjQyMy4xMzUwIiwiY19oYXNoIjoiVTB3VmlaWW0xSjhJWnVyTGNmYXhxQSIsImVtYWlsIjoiZ2VldDE5OTVAZ21haWwuY29tIiwiZW1haWxfdmVyaWZpZWQiOiJ0cnVlIiwiYXV0aF90aW1lIjoxNjE5NzkwNjA5LCJub25jZV9zdXBwb3J0ZWQiOnRydWUsInJlYWxfdXNlcl9zdGF0dXMiOjJ9.gfbuasH_AqkZXXtU2dMtTHaRxqu5TNxf5MFhmgg-hoc68e5ArlBPpPkAYLy8Z4dC5nW2rFn9531vzves174Ko5Rh5vWmcRs4EwHt_oyoNFzOiduuf54LStjKZYJubrbZUbaqBhvbDlZcNXq_DtelEzi2tU1bfo4_Q6w4MtZOWdyoZ0qzMKUK31z9zsvE0V36SyEAzw3xRRHbJr761jbo9yFleN0A_Phz8C_4S1zIEUY2QCDoWUkLh0NaDFMxTcPee2irWgY1qWRzAm3zpkiPgMlpVEQ9QCdzX0oUn9vrciPr5p7wDRd7N_XfooBjCaVQkSEB0Vzh4xxpUgoU1BKdgg",
      "name": "Githika"
    }
  }
}
Parameter Mandatory? Type Description
credentialType Yes String Possible values are username, emailAddress, mobileNumber, facebook, google, apple.
username Yes/No String Mandatory if the credentialType is username. Otherwise optional.
hashedPassword Yes/No String Mandatory if credentialType is username. Otherwise optional.
facebook Yes/No Object Mandatory if the credentialType is facebook. Otherwise optional.
facebookId Yes String The facebookId that you get from Facebook after sign in.
token Yes String The respective token from the social platform(facebook token, google token, apple idToken).
gender No String Possible values are male, female, others. Pass the value if you get it from the social platform.
name No String Pass the value if you get it from the social platform.
mobileDetails Yes/No Object Mandatory if the credentialType is mobileNumber. Otherwise optional.
otp Yes/No String Mandatory if credentialType is mobileNumber.

Endpoint Authentication

This endpoint uses a different REST API authorisation mechanism, as the user is unauthenticated. The API Key mechanism is used, with:

key: "x-api-key"

value: <API key>

Request

Sample request

{
    "emailAddress": "amit.singh@hummingwave.com",
    "hashedPassword": "43f997e9b08a715ddedf1ac8c8d7fa388d45fca154359b4e553a62b92c5a7fdec4decf7e886da4b418345541ee53564bb1c32a750da65332fd8f896852149379"
}

An Ops user can sign in using their email address and password.

Parameter Required? Type Description
username Yes String The username of the member, preferably trimmed.
emailAddress Yes String The email address of the member, preferably trimmed and in all lowercase. Either of username or email address is required.
hashedPassword Yes String The password, hashed with the SHA-512 variant of the SHA-2 algorithm.

Response

Sample response

{
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhMmJhNWM2ZS01NDY3LTRlODgtODk4MC02YzNkNDhjYTQ1ZDYiLCJncmFudF90eXBlIjoiYXV0aG9yaXphdGlvbi10b2tlbiIsImlzcyI6IllhbWFoYSBMTVMiLCJleHAiOjE2MTYxNDE4NTYsImlhdCI6MTYxNjEzODI1NiwianRpIjoiMDU4MDMyY2YtOWYxNS00ODU0LWI4NDItNmYyZGY3MTAwMzYzIn0.wArbHnGQlJ-burSKzjGcap5S1Hq3mTMs9FzozivjCbs",
    "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhMmJhNWM2ZS01NDY3LTRlODgtODk4MC02YzNkNDhjYTQ1ZDYiLCJncmFudF90eXBlIjoicmVmcmVzaC10b2tlbiIsImlzcyI6IllhbWFoYSBMTVMiLCJleHAiOjE5MzE0OTgyNTYsImlhdCI6MTYxNjEzODI1NiwianRpIjoiOGRkOTJiNzUtODQxMS00NDk5LWI4ZjMtZmY2MzY1N2FlN2NkIn0.p-zy7rGTjQbEb8EUfkh-8U1s3sGPCpixNqEbVKNecqc",
    "tokenType": "Bearer"
}

Sample decoded JWT access token

{
  "sub": "cfdfee61-40ac-4e56-9ad4-ba2640de614d",
  "grant_type": "authorization-token",
  "iss": "HLYM LMS",
  "userType": "member",
  "exp": 1619608587,
  "iat": 1619604987,
  "jti": "780a23ab-f68d-422c-b85e-498ba90732e8"
}

Sample decoded JWT refresh token

{
  "sub": "e7e3b4d6-8ee8-4b15-b57c-4f2a43190553",
  "grant_type": "refresh-token",
  "iss": "HLYM LMS",
  "userType": "member",
  "exp": 1934969029,
  "iat": 1619609029,
  "jti": "5a63f22f-2e42-4d7f-823e-fae08d11b5cb"
}

The endpoint responds with an access token and a refresh token.

Parameter Mandatory? Type Description
accessToken Yes String A JWT token with the sub and iat fields. The sub (subject) field has the UUID of the user. The exp (expiration time) is in the Unix time format, with the number of seconds since the Unix epoch.
refreshToken Yes String The password, hashed with the SHA-512 variant of the SHA-2 algorithm.
tokenType Yes String Always has the value "Bearer".

Sign-out

POST /members/sign-out

Send OTP For Forgot Password

GET /members/otp/send

Sample Input Parameters

{
   "emailOrMobile" : "+918139921556",
   "verificationType" : "mobileNumber",
   "bypassCode": "123456"
}

Sample Output Parameters

{
  "message": "OTP sent successfully."
}

Verify OTP for forgot password

POST /members/otp/verify

Sample Input Parameters

{
 "otp": "123456",
 "emailOrMobile": "+919891234567",
 "verificationType": "mobileNumber",
 "bypassCode": "123456"
}

Sample Output Parameters

{
  "message": "OTP verified successfully."
}

Forgot Password

POST /members/password/forgot

Sample Input Parameters 

{
    "mobile": {
        "mobileNumber": "8139921557",
        "countryCode": "+91"
    },
    "newPassword": "43f997e9b08a715ddedf1ac8c8d7fa388d45fca154359b4e553a62b92c5a7fdec4decf7e886da4b418345541ee53564bb1c32a750da65332fd8f896852149379"
}

Sample Output Parameters 

{
    "message": "Password reset successfully"
}
Parameter Mandatory? Type Description
otp Yes String otp from the Send OTP for forgot Password API.

Reset Password

POST /members/password/change

Sample Input Parameters 

{
    "mobile": {
        "mobileNumber": "8139921557",
        "countryCode": "+91"
    },
    "oldPassword": "43f997e9b08a715ddedf1ac8c8d7fa388d45fca154359b4e553a62b92c5a7fdec4decf7e886da4b418345541ee53564bb1c32a750da65332fd8f896852149379",
    "newPassword": "0b0c4c14eea4a0eb492171d592c21c50053c05aa15dcf31320c7400920521f601d721d8a1e5baee7cd8c08ad776fdb6e01d0044c31f72e25b99441603e53e3bb"
}

Sample Output Parameters 

{
    "message": "Password changed successfully!"
}

Update member (Setup profile)

PUT /members/{memberId}/profile

Sample Input Parameters

{
    "name": "Githika Ramesh",
    "gender": "female",
    "dateOfBirth": "1972-07-25",
    "email": "githika.ramesh@hummingwave.com",
    "currentTier": "member",
    "profileImageName": "sample1",
    "mobile": {
      "countryCode": "+60",
      "mobileNumber": "0390764779"
    },
    "addresses": [{
      "addressLine1": "125 Jln Cheras Batu 11 Kampung Baru China",
      "addressLine2": "43200 Cheras 43200 Malaysia Cheras 43200 Malaysia",
      "postCode": "43200",
      "city": "Cheras",
      "state": "Selangor",
      "addressType": "Home",
      "defaultStatus": "defaultAddress"
    }]
}

Parameters

Parameter Type Required Description
mobileVerifiedStatus String Required Possible values are verified, notVerified
emailVerifiedStatus String Required Possible values are verified, notVerified
currentTier String Required Possible values are member, fan
defaultStatus String Required Posiible values are defaultAddress, otherAddress.

Add Member Card Details

POST /members/{memberId}/cards

Sample Input Parameters

{
"cardNumber":"123456789011"
}

Sample Input Parameters to generate virtual card

{

}

Sample Output Parameters

{
    "id": "e7e3b4d6-8ee8-4b15-b57c-4f2a43190553",
    "username": "githika",
    "name": "Githika Ramesh",
    "tier": "member",
    "mobileVerifiedStatus": "verified",
    "emailVerifiedStatus": "notVerified",
    "cards": [
        {
            "id": "573db3d9-2efd-4b56-acad-07706682129e",
            "cardNumber": "123456789011",
            "issuedOn": "2021-04-27",
            "cardType": "physical"
        },
        {
            "id": "4071e25d-0f29-44de-84b7-fd5488d0e498",
            "cardNumber": "123456789012",
            "issuedOn": "2021-04-28",
            "cardType": "physical"
        }
    ],
    "addresses": [{
      "addressLine1": "125 Jln Cheras Batu 11 Kampung Baru China",
      "addressLine2": "43200 Cheras 43200 Malaysia Cheras 43200 Malaysia",
      "postCode": "43200",
      "city": "Cheras",
      "state": "Selangor",
      "addressType": "Home",
      "defaultStatus": "defaultAddress"
    }],
    "gender": "female",
    "email": "githika.ramesh@hummingwave.com",
    "dateOfBirth": "1972-07-25",
    "bikes": [
        {
            "id": "80936b4b-5058-400f-925a-51d222f7ded2",
            "plateNumber": "PFQ 5217",
            "icNumber": "691206-10-5330",
            "vocVerificationMode": "manual"
        }
    ]
}

Sample Error Response

{
    "message": "Member already has this card"
}

Parameters

Parameter Type Required Description
mobileVerifiedStatus String Required Possible values are verified, notVerified
cardType String Required Possible values are physical, virtual. If the user doesn't have a physical card or if the user is a fan we generate a virtual card for the user.

Send OTP for mobile verification

GET /otp

Sample Input Parameters

{
   "emailOrMobile" : "+918139921556",
   "verificationType" : "mobileNumber",
   "bypassCode": "123456"
}

Sample Output Parameters

{
  "message": "OTP sent successfully."
}

Parameters

Parameter Type Required Description
bypassCode String Optional This is a field to be passed in the dev environment to avoid sending the OTPs. You can pass the value as "123456" as this is the OTP used in the dev environment.

Verify OTP

POST members/{memberId}/verify-otp

Sample Input Parameters

{
 "otp": "123456",
 "emailOrMobile": "+919891234567",
 "verificationType": "mobileNumber",
 "bypassCode": "123456"
}

Sample Output Parameters

{
    "id": "e7e3b4d6-8ee8-4b15-b57c-4f2a43190553",
    "username": "githika",
    "name": "Githika Ramesh",
    "tier": "member",
    "mobileVerifiedStatus": "verified",
    "emailVerifiedStatus": "notVerified",
    "cards": [
        {
            "id": "573db3d9-2efd-4b56-acad-07706682129e",
            "cardNumber": "123456789011",
            "issuedOn": "2021-04-27"
        },
        {
            "id": "4071e25d-0f29-44de-84b7-fd5488d0e498",
            "cardNumber": "123456789012",
            "issuedOn": "2021-04-28"
        }
    ],
    "addresses": [{
      "addressLine1": "125 Jln Cheras Batu 11 Kampung Baru China",
      "addressLine2": "43200 Cheras 43200 Malaysia Cheras 43200 Malaysia",
      "postCode": "43200",
      "city": "Cheras",
      "state": "Selangor",
      "addressType": "Home",
      "defaultStatus": "defaultAddress"
    }],
    "gender": "female",
    "email": "githika.ramesh@hummingwave.com",
    "dateOfBirth": "1972-07-25",
    "bikes": [
        {
            "id": "80936b4b-5058-400f-925a-51d222f7ded2",
            "plateNumber": "PFQ 5217",
            "icNumber": "691206-10-5330",
            "vocVerificationMode": "manual"
        }
    ]
}

Sample Input Parameters

{
   "emailOrMobile" : "john.smith@gmail.com",
   "verificationType" : "emailAddress",
   "bypassCode": "123456"
}

Sample Output Parameters

{
  "message": "OTP sent successfully."
}

Get states and cities grouped by post code.

GET /city-state?

Sample Input Parameters

{
 "postCode": "79000"
}

Sample Output Parameters

{
    "postCode": "79000",
    "city": "Nusajaya",
    "state": "Johor"
}

Get presigned URL for profile image upload.

GET /presigned-url/profile-image

Sample Input Parameters 

{
 "fileName": "edc3fd41-6770-4210-bf0a-e608b93d2e64-profile-image.jpg"
}

Sample Output Parameters

{
  "presignedUrl": "https://s3.ap-southeast-2.amazonaws.com/s3sign2-bucket-hchq3nwuo8ns/s3-sign-demo.json?X-Amz-Security-Token=FQ…&X-Amz-Credential=ASIAJF3BXG…&X-Amz-Date=20170125T044127Z&X-Amz-Expires=60&X-Amz-Signature=24db05…"
}

Get Notifications

GET /members/{memberId}/notifications

Sample Output Parameters

{
    "notifications": [
        {
            "notificationToUserId": "00fe7ef0-b65b-44f5-b8dd-c2b10ca68cab",
            "userId": "e7e3b4d6-8ee8-4b15-b57c-4f2a43190553",
            "title": "Genblu campaign",
            "imageUrl": "https://pearl-academy.s1.umbraco.io/media/hujc254f/event-3.jpeg?width=500&mode=max&animationprocessmode=first",
            "type": "campaigns",
            "sentAtTime": "2021-04-28T06:20:48.345Z",
            "readStatus": "notRead",
            "detail": "Earn point by shopping on our Genblu website!"
        }
    ]
}

Bike Details

Get Bike Model Names

GET /bike/models

Sample Output Parameters

{
    "bikeModels": [
        {
            "id": "59c354df-b150-4614-bbe9-99c603d0304f",
            "bikeModelName": "NOUVO CW"
        },
        {
            "id": "3236c5bb-ede9-488b-bdb4-787470d827fb",
            "bikeModelName": "YAMAHA EGO S"
        }
    ]
}

Get All Bike Details

Sample Input Parameters

GET /bike

Sample Output Parameters

{
"bikeDetails": [
    {
        "id": "8771f928-e5fb-48ee-b060-a3ecb9cf0cb0",
        "customerId": "0b44842a-dade-4d40-9ea3-d261f1199ebc",
        "modelNo": "135LC SE",
        "plateNo": "VGC2931",
        "icNumber": "991111123456",
        "status": "approved",
        "engineNumber": "52WVC10338",
        "chassisNumber": "MR053HY93050009999",
        "registrationDate": "2021-01-29T09:58:44.635Z"
    }
]
}

Parameters

Parameter Type Required Description
icNumber String Required The current format of the Malaysian identity card number is YYMMDD-PB-###G
status String Required Possible values are approved, rejected, pending.

Add Vehicle JPJ Info

POST /bike/add-vehicle-jpj-info

Sample Input Parameters

 {
"icNumber":"691206-10-5330",
"plateNumber":"PFQ 5217"
}

Sample Output Parameters if vocVerificationMode is manual

{
    "id": "2eb00c25-bbde-461a-9323-e6091e791643",
    "plateNumber": "PFQ 5217",
    "icNumber": "691206-10-5330",
    "vocVerificationMode": "manual",
    "status": "pending"
}

Sample Output Parameters if vocVerificationMode is jpj

{
    "id": "991bb482-dfe2-4c28-a572-55682f276792",
    "plateNumber": "PFQ 5218",
    "icNumber": "691206-10-5331",
    "engineNumber": "521231033890",
    "chassisNumber": "MR053HY9305000999",
    "vocVerificationMode": "jpj",
    "status": "verified"
}

Sample Error Response 

{
 "message" : "Invalid icNumber"
}

Parameters

Parameter Type Required Description
plateNo String Required The bike's plate number.
icNumber String Required Owner's NRIC number.
engineNo String Optional The bike's engine number.
chassisNo String Optional The bike's chassis number.
modelNo String Optional The bike's model number.
status String Required Possible values are verified, rejected, pending
vocVerificationMode String Required Possible values are preApproved, manual, jpj, preOwned.

Get VOC Approval List for Ops User

GET /bike/voc-approval

Sample Output Parameters

{

}

Update Vehicle Engine Info Details

PUT /bike/{bikeId}/add-vehicle-jpj-info

Sample Input Parameters to update only icNumber and plateNumber

{
"plateNumber": "1234567",
"icNumber": "691206-10-5331"
}

Sample Input Parameters to update other details

{
"engineNumber": "523451033889",
"modelName": "135LC SE",
"chassisNumber": "MR053HY9305000999",
"plateNumber": "1234567",
"icNumber": "691206-10-5331",
"vocCopyfileNames": ["sample1"]
}

Sample Output Parameters 

{
    "id": "56277c73-407c-45a8-8ead-dfcbac25dcfa",
    "plateNumber": "1234567",
    "icNumber": "691206-10-5331",
    "engineNumber": "523451033889",
    "chassisNumber": "MR053HY9305000999",
    "modelNumber": "135LC SE",
    "vocVerificationMode": "manual",
    "status": "pending",
    "vocCopyFileNames": ["sample1"]
}

Parameters

Parameter Type Required Description
id String Required The bike's id. Update bike details should be allowed only if the vocVerificationMode is manual.
engineNumber String Optional The bike's engine number. Must be 12 digits.
modelName String Optional The bike's model name.
chassisNumber String Optional The bike's chassis number. Alphanumeric with a length of 17.
plateNumber String Required The bike's plateNumber. Must have a length between 6 and 8 characters.
icNumber String Required The bike's icNumber. Length is 12 digits.

Get presigned URL for VOC image upload.

GET /bike/add-vehicle-jpj-info/pre-signed-url

Sample Input Parameters 

{
 "fileName": "edc3fd41-6770-4210-bf0a-e608b93d2e64-profile-image.jpg"
}

Sample Output Parameters

{
  "presignedUrl": "https://s3.ap-southeast-2.amazonaws.com/s3sign2-bucket-hchq3nwuo8ns/s3-sign-demo.json?X-Amz-Security-Token=FQ…&X-Amz-Credential=ASIAJF3BXG…&X-Amz-Date=20170125T044127Z&X-Amz-Expires=60&X-Amz-Signature=24db05…"
}

Home

GET member/home-details

Sample Input Parameters

{
  "advertisementsAndEvents": [
    {
      "imageUrl": "https://www.yamaha-motor/test-drive.jpg",
      "type": "event",
      "date": "2021-01-29T09:58:44.635Z",
      "title": "All New",
      "subTitle": "MT25",
      "details": "DJ Lorem Ipsum",
      "linkText": "Test Drive",
      "linkUrl": "https://www.yamaha-motor/test-drive"
    }
  ],
  "totalRewardPoints": 1300
}

Parameters

Parameter Type Required Description
type String Required Possible values are event and advertisement.

Transactions

Transaction List for Member

GET /members/{member-id}/transactions

Request

Path Parameter

This request requires member-id as a path parameter.

Query String Parameters

This request for now takes a transactionType which must be awarded for this case.

Response

Response would be containing the list of transactions associated with this memberId, the following JSON structure depicts the same.

Sample Output Parameters

{
    "transactionList": [
        {
            "id": "38322361-cba2-457a-a886-39355ed58c97",
            "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
            "transactionTime": "2021-05-03T11:26:25.474536",
            "description": "Points accrued for checkIn to campaign11caf9b1-d3d7-443f-8af2-3b0c2d966be6",
            "pointsRewarded": 50,
            "action": "checkIn",
            "merchantId": "38040d80-b66e-4fba-b2f2-08ff7530f506",
            "associatedCampaignId": "11caf9b1-d3d7-443f-8af2-3b0c2d966be6"
        },
        {
            "id": "39e77a1f-a8d2-4e8a-8f21-e4874ab02d1c",
            "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
            "transactionTime": "2021-05-05T08:26:53.087944",
            "description": "New Year reprised with yamaha",
            "purchaseAmount": 0.0,
            "spentAmount": 0.0,
            "pointsRewarded": 1000,
            "action": "opsAward"
        },
        {
            "id": "4358d037-e0ae-414f-adf0-530ae398d36c",
            "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
            "transactionTime": "2021-05-05T08:29:18.738945",
            "description": "New Year reprised with yamaha",
            "purchaseAmount": 0.0,
            "spentAmount": 0.0,
            "pointsRewarded": 1000,
            "action": "opsAward"
        },
        {
            "id": "94abc503-f7a7-4fc0-9d5c-f58dba3fe5fe",
            "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
            "transactionTime": "2021-05-05T08:28:07.863229",
            "description": "New Year reprised with yamaha",
            "purchaseAmount": 0.0,
            "spentAmount": 0.0,
            "pointsRewarded": 1000,
            "action": "opsAward"
        },
        {
            "id": "d02ebcf9-250b-4141-8130-8aa15c12260c",
            "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
            "transactionTime": "2021-05-03T11:43:46.851115",
            "description": "Points accrued for checkIn to campaign11caf9b1-d3d7-443f-8af2-3b0c2d966be6",
            "purchaseAmount": 0.0,
            "spentAmount": 0.0,
            "pointsRewarded": 50,
            "action": "checkIn",
            "associatedCampaignId": "11caf9b1-d3d7-443f-8af2-3b0c2d966be6"
        },
        {
            "id": "f40f3cc0-fd44-4faf-9575-4abea33dbea9",
            "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
            "transactionTime": "2021-05-03T11:27:24.074406",
            "description": "Points accrued for checkIn to campaign11caf9b1-d3d7-443f-8af2-3b0c2d966be6",
            "pointsRewarded": 50,
            "action": "checkIn",
            "associatedCampaignId": "11caf9b1-d3d7-443f-8af2-3b0c2d966be6"
        }
    ],
    "countTransactions": 6
}

Specific Transaction for Member

GET /members/{member-id}/transactions/{transaction-id}

Request

This request requires member-id, transaction-id as a path parameter.

Response

Response would contain a specific transaction detail for the merchant.

Sample Output for transaction detail 

{
    "id": "8df96ff2-7f34-4f68-87c2-89ac806e1c8f",
    "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
    "transactionTime": {
        "date": "2021-05-06",
        "time": "09:19:07.389915"
    },
    "description": "Points accrued for checkIn to campaign11caf9b1-d3d7-443f-8af2-3b0c2d966be6",
    "purchaseAmount": 0.0,
    "spentAmount": 0.0,
    "pointsRewarded": 50,
    "action": "checkIn",
    "merchantPoints": [
        {
            "pointId": "62281a60-8fe1-4b7d-b4dd-5d8d3d4cadf7",
            "isCreated": false,
            "amount": 50
        }
    ],
    "memberPoints": [
        {
            "pointId": "b1da5bca-25a8-404b-9cde-5fb5403fabb2",
            "isCreated": true,
            "pointsProvider": "yamaha",
            "amount": 50
        }
    ],
    "merchantId": "38040d80-b66e-4fba-b2f2-08ff7530f506",
    "associatedCampaignId": "11caf9b1-d3d7-443f-8af2-3b0c2d966be6",
    "createTime": "May 6, 2021, 9:19:07 AM",
    "updateTime": "May 6, 2021, 9:19:07 AM"
}

Merchants

Merchant Sign-in

POST /merchants/sign-in

A merchant signs in with an email address.

Endpoint Authentication

This endpoint uses a different REST API authorisation mechanism, as the user is unauthenticated. The API Key mechanism is used, with:

key: "x-api-key"

value: <API key>

Request

Sample request

{
    "credentialType": "emailAddress",
    "credentials": {
    "emailAddress": "githika.ramesh@hummingwave.com",
    "hashedPassword": "0b0c4c14eea4a0eb492171d592c21c50053c05aa15dcf31320c7400920521f601d721d8a1e5baee7cd8c08ad776fdb6e01d0044c31f72e25b99441603e53e3bb"
    }
}

A merchant can sign in using their email address and password.

Parameter Required? Type Description
emailAddress Yes String The email address of the member, preferably trimmed and in all lowercase.
hashedPassword Yes String The password, hashed with the SHA-512 variant of the SHA-2 algorithm.

Response

Sample response

{
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiZmVkNTcxYy01YTIxLTQ3OWQtODIyZC05ZDliNTMzNTg2NGIiLCJncmFudF90eXBlIjoiYXV0aG9yaXphdGlvbi10b2tlbiIsImlzcyI6IllhbWFoYSBMTVMiLCJleHAiOjE2MTg2NjQ0NzMsImlhdCI6MTYxODY2MDg3MywianRpIjoiOWRjM2JjNzctOGI3NS00M2IxLTk1YTctYzRmYTkzYWRmYzQ1In0.QFAlfpnjWEMhoK0802FlFPdWcdxpCKi2v4pF1SQLofI",
    "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiZmVkNTcxYy01YTIxLTQ3OWQtODIyZC05ZDliNTMzNTg2NGIiLCJncmFudF90eXBlIjoicmVmcmVzaC10b2tlbiIsImlzcyI6IllhbWFoYSBMTVMiLCJleHAiOjE5MzQwMjA4NzMsImlhdCI6MTYxODY2MDg3MywianRpIjoiODM2Yjc3YWEtNDMyOS00NDM1LTgzNmMtMWEwZTAyODgxZTI0In0.Ux_3T-Ql7qpSWlN575HhWZ5H_qCzkOiR_06YWtGn0WA",
    "tokenType": "Bearer"
}

Sample decoded JWT access token

{
  "sub": "bfed571c-5a21-479d-822d-9d9b5335864b",
  "grant_type": "authorization-token",
  "iss": "HLYM LMS",
  "userType": "merchant",
  "exp": 1618671911,
  "iat": 1618668311,
  "jti": "5b792ce9-9598-4d93-8e00-f6eb2e59c662"
}

Sample decoded JWT refresh token

{
  "sub": "bfed571c-5a21-479d-822d-9d9b5335864b",
  "grant_type": "refresh-token",
  "iss": "HLYM LMS",
  "userType": "merchant",
  "exp": 1934028311,
  "iat": 1618668311,
  "jti": "55ca5135-70ff-43c0-b16c-5de03a4afc7e"
}

The endpoint responds with an access token and a refresh token.

Parameter Mandatory? Type Description
accessToken Yes String A JWT token with the sub and iat fields. The sub (subject) field has the UUID of the user. The exp (expiration time) is in the Unix time format, with the number of seconds since the Unix epoch.
refreshToken Yes String The password, hashed with the SHA-512 variant of the SHA-2 algorithm.
tokenType Yes String Always has the value "Bearer".

Forgot Password

POST merchants/password/forgot

Sample Input Parameters 

{
    "emailAddress": "githika.ramesh@hummingwave.com",
    "newPassword": "43f997e9b08a715ddedf1ac8c8d7fa388d45fca154359b4e553a62b92c5a7fdec4decf7e886da4b418345541ee53564bb1c32a750da65332fd8f896852149379"
}

Sample Output Parameters 

{
    "message": "Password reset successfully"
}
Parameter Mandatory? Type Description
otp Yes String otp from the Send OTP API.

Reset Password

POST members/password/change

Sample Input Parameters 

{
    "emailAddress": "githika.ramesh@hummingwave.com",
    "oldPassword": "43f997e9b08a715ddedf1ac8c8d7fa388d45fca154359b4e553a62b92c5a7fdec4decf7e886da4b418345541ee53564bb1c32a750da65332fd8f896852149379",
    "newPassword": "0b0c4c14eea4a0eb492171d592c21c50053c05aa15dcf31320c7400920521f601d721d8a1e5baee7cd8c08ad776fdb6e01d0044c31f72e25b99441603e53e3bb"
}

Sample Input Parameters for first time user

{
    "emailAddress": "githika.ramesh@hummingwave.com",
    "newPassword": "0b0c4c14eea4a0eb492171d592c21c50053c05aa15dcf31320c7400920521f601d721d8a1e5baee7cd8c08ad776fdb6e01d0044c31f72e25b99441603e53e3bb"
}

Sample Output Parameters 

{
    "message": "Password changed successfully"
}

Send OTP for mobile verification

GET /merchants/otp/send

Sample Input Parameters

{
   "emailOrMobile" : "githika.ramesh@hummingwave.com",
   "verificationType" : "emailAddress"
}

Sample Output Parameters

{
  "message": "OTP sent successfully."
}

Verify OTP

POST merchants/otp/verify

Sample Input Parameters

{
 "otp": "123456",
 "emailOrMobile": "githika.ramesh@hummingwave.com",
 "verificationType": "emailAddress"
}

API Reference

Ops Authentication

Ops Sign-in

POST /auth/sign-in

Request

Sample request

{
    "emailAddress": "amit.singh@hummingwave.com",
    "hashedPassword": "43f997e9b08a715ddedf1ac8c8d7fa388d45fca154359b4e553a62b92c5a7fdec4decf7e886da4b418345541ee53564bb1c32a750da65332fd8f896852149379"
}

An Ops user can sign in using their email address and password.

Parameter Required? Type Description
emailAddress Yes String The email address of the Ops person, preferably trimmed and in all lowercase.
hashedPassword Yes String The password, hashed with the SHA-512 variant of the SHA-2 algorithm.

Response

Sample response

{
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhMmJhNWM2ZS01NDY3LTRlODgtODk4MC02YzNkNDhjYTQ1ZDYiLCJncmFudF90eXBlIjoiYXV0aG9yaXphdGlvbi10b2tlbiIsImlzcyI6IllhbWFoYSBMTVMiLCJleHAiOjE2MTYxNDE4NTYsImlhdCI6MTYxNjEzODI1NiwianRpIjoiMDU4MDMyY2YtOWYxNS00ODU0LWI4NDItNmYyZGY3MTAwMzYzIn0.wArbHnGQlJ-burSKzjGcap5S1Hq3mTMs9FzozivjCbs",
    "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhMmJhNWM2ZS01NDY3LTRlODgtODk4MC02YzNkNDhjYTQ1ZDYiLCJncmFudF90eXBlIjoicmVmcmVzaC10b2tlbiIsImlzcyI6IllhbWFoYSBMTVMiLCJleHAiOjE5MzE0OTgyNTYsImlhdCI6MTYxNjEzODI1NiwianRpIjoiOGRkOTJiNzUtODQxMS00NDk5LWI4ZjMtZmY2MzY1N2FlN2NkIn0.p-zy7rGTjQbEb8EUfkh-8U1s3sGPCpixNqEbVKNecqc",
    "tokenType": "Bearer"
}

Sample decoded JWT access token

{
  "sub": "a2ba5c6e-5467-4e88-8980-6c3d48ca45d6",
  "grant_type": "authorization-token",
  "iss": "Yamaha LMS",
  "exp": 1616141856,
  "iat": 1616138256,
  "jti": "058032cf-9f15-4854-b842-6f2df7100363"
}

Sample decoded JWT refresh token

{
  "sub": "a2ba5c6e-5467-4e88-8980-6c3d48ca45d6",
  "grant_type": "refresh-token",
  "iss": "Yamaha LMS",
  "exp": 1931498256,
  "iat": 1616138256,
  "jti": "8dd92b75-8411-4499-b8f3-ff63657ae7cd"
}

The endpoint responds with an access token and a refresh token.

Parameter Mandatory? Type Description
accessToken Yes String A JWT token with the sub and iat fields. The sub (subject) field has the UUID of the user. The exp (expiration time) is in the Unix time format, with the number of seconds since the Unix epoch.
refreshToken Yes String The password, hashed with the SHA-512 variant of the SHA-2 algorithm.
tokenType Yes String Always has the value "Bearer".

Errors

The endpoint throws these specific errors in addition to the generic ones.

Error code Description
401 The password is incorrect.
423 The account is temporarily locked. This is most likely due to too many failed attempts.

Refresh Token

Sample request

{
    "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhMmJhNWM2ZS01NDY3LTRlODgtODk4MC02YzNkNDhjYTQ1ZDYiLCJncmFudF90eXBlIjoicmVmcmVzaC10b2tlbiIsImlzcyI6IllhbWFoYSBMTVMiLCJleHAiOjE5MzE0OTgyNTYsImlhdCI6MTYxNjEzODI1NiwianRpIjoiOGRkOTJiNzUtODQxMS00NDk5LWI4ZjMtZmY2MzY1N2FlN2NkIn0.p-zy7rGTjQbEb8EUfkh-8U1s3sGPCpixNqEbVKNecqc"
}

Sample response

{
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhMmJhNWM2ZS01NDY3LTRlODgtODk4MC02YzNkNDhjYTQ1ZDYiLCJncmFudF90eXBlIjoiYXV0aG9yaXphdGlvbi10b2tlbiIsImlzcyI6IllhbWFoYSBMTVMiLCJleHAiOjE2MTYxNTE2NzUsImlhdCI6MTYxNjE0ODA3NSwianRpIjoiYTc1OGJjNmItMjIyYS00ZThmLTgyYWUtYWY2YmNiOTBmNDkzIn0.e7Ic-UWVnZJRVJwlKiJNpzCWlinMtMr1U6xAHcByMFk",
    "tokenType": "Bearer"
}

POST /auth/refresh-token

Campaigns

Create Campaigns

POST /campaigns

Request

This API endpoint is intended for resource Campaigns, this method would be creating a new campaign based on the values provided in the body of requests. The paramaters provided for creating the request must be in consisitent with the requirements for creating the campaigns failing which errors like 404 or 500 group would be sent viz. response.

Body Parameters

Parameter Required? Type Description
title Yes String The campaign title would be displayed on the banners and at various places within the different applications.
content Yes String This is kind of description about the campaign, this would be shown when any application requests for detailed description of campaign.
status Yes String Status defines the present state of the campaign that has been created, it can take different types of values. If values are provided out of these bounds suitable error would be thrown. Possible values belong to set {draft, enabled, disabled, deleted}
startDate Yes Date Start Date
endDate Yes Date End Date
type Yes String Type expects string values which must be from set { advertisement, genbluStore, event, merchantEvent }, this is required that type must belong to provided set. Failing which, suitable error will be provided in response like 500 or 400. It is important to note that the value for type would determine what type of configuration would be supported for a campaign.
bannerImageUrl Yes String Banner Image URL refers to the URL of the image that would be rendered on the application campaign screeens. It is important to note that this URL for the resource is generated when image is uploaded to the servers. An invalid image URL would fail to render on the applications, please provide the valid URLs for the same.
contentImageUrls Yes [String] Content Image URLs refer to the actual images that would be shown to the users on the applications like Android and IOS, it is important to note that it expects a list of values for the URLs of the different images that would be required for our campaigns to be rendered.
userSegment Yes Object User Segment Model
adConfig Yes Object adConfig would be of type AdConfig
genbluEcommerceConfig Yes Object GenBlu Configuration Object, defining configuration of genblu event only.
campaignEventConfig Yes Object Event Configuration Object, defining configuration of event only.
campaignMerchantEventConfig Yes Object Merchant Event Configuration Object, defining configuration of event only.
campaignSchedule Yes Object campaignSchedule is required for events of all types, it defines the schedule through which users would be shown advertisements of campaign.
campaignNotificationConfig Yes Object campaignNotificationConfig is required for events of all types, it defines the schedule through which users would be notified for campaign.

Sample Create Request Advertisement Event

{
  "title" : "New Week Event", 
  "content" : "This new year celebrate with us.",
  "status" : "enabled", 
  "startDate" : "2021-04-10",
  "endDate" : "2021-04-23",
  "type" : "advertisement", 
  "bannerImageUrl" : "https://5.imimg.com/data5/RC/KK/MY-989864/yamaha-bike-500x500.png", 
  "contentImageUrls" : ["https://i.pinimg.com/originals/d3/b6/48/d3b6488dd189048d58d82a4aee68dcef.jpg", 
  "https://cdn.statically.io/img/wallpaperplay.com/walls/full/6/6/c/8130.jpg", 
  "https://images.unsplash.com/photo-1506765515384-028b60a970df?ixid=MnwxMjA3fDB8MHxzZWFyY2h8Mnx8YmFubmVyfGVufDB8fDB8fA%3D%3D&ixlib=rb-1.2.1&w=1000&q=80", 
  "https://st.depositphotos.com/1157537/2479/v/600/depositphotos_24798755-stock-illustration-red-ribbon-set.jpg"], 
  "adConfig" : {
    "linkName" : "Yamaha Bikes this year", 
    "linkUrl" : "https://www.youtube.com/watch?v=84Af6_2lIuY"
  }, 
  "campaignSchedule" : {
    "startDate" : "2021-04-10",
    "endDate" : "2021-04-23", 
    "timeOfDayStart" : "16:46", 
    "timeOfDayEnd" : "20:46", 
    "specificDaysOfWeek" : "allDays"
  }, 
  "campaignNotificationStatus" :{
    "smsNotificationStatus" : "true", 
    "campaignNotificationSmsConfig" : { 
      "message" : "Campaign for you this new year, we regret the latency due to COVID situation. We're back again."
    }
  }
}

Sample Create Request GenBlu E-Commerce Event

{
  "title" : "Store Upgradation Event in Bengaluru, Karnataka, India", 
  "content" : "Local Merchant Events, arrive and participate and win to our brand new yamaha franchisee.",
  "status" : "enabled", 
  "startDate" : "2021-05-15",
  "endDate" : "2021-05-30",
  "type" : "genbluStore", 
  "bannerImageUrl" : "https://5.imimg.com/data5/RC/KK/MY-989864/yamaha-bike-500x500.png", 
  "contentImageUrls" : ["https://i.pinimg.com/originals/d3/b6/48/d3b6488dd189048d58d82a4aee68dcef.jpg", 
  "https://cdn.statically.io/img/wallpaperplay.com/walls/full/6/6/c/8130.jpg", 
  "https://images.unsplash.com/photo-1506765515384-028b60a970df?ixid=MnwxMjA3fDB8MHxzZWFyY2h8Mnx8YmFubmVyfGVufDB8fDB8fA%3D%3D&ixlib=rb-1.2.1&w=1000&q=80", 
  "https://st.depositphotos.com/1157537/2479/v/600/depositphotos_24798755-stock-illustration-red-ribbon-set.jpg"], 
  "campaignSchedule" : {
    "startDate" : "2021-05-11",
    "endDate" : "2021-05-25", 
    "timeOfDayStart" : "16:46", 
    "timeOfDayEnd" : "20:46", 
    "specificDaysOfWeek" : "allDays"
  }, 
  "campaignNotificationStatus" :{
    "scheduledTime" : "2021-05-11T11:25:19",
    "smsNotificationStatus" : "true", 
    "campaignNotificationSmsConfig" : { 
      "message" : "This is upgradation event for our previous store in your city on exclusive demands."
    }
  }, 
  "genbluEcommerceConfig" : {
    "linkName" : "Local Bike Fair and Store Launch", 
    "linkUrl" : "https://www.justdial.com/Bangalore/Whitefield-Yamaha-Forum-Mall-Whitefield/080PXX80-XX80-170511152022-C5Z1_BZDET", 
    "eventStartTime" : "2021-05-15T11:30:19", 
    "eventEndTime" : "2021-05-30T11:30:19", 
    "pointsTiers" : [
      { 
        "lowerLimit" : 0,  
        "upperLimit" : 100, 
        "pointsMultiplierFromMerchant" : 2
      }, 
      { 
        "lowerLimit" : 101,  
        "upperLimit" : 800, 
        "pointsMultiplierFromMerchant" : 3
      }
    ], 
    "pointsCeilingPerTransaction" : 1000,
    "pointsCeilingPerUser" : 500, 
    "transactionCountCeilingPerUser" : 3, 
    "pointsCeilingForCampaign" : 100000, 
  }
}

Sample Create Request A&P Event

{
  "title" : "Store Upgradation Event in Bengaluru, Karnataka, India", 
  "content" : "Local Merchant Events, arrive and participate and win to our brand new yamaha franchisee.",
  "status" : "enabled", 
  "startDate" : "2021-05-15",
  "endDate" : "2021-05-30",
  "type" : "event", 
  "bannerImageUrl" : "https://5.imimg.com/data5/RC/KK/MY-989864/yamaha-bike-500x500.png", 
  "contentImageUrls" : ["https://i.pinimg.com/originals/d3/b6/48/d3b6488dd189048d58d82a4aee68dcef.jpg", 
  "https://cdn.statically.io/img/wallpaperplay.com/walls/full/6/6/c/8130.jpg", 
  "https://images.unsplash.com/photo-1506765515384-028b60a970df?ixid=MnwxMjA3fDB8MHxzZWFyY2h8Mnx8YmFubmVyfGVufDB8fDB8fA%3D%3D&ixlib=rb-1.2.1&w=1000&q=80", 
  "https://st.depositphotos.com/1157537/2479/v/600/depositphotos_24798755-stock-illustration-red-ribbon-set.jpg"], 
  "campaignSchedule" : {
    "startDate" : "2021-05-11",
    "endDate" : "2021-05-25", 
    "timeOfDayStart" : "16:46", 
    "timeOfDayEnd" : "20:46", 
    "specificDaysOfWeek" : "allDays"
  }, 
  "campaignNotificationStatus" :{
    "scheduledTime" : "2021-05-11T11:25:19",
    "smsNotificationStatus" : "true", 
    "campaignNotificationSmsConfig" : { 
      "message" : "This is upgradation event for our previous store in your city on exclusive demands."
    }
  }, 
  "campaignEventConfig" : {
    "merchantId" : "38040d80-b66e-4fba-b2f2-08ff7530f506",
    "linkName" : "Local Bike Fair and Store Launch", 
    "linkUrl" : "https://www.justdial.com/Bangalore/Whitefield-Yamaha-Forum-Mall-Whitefield/080PXX80-XX80-170511152022-C5Z1_BZDET", 
    "qrCodeScanPermission" : "member",
    "eventStartTime" : "2021-05-15T11:30:19", 
    "eventEndTime" : "2021-05-30T11:30:19", 
    "pointsTiers" : [
      { 
        "lowerLimit" : 0,  
        "upperLimit" : 100, 
        "pointsMultiplierFromMerchant" : 2
      }, 
      { 
        "lowerLimit" : 101,  
        "upperLimit" : 800, 
        "pointsMultiplierFromMerchant" : 3
      }
    ], 
    "pointsAccruedPerCheckIn" : 50,
    "pointsCeilingForCheckIn" : 1500,
    "pointsCeilingPerUserForCheckIn": 100,
    "checkInFrequency" : "daily",
    "pointsCeilingPerTransaction" : 1000,
    "pointsCeilingPerUser" : 500, 
    "transactionCountCeilingPerUser" : 3, 
    "pointsCeilingForCampaign" : 100000, 
    "address" : "No. 2, Whitefield Main Rd, Brooke Bond First Cross, Whitefield, Bengaluru, Karnataka 560066"
  }
}

Sample Create Request Merchant Event

{
  "title" : "Store Upgradation Event in Bengaluru, Karnataka, India", 
  "content" : "Local Merchant Events, arrive and participate and win to our brand new yamaha franchisee.",
  "status" : "enabled", 
  "startDate" : "2021-05-15",
  "endDate" : "2021-05-30",
  "type" : "merchantEvent", 
  "bannerImageUrl" : "https://5.imimg.com/data5/RC/KK/MY-989864/yamaha-bike-500x500.png", 
  "contentImageUrls" : ["https://i.pinimg.com/originals/d3/b6/48/d3b6488dd189048d58d82a4aee68dcef.jpg", 
  "https://cdn.statically.io/img/wallpaperplay.com/walls/full/6/6/c/8130.jpg", 
  "https://images.unsplash.com/photo-1506765515384-028b60a970df?ixid=MnwxMjA3fDB8MHxzZWFyY2h8Mnx8YmFubmVyfGVufDB8fDB8fA%3D%3D&ixlib=rb-1.2.1&w=1000&q=80", 
  "https://st.depositphotos.com/1157537/2479/v/600/depositphotos_24798755-stock-illustration-red-ribbon-set.jpg"], 
  "campaignSchedule" : {
    "startDate" : "2021-05-11",
    "endDate" : "2021-05-25", 
    "timeOfDayStart" : "16:46", 
    "timeOfDayEnd" : "20:46", 
    "specificDaysOfWeek" : "allDays"
  }, 
  "campaignNotificationStatus" :{
    "scheduledTime" : "2021-05-11T11:25:19",
    "smsNotificationStatus" : "true", 
    "campaignNotificationSmsConfig" : { 
      "message" : "This is upgradation event for our previous store in your city on exclusive demands."
    }
  }, 
  "campaignMerchantEventConfig" : {
    "merchantId" : "38040d80-b66e-4fba-b2f2-08ff7530f506",
    "linkName" : "Local Bike Fair and Store Launch", 
    "linkUrl" : "https://www.justdial.com/Bangalore/Whitefield-Yamaha-Forum-Mall-Whitefield/080PXX80-XX80-170511152022-C5Z1_BZDET", 
    "qrCodeScanPermission" : "member",
    "eventStartTime" : "2021-05-15T11:30:19", 
    "eventEndTime" : "2021-05-30T11:30:19", 
    "pointsTiers" : [
      { 
        "lowerLimit" : 0,  
        "upperLimit" : 100, 
        "pointsMultiplierFromMerchant" : 2
      }, 
      { 
        "lowerLimit" : 101,  
        "upperLimit" : 800, 
        "pointsMultiplierFromMerchant" : 3
      }
    ], 
    "pointsAccruedPerCheckIn" : 50,
    "pointsCeilingForCheckIn" : 1500,
    "pointsCeilingPerUserForCheckIn": 100,
    "checkInFrequency" : "daily",
    "pointsCeilingPerTransaction" : 1000,
    "pointsCeilingPerUser" : 500, 
    "transactionCountCeilingPerUser" : 3, 
    "pointsCeilingForCampaign" : 100000, 
    "address" : "No. 2, Whitefield Main Rd, Brooke Bond First Cross, Whitefield, Bengaluru, Karnataka 560066"
  }
}

User Segment Model

Parameter Required? Type Description
userType Yes String UserType expects a string value, which must belong to set { all, userSegment }, for case of userSegment *it is required that valid userSegmentId must be provided.
userSegmentId Yes UUID The userSegmentId is is unique value referring to group of users that may be addressed under a logical unqiue ID, if userSegmentId is provided with "all" userType then it would be invalidated.

Ad Config Model

Parameter Required? Type Description
linkName Yes String Link name refers to logical name for the description of the link that would be shown to users in applications.
linkUrl Yes UUID Actual link which linkName would be pointing to.

Genblu Config Model

Parameter Required? Type Description
linkName Yes String Link name refers to logical name for the description of the link that would be shown to users in applications.
linkUrl Yes UUID Actual link which linkName would be pointing to.
eventStartTime Yes DateTime
eventEndTime Yes DateTime
pointsTiers Yes [PointTiers] List of Point Tiers for campaign
pointsCeilingPerTransaction Yes Number
pointsCeilingPerUser Yes Number
transactionCountCeilingPerUser Yes Number
pointsCeilingForCampaign Yes Number

Event Config Model

Parameter Required? Type Description
merchantId No UUID Unique ID for merchant who may be involved in A&P Event.
qrCodeScanPermission Yes String QRCodeScanPermission expects values from set { merchantAndMember, member }.
eventStartTime Yes DateTime
eventEndTime Yes DateTime
pointsTiers Yes [PointTiers]
pointsAccruedPerCheckIn Yes Number
pointsCeilingForCheckIn Yes Number
pointsCeilingPerUserForCheckIn Yes Number
checkInFrequency Yes Number Number of points that would be rewarded per check-in of customer.
pointsCeilingPerTransaction Yes Number
pointsCeilingPerUser Yes Number
transactionCountCeilingPerUser Yes Number
pointsCeilingForCampaign Yes Number
address Yes Number Address of event.

Merchant Event Config Model

Parameter Required? Type Description
merchantId No UUID Unique ID for merchant who may be involved in A&P Event.
qrCodeScanPermission Yes String QRCodeScanPermission expects values from set { merchantAndMember, member }.
eventStartTime Yes Date
eventEndTime Yes Date
pointsTiers Yes [PointTiers]
pointsAccruedPerCheckIn Yes Number
pointsCeilingForCheckIn Yes Number
pointsCeilingPerUserForCheckIn Yes Number
checkInFrequency Yes Number
pointsCeilingPerTransaction Yes Number
pointsCeilingPerUser Yes Number
transactionCountCeilingPerUser Yes Number
pointsCeilingForCampaign Yes Number
address Yes Number

Campaign Schedule Model

Parameter Required? Type Description
startDate Yes UUID Unique ID for merchant who may be involved in A&P Event.
endDate Yes String QRCodeScanPermission expects values from set { merchantAndMember, member }.
timeOfDayStart Yes Date
timeOfDayEnd Yes Date
specificDaysOfWeek Yes [PointTiers] Actual link which linkName would be pointing to.
pointsAccruedPerCheckIn Yes Number Number of points that would be rewarded per check-in of customer.
runOnDaysOfWeek Yes Number Number of points that would be rewarded per check-in of customer.

Campaign Notification Model

Parameter Required? Type Description
emailNotificationStatus Yes Boolean Is email allowed for notiifcation ?
smsNotificationStatus Yes Boolean Is sms allowed for notiifcation ?
pushNotificationStatus Yes Boolean Is push notification allowed for notiifcation ?
emailNotificationConfig Yes Object
smsNotificationConfig Yes Object
pushNotificationConfig Yes Object
scheduledTime Yes DateTime

Point Tier Model

Parameter Required? Type Description
lowerLimit Yes Number Unique ID for merchant who may be involved in A&P Event.
upperLimit Yes Number QRCodeScanPermission expects values from set { merchantAndMember, member }.
pointsMultiplierFromMerchant No Double Actual link which linkName would be pointing to.
pointsMultiplierFromYamaha No Double Actual link which linkName would be pointing to.

Email Notification Model

Parameter Required? Type
subject Yes String
htmlBody Yes String

SMS Notification Model

Parameter Required? Type
message Yes String

Push Notification Model

Parameter Required? Type
message Yes String

Response

On successful creation, the response would be containing status of 200, and body of response would be containing the actual campaign that is created. This would also contain automatically generated campaignID.

Error Code Description Possible Cause
500 Internal Server Error Failing to provide legal values for set defined values e.g, type; logically invalid values for fields may result into this.
401 Bad Request Failed to follow the requirements of input in any way which woulod fail the intial validation of the request.
200 OK Resource (Campaign) was created successfully, this would create the campaign with the specified attributes. Success would also return the campaign created with unique UUID.

Sample Response

{
  "id": "fa513ef4-be75-4673-92f4-a86c205d9221",
  "title": "Store Upgradation Event in Bengaluru, Karnataka, India",
  "content": "Local Merchant Events, arrive and participate and win to our brand new yamaha franchisee.",
  "status": "enabled",
  "startDate": "2021-05-15",
  "endDate": "2021-05-30",
  "type": "merchantEvent",
  "bannerImageUrl": "https://5.imimg.com/data5/RC/KK/MY-989864/yamaha-bike-500x500.png",
  "contentImageUrls": [
    "https://i.pinimg.com/originals/d3/b6/48/d3b6488dd189048d58d82a4aee68dcef.jpg",
    "https://cdn.statically.io/img/wallpaperplay.com/walls/full/6/6/c/8130.jpg",
    "https://images.unsplash.com/photo-1506765515384-028b60a970df?ixid\\u003dMnwxMjA3fDB8MHxzZWFyY2h8Mnx8YmFubmVyfGVufDB8fDB8fA%3D%3D\\u0026ixlib\\u003drb-1.2.1\\u0026w\\u003d1000\\u0026q\\u003d80",
    "https://st.depositphotos.com/1157537/2479/v/600/depositphotos_24798755-stock-illustration-red-ribbon-set.jpg"
  ],
  "campaignEventConfig": {
    "merchantId": "38040d80-b66e-4fba-b2f2-08ff7530f506",
    "eventStartTime": {
      "date": "2021-05-15",
      "time": "11:30:19"
    },
    "eventEndTime": {
      "date": "2021-05-30",
      "time": "11:30:19"
    },
    "qrCodeScanPermission": "member",
    "pointsAccruedPerCheckIn": 50,
    "pointsCeilingForCheckIn": 1500,
    "pointsCeilingPerUserForCheckIn": 100,
    "checkInFrequency": "daily",
    "pointsCeilingPerTransaction": 1000,
    "pointsCeilingPerUser": 500,
    "transactionCountCeilingPerUser": 3,
    "pointsCeilingForCampaign": 100000,
    "address": "No. 2, Whitefield Main Rd, Brooke Bond First Cross, Whitefield, Bengaluru, Karnataka 560066"
  },
  "campaignSchedule": {
    "startDate": "2021-05-11",
    "endDate": "2021-05-25",
    "timeOfDayStart": "16:46",
    "timeOfDayEnd": "20:46",
    "specificDaysOfWeek": "allDays"
  },
  "createTime": "Apr 26, 2021, 1:15:11 PM",
  "updateTime": "Apr 26, 2021, 1:15:11 PM"
}

Get Multiple Campaigns

GET /campaigns

This method for Campaigns is valid for all the types of users that are supported by system. This would en-list multiple campaigns as described by the condition that are made within the request.

Request

Query String Parameters

Following enlists the query string parameters, that are required for making this request. CampaignType is described in the seperate table and its validity for different types of users, campaignCategory need not be specified for members (customers) while with merchants its a required parameter. It might throw an error in response with incompatible calls. Pagination bookmark and fetch limit are not required parameters, they are meant for too many records. In default case it would fetch 100 records starting from index 0 (its just like array of values but in database).

In summary, campaignType is always required. campaignCategory is only required for merchants, with others it is incomptaible.

Parameter Required? Type Description
campaignType Yes String CampaignType is paramter for filter for different campaigns. These belong to various categories for different types of users.
campaignCategory No String Campaign Category is meant for the merchant users only, since they can have My Events category seperated by Others events. It can have legal values in { myEvent, others }. MyEvents catyegory is meant for events in which merchant is involved while others are those in which merchant is not involved.
paginationBookmark No Number For last point of access in campaign records searching.
fetchLimit No Number Fetch Limit is the total number of records that would be fetched in a single request starting from paginationBookmark.

Campaign Type

Following enlists the compatibility of each type of user with what type of campaignType it can request.

UserType / CampaignType all scheduled upcoming live expired disabled draft
Member No No No Yes No No No
Merchant No No Yes Yes Yes No No
OpsUser Yes Yes Yes Yes Yes Yes Yes

Response

Response to the multiple campaign fetch request contain following fields and values.

Parameter Type Description
campaignList [campaign] Actual campaign list with details about campaigns, it is a list containing campaigns with lesser number of details. It contains minimalistic details of campaign. The campaign model id described later.
campaignCounts Number Campaigns total matched count, this is beneficial for paginated query response, and multiple other params.

Campaign Model

Parameter Type Mandatory? Description
id UUID Yes This is unique UUID field for campaign, can be used to fetch actual campaign record.
title String Yes This is the title for campaign.
content String Yes This is detailed content about campaign.
status String Yes It is current status of campaign it may be one of { enabled, disabled, draft }
startDate Date Yes Campign Start Date
endDate Date Yes Campaign End Date
type String Yes Type of campaign it is, it is already described what type of campaign do exist.
bannerImageUrl String Yes It is a URL string for link to the image resource for image to be displayed on banner.
campaignSchedule Object Yes This is collection of fields for campaign schedule.
eventSchedule Object No This is collection of fields for event schedule. It will not be present in response structure for advertisement events.

Event Schedule Response Model

This will be present inside the response as sub part of campaigns.

Parameter Type Mandatory? Description
eventStartTime DateTime No Actual start time for event. Advertisemnent event will not have eventStartTime field in response structure.
eventEndTime DateTime No Actual end time for event. Advertisemnent event will not have eventEndTime field in response structure.
linkName String Yes Name to be displayed for event link
linkUrl String Yes Link URL for campaign.

Campaign Schedule Response Model

This model will be present in the respponse as sub part of list of campaigns.

Parameter Type Mandatory? Description
startDate DateTime Yes Start date for event.
endDate DateTime Yes End date for event.
timeOfDayStart String Yes Start time
timeOfDayEnd String Yes End Time
specificDaysOfWeek String Yes Specific Days must be one of {allDays, specificDays}
runOnDaysOfWeek [String] No List of Strings providing the actual days of campaign schedule. It will only be present when specificDaysOfWeek will be specificDays

Please note that campaignCount signifies the total number of campaigns that satisfy our condition it may or may not be equal to actual campaignList provided. It is done in order to fetch the paginated response.

Sample Response for multiple events 

{
  "campaignList": [
    {
      "id": "141a2701-dc2a-4c88-8130-567636902f9e",
      "title": "Partners' Events",
      "content": "GenBlu Yearly event collaborated with Yamaha Motors",
      "status": "enabled",
      "startDate": "2021-04-10",
      "endDate": "2021-04-30",
      "type": "genbluStore",
      "bannerImageUrl": "https://5.imimg.com/data5/RC/KK/MY-989864/yamaha-bike-500x500.png",
      "campaignSchedule": {
        "startDate": "2021-04-10",
        "endDate": "2021-04-30",
        "timeOfDayStart": "16:46",
        "timeOfDayEnd": "20:46",
        "specificDaysOfWeek": "allDays"
      },
      "eventSchedule": {
        "eventStartTime": "2021-04-26T11:30:19",
        "eventEndTime": "2021-04-30T11:30:19",
        "linkName": "Get Started",
        "linkUrl": "https://www.yamaha-motor.com.my/yamaha-gen-blu-carnival-r15-launch/"
      }
    }
  ],
  "campaignCounts": 1
}

Get Single Campaign

GET /campaigns/{campaign-id}

Single Campaign can be fetched from API using the camapaign UUID as a path parameter. This would return a single record for campaign based on the UUID.

CampaignID would be provided as Path Parameter of this request

Parameter Required? Type Description
campaign-id Yes UUID The UUID of the campaign we need to fetch.

Response

The response to this event would be different depending upon the user type in the request.

Sample Response for single campaign (for Member)

{
    "id": "081128f2-9668-42a7-afc6-972df6ac55a3",
    "title": "New Month Event",
    "content": "This new year celebrate with us.",
    "bannerImageUrl": "https://cdn.pixabay.com/photo/2019/10/06/10/03/team-4529717__480.jpg",
    "contentImageUrls": [
        "https://i.pinimg.com/originals/d3/b6/48/d3b6488dd189048d58d82a4aee68dcef.jpg",
        "https://cdn.statically.io/img/wallpaperplay.com/walls/full/6/6/c/8130.jpg",
        "https://images.unsplash.com/photo-1506765515384-028b60a970df?ixid=MnwxMjA3fDB8MHxzZWFyY2h8Mnx8YmFubmVyfGVufDB8fDB8fA%3D%3D&ixlib=rb-1.2.1&w=1000&q=80",
        "https://st.depositphotos.com/1157537/2479/v/600/depositphotos_24798755-stock-illustration-red-ribbon-set.jpg"
    ],
    "link": "https://www.youtube.com/watch?v=84Af6_2lIuY",
    "linkName": "Yamaha Bikes this year",
    "campaignType": "advertisement"
}

Update Campaigns

PUT /campaigns/{campaign-id}

This API endpoint is intended for resource Campaigns, this method would be creating a new campaign based on the values provided in the body of requests. The paramaters provided for creating the request must be in consisitent with the requirements for creating the campaigns failing which errors like 404 or 500 group would be sent viz. response.

Request Body Parameters and their description

The request body contains the overall paramters for updating the record. If the request body contains valid parameters then it would be updating the requested record. The request body for this request is same as that of the Create request, the only difference is that Campaign ID need to be provided as path parameters to this request, which is required parameter.

Parameter Required? Type Description
campaign-id Yes String The UUID of the campaign we need to update.

Request body has same parameters as that of Create Request for campaign, please refer to it for valid requests., this request takes the overall final form of record it updates the entire record and not single or multiple individual fields. Please notice that you need to send the overall updated record values you need to update.

Campaign CheckIn

Member Only Check In

Request

POST /campaigns/member-checkin

This request uses body params for getting campaign-id for this request.

Response

The response structure for this request contains details associated with checkIn, transactionId for checkIn and pointsAccrued for this checkIn.

Sample Output 

{
    "id": "f88d36b0-332d-4a2c-b9b9-706569879861",
    "participationTime": {
        "date": "2021-05-06",
        "time": "09:06:56.023018"
    },
    "campaignId": "11caf9b1-d3d7-443f-8af2-3b0c2d966be6",
    "memberId": "e7e3b4d6-8ee8-4b15-b57c-4f2a43190553",
    "checkInCreator": "member",
    "checkInCreatorId": "38040d80-b66e-4fba-b2f2-08ff7530f506",
    "pointsAccrued": 50,
    "transactionId": "868b5cd3-3b92-443e-a3a6-dddf4836fd11",
    "createTime": "May 6, 2021, 9:06:56 AM",
    "updateTime": "May 6, 2021, 9:06:56 AM"
}

Merchant aided Member CheckIn

Request

POST /campaigns/member-checkin

This request uses body params for getting campaign-id and member-id for this request.

Response

The response structure for this request contains details associated with checkIn, transactionId for checkIn and pointsAccrued for this checkIn.

Sample Output 

{
    "id": "f88d36b0-332d-4a2c-b9b9-706569879861",
    "participationTime": {
        "date": "2021-05-06",
        "time": "09:06:56.023018"
    },
    "campaignId": "11caf9b1-d3d7-443f-8af2-3b0c2d966be6",
    "memberId": "e7e3b4d6-8ee8-4b15-b57c-4f2a43190553",
    "checkInCreator": "member",
    "checkInCreatorId": "38040d80-b66e-4fba-b2f2-08ff7530f506",
    "pointsAccrued": 50,
    "transactionId": "868b5cd3-3b92-443e-a3a6-dddf4836fd11",
    "createTime": "May 6, 2021, 9:06:56 AM",
    "updateTime": "May 6, 2021, 9:06:56 AM"
}

Common Campaigns for Merchant / Member

Request

Query String Parameters

This request requires member-id in query string parameters.

Response

The response contains the list of events / merchant events which are common between both of the merchant and member as specified in the request.

Sample Output 

[
    {
        "campaign": {
            "id": "0c989ff5-dbc0-4ccc-b23c-ec6ce92c97d7",
            "title": "Partners' Events",
            "content": "GenBlu Yearly event collaborated with Yamaha Motors",
            "userSegment": {
                "userType": "all"
            },
            "status": "enabled",
            "startDate": "2021-04-15",
            "endDate": "2021-05-30",
            "type": "event",
            "bannerImageUrl": "https://5.imimg.com/data5/RC/KK/MY-989864/yamaha-bike-500x500.png",
            "campaignSchedule": {
                "startDate": "2021-05-11",
                "endDate": "2021-05-25",
                "timeOfDayStart": "16:46",
                "timeOfDayEnd": "20:46",
                "specificDaysOfWeek": "allDays"
            },
            "eventSchedule": {
                "merchantId": "c9a2f11e-43f4-4c86-8343-039b79cc93ea",
                "eventStartTime": "2021-04-15T11:30:19",
                "eventEndTime": "2021-05-30T23:30:19",
                "address": "No. 2, Whitefield Main Rd, Brooke Bond First Cross, Whitefield, Bengaluru, Karnataka 560066",
                "checkInCountCeiling": 2,
                "dayOfWeekSet": [
                    "SATURDAY",
                    "MONDAY"
                ]
            }
        },
        "allowedType": "regular",
        "checkInCount": 0
    }
]

Points

Member Points Balance

GET /members/{member-id}/points-balance

Request

Path Parameters

This request requires member-id as a path parameter.

Response

Sample Response

{
    "points": [
        {
            "id": "b7486dc2-33bb-49be-9b89-f102e48ee359",
            "pointsAllocated": 1000,
            "balance": 1000,
            "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
            "expiryDate": "2022-05-05",
            "allocationDate": "2021-05-05",
            "pointsProvider": "ops"
        },
        {
            "id": "378308f8-4584-41ed-90b4-46c60dcc642e",
            "pointsAllocated": 1000,
            "balance": 1000,
            "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
            "expiryDate": "2022-05-05",
            "allocationDate": "2021-05-05",
            "pointsProvider": "ops"
        },
        {
            "id": "1a170e8c-07ba-4ada-b5f8-f956c0c824a7",
            "pointsAllocated": 1000,
            "balance": 1000,
            "memberId": "0225f813-cda5-4331-9c5e-e17e6a69b82c",
            "expiryDate": "2022-05-05",
            "allocationDate": "2021-05-05",
            "pointsProvider": "ops"
        }
    ],
    "totalPoints": 3000,
    "pointCount": 3
}

Merchant Points Balance

GET /merchants/{merchant-id}/points-balance

Request

Path Parameters

This request requires a merchant-id parameter in request.

Response

The response contains the list of valid points with some details.

Sample Output 

{
    "points": [
        {
            "id": "cb3f0808-686c-473d-b381-620829edae13",
            "pointsAllocated": 100000,
            "allocationDate": "2021-05-05"
        },
        {
            "id": "9e8d3a63-f8b6-490e-aeaa-77d4f74f169f",
            "pointsAllocated": 100000,
            "allocationDate": "2021-05-05"
        }
    ],
    "totalPoints": 200000,
    "pointCount": 2
}

POS

Overview

This document outlines the integration flow for the merchant POS System to perform the following operations: - Utilize a member's points for a discount on products bought by the member. - Reward points to an existing member using a mobile number or to a new mobile number. - Verify a member's digital voucher at POS to validate if the voucher is valid for redemption. - Redeem a member's digital voucher at POS.

These resources allow the POS system to interact with the Yamaha LMS for: - Point deduction from the members. - Point awards to members. - Voucher verification and redemption.

The process also involves bearer token authentication for secure authorization and an error-handling mechanism.

APIs Involved

For member point deduction, it has two main APIs and one webhook API:

  1. Get Member Balance API
  2. Request Member Points API
  3. Transaction Status Webhook API

for member point award by POS, one API needs to be integrated:

  1. Award Points to Member API

For voucher verification and redemption:

  1. Verify Digital Voucher API
  2. Redeem Digital Voucher API

Base URL

Authorization

The Bearer Authentication mechanism is used for API authentication. - The token will be used to identify the merchant POS system to log the requested transaction. - Tokens will be generated and provided by the tech team for all individual merchants.

HTTP Status Code Summary

Status Code Status Message Description
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid token was provided.
403 Forbidden The user is not authorized to access the resource.
409 Conflict The request conflicts with another request (perhaps due to using the same transaction key).
422 Request Failed The parameters were valid but the request failed.
500, 502, 503, 504 Server Errors Something went wrong on the LMS end. (These are rare.)

API Endpoints

GET - POS Get Member Balance

URL:
https://zgh4ccfjs3.execute-api.ap-southeast-1.amazonaws.com/v1/pos/member/{number}/points-balance

Purpose: Fetch the current member point balance from the LMS system.

Request: Pass the member card or mobile number in the URL path variable {number}.

Response: Returns the name and points.

Authorization: Bearer {{token}}

POST - POS Request Member Points

Sample Input Parameters

{
    "transactionId": "bb8eddef-3d56-4d5b-b380-0956ad2e65534",
    "number": "60167725655",
    "points": 6
}

URL:
https://zgh4ccfjs3.execute-api.ap-southeast-1.amazonaws.com/v1/pos/member/transaction

Purpose: Raise a request to the LMS system to initiate the member's points deduction transaction flow.

Response: Returns a success message for a valid request.

Authorization: Bearer {{token}}

POST - Transaction Status Webhook

Sample Input Parameters

{
  "id": "cc6b84ee-7a29-4fba-8ea3-9c0c55d600cf",
  "data": {
    "eventType": "transaction",
    "transactionId": "241028115547-11272",
    "status": "Approved"
  }
}

URL:
{{webhookUrl}}

Body: Contains transaction information, such as

  1. id: Unique identifier for webhook

  2. eventType:- Webhook event name.

  3. status:- Status of the requested transaction (Approved, or Declined).

  4. transactionId:- Unique Identifier in the POS system for each transaction request.

Purpose: To acknowledge the requested transaction status in the POS system after the member's consent.

Note: Merchants need to provide the webhook URL.

POST - POS Award Points to Member

Sample Input Parameters

{
    "number": "60167725655",
    "merchantId": "bf544601-f761-4520-8385-fd87aef84fc1",
    "pointsRewarded": 2,
    "merchantRemarks": "test 8 nov 22"
}

URL:
{{baseUrl}}/v1/pos/merchant/points/award

Purpose: Raise a request to the LMS system to award points to an active member/new number using a mobile number.

Response: Returns a success message for a valid request.

Authorization: Bearer {{token}}

POST - Verify Digital Voucher

URL:
{{baseUrl}}/v1/pos/voucher/verify

Purpose: Request the LMS system to verify a digital voucher.

Sample Input Parameters

{
    "transactionId": "frufiuefer43i3453o546dsh",
    "purchaseValue": 4.0,
    "appliedVoucherCode": "ce93937f-b688-4f6e-9c53-630bbe757338",
    "number": "145559813"
}

Sample Output Parameters

{
    "message": "Voucher is valid to redeem.",
    "voucherValue": 9.0
}

Request:

Field Data Type Description
transactionId String Unique Identifier in the POS system for each transaction request.
purchaseValue Double Purchase value of item purchased at POS by member.
appliedVoucherCode String Unique voucher ID received by scanning the voucher QR code.
number String Mobile number of the member.

Response:

Field Data Type Description
message String Success message.
voucherValue Double Discount value of the voucher.

Authorization: Bearer {{token}}

POST - Redeem Digital Voucher

Sample Input Parameters

{
    "transactionId": "frufiuefer43i3453o54u",
    "purchaseValue": 5,
    "appliedVoucherCode": "50ac317b-0491-455e-be2c-4ca5df30802d",
    "number": "145559813"
}

Sample Output Parameters

{
    "message": "Voucher redeemed successfully.",
    "voucherValue": 20.0
}

URL:
{{baseUrl}}/v1/pos/voucher/redeem

Purpose: Request the LMS system to redeem a digital voucher.

Request:

Field Data Type Description
transactionId String Unique Identifier in the POS system for each transaction request.
purchaseValue Double Purchase value of item purchased at POS by member.
appliedVoucherCode String Unique voucher ID received by scanning the voucher QR code.
number String Mobile number of the member.

Response:

Field Data Type Description
message String Success message.
voucherValue Double Voucher point value to be credited to the merchant on redemption of the member's digital voucher.

Authorization: Bearer {{token}}

Errors

The Kittn API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell ruby python javascript