Player

The Player API can be used to create, update and display players' information as well as attach/detach tags in Gameball. Players are uniquely identified by playerUniqueId.

Available Endpoints

Type	Description	Endpoint
POST	Create Player	/integrations/player
GET	Retrieve Player	/integrations/player/{playerUnqiueId}
GET	Retrieve Player's Balance	/integrations/player/{playerUnqiueIdl}/balance
GET	Retrieve Player's Hash	/integrations/player/{playerUnqiueId} /hash
GET	Retrieve Player's Progress 👑	/integrations/player/{playerUnqiueIdl}/progress
DELETE	Delete Player	/integrations/player/{playerUnqiueId}
GET	Challenge Progress	/integrations/player/{playerUnqiueIdl}/progress/challenge/{handle}
GET	Player's Coupons	/integrations/transactions/{playerUniqueId}/coupon
GET	Get Player's Referrals	/integrations/players/{playerUniqueId}/referrals
GET	Get All Player's Referrals	/integrations/players/referrals
POST	Attach Tags	/integrations/player/{playerUnqiueId}/tags
DELETE	Detach Tags	/integrations/player/{playerUnqiueId}/tags

POST - Create Player

https://api.gameball.co/api/v3.0/integrations/player

The API call is used to create or update a player in Gameball with the provided attributes.

This endpoint could also be used in case of referral. In such case,referralCode of the referring player is to be provided along with the body parameters. So that Gameball understands that the newly created player is being referred.

mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.

In cases where channel merging is supported, you have the flexibility to identify users by their mobile number or email. For accounts utilizing separate systems for online and offline channels, it's advisable to consider changing the customer's unique ID to either their mobile number or email address for enhanced efficiency.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key

Body

Attribute	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player in your database. Could be database ID, random string, email or anything that uniquely identifies the player.
mobile	string	No	Player's unique mobile number. (Sent in case your account supports channel merging)
email	string	No	Player's unique email. (Sent in case your account supports channel merging)
playerAttributes	object	No	An object with set of properties that you want to set for the player. This object also includes a customobject inside for custom attributes.
referrerCode	string	No	Referring player’s referral code. This is used in case of referral, where the player to be created is referred by the player having this code.
levelOrder	integer	No	The level order to place the player in. IMPORTANT: manual player leveling is available under special circumstances and is not available by default. Contact us for more info.
deviceToken	string	No	The FCM token (Firebase Cloud Messaging) needed for sending mobile push notifications. (Used only in case of mobile app)
osType	string	No*	OS Type according to the mobile device used (if any). Note: Required in case deviceToken is sent in the payload (e.g. "android", "ios")

playerAttributes Object

Parameter	Type	Description
displayName	string	Player's display name.
firstName	string	Player's first name.
lastName	string	Player's last name.
mobile	string	Player's mobile number.
gender	string	Player's gender. Example: M or F, Male or Female.
email	string	Player's email.
dateOfBirth	string	Player's date of birth. Example: "1980-09-19T00:00:00.000Z"
joinDate	string	Player join date at your system. Example: "2019-09-19T21:06:29.158Z"
tags	string	Comma separated string of tags to be attached to the player. Example: "VIP,Platinum"
country	string	Country of the player.
city	string	City of the player.
zip	string	ZIP of the player.
totalSpent	float	Total amount spent by player.
totalOrders	int	Total orders by player.
lastOrderDate	date	Last order date.
avgOrderAmount	float	Average order amount.
custom	object	Key value pairs of any extra player attributes. {"class" : "E2022", "weight" : 78}

{
   "playerUniqueId":"player123",
   "mobile": "+1234567", // optional (Channel Merging)
   "email": "[e-mail]", // optional (Channel Merging)
   "playerAttributes":{
      "displayName":"Jon Snow",
      "firstName": "Jon",
      "lastName": "Snow",
      "mobile": "+1234567",
      "email":"[e-mail]",
      "gender":"M",
      "dateOfBirth":"1980-09-19T00:00:00.000Z",
      "joinDate":"2019-09-19T21:06:29.158Z",
       "country": "Egypt",
        "city": "Cairo",
        "zip": "18754",
      "tags": "VIP,Platinum",
      "custom":{
          "location":"Miami",
          "graduationDate":"2018-07-04T21:06:29.158Z",
          "isMarried":false
      }
    },
    "referrerCode": null,
    "levelOrder": null
  }

Response

Parameter	Type	Description
playerUniqueId	string	Unique identifier for the player at Gameball Note: in case your account supports channel merging, mobile or email could be used instead of playerUniqueId.
gameballId	string	Player's ID at Gameball.
levelsProgress	int	The current progress of player on the level.
level	object	Level object holds information about the player's current level at Gameball.
balance	object	An object that contains all the information about the player's balance.
referralCode	string	Player's Referral Code. Used to refer another player.
referralLink	string	Referral URL.
dynamicReferralLink	string	Referral URL for mobile APPs integrations with firebase.

Sample Response

{
    "playerUniqueId": "player123",
    "gameballId": 160281869,
    "levelsProgress": 0,
    "level": {
        "id": 17812,
        "name": "very Basic ",
        "description": "",
        "levelStartScore": 0,
        "levelOrder": 1,
        "iconPath": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.png",
        "benefits": {
            "scoreEnteryReward": 0,
            "pointsEnteryReward": 0,
            "levelDiscount": null,
            "discountCapping": null
        }
    },
    "balance": {
        "pointsBalance": 0,
        "pointsValue": 0.0,
        "pendingPoints": 0,
        "pendingPointsValue": 0.0,
        "currency": "USD",
        "walletPointsName": "Points",
        "totalPositivePoints": 0,
        "totalPositivePendingPoints": 0,
        "totalNegativePoints": 0,
        "totalNegativePendingPoints": 0
    },
    "referralCode": "QQAF9B02734oKn",
    "referralLink": "https://wizardtest123.myshopify.com/account/register?ReferralCode=QQAF9B02734oKn",
    "dynamicReferralLink": null
}

Usage Examples

Example One

This example creates a new player at Gameball, using playerUniqueId, playerAttributes with custom attributes.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
  "playerUniqueId":"player123",
  "mobile": "+1234567",
  "email": "[e-mail]",
  "playerAttributes":{
      "displayName":"Jon Snow",
      "firstName": "Jon",
      "lastName": "Snow",
      "mobile": "+1234567",
      "email":"[e-mail]",
      "gender":"M",
      "dateOfBirth":"1980-09-19T00:00:00.000Z",
      "joinDate":"2019-09-19T21:06:29.158Z",
      "country": "Egypt",
        "city": "Cairo",
        "zip": "18754",
      "custom":{
         "location":"Miami",
         "graduationDate":"2018-07-04T21:06:29.158Z",
         "isMarried":false
      }
   }

  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/player'

Ruby

Gameball::Player.initialize_player({
   playerUniqueId:"player123",
   mobile: "+1234567",
   email: "[e-mail]",
   "playerAttributes":{
      displayName:"Jon Snow",
      firstName: "Jon",
      lastName: "Snow",
      mobile: "+1234567",
      email:"[e-mail]",
      gender:"M",
      dateOfBirth:DateTime.iso8601("1980-09-19T00:00:00.000Z"),
      joinDate:DateTime.iso8601("2019-09-19T21:06:29.158Z"),
      country: "Egypt",
        city: "Cairo",
        zip: "18754",
      tags: "VIP,Platinum",
    	custom:{
           location:"Miami",
           graduationDate:"2018-07-04T21:06:29.158Z",
           isMarried:false
        }
    }
  })

PHP

$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Jon Snow";
$playerAttributes->firstName = 'Jon';
$playerAttributes->lastName = 'snow';
$playerAttributes->gender = 'M';
$playerAttributes->email = '[e-mail]';
$playerAttributes->dateOfBirth = '1978-01-11T00:00:00.000Z';
$playerAttributes->joinDate = '2021-09-19T21:06:29.158Z';
$playerAttributes->country= 'Egypt';
$playerAttributes->city= 'Cairo';
$playerAttributes->zip= '18754';
$playerAttributes->addCustomAttribute('isMarried' , true);
$playerAttributes->addCustomAttribute('location' , 'Miami');
$playerAttributes->addCustomAttribute('graduationDate' , '2018-07-04T21:06:29.158Z');

$playerRequest = \Gameball\Models\PlayerRequest::factory(
        "player123",
        null, // Mobile (not null according to your channel merging config)
        null, // Email (not null according to your channel merging config)
        $playerAttributes
);

$playerResponse = $gameball->player->initializePlayer($playerRequest);

Python

import gameball
gameball.api_key = "API_KEY"
gameball.transaction_key = "TRANSACTION_KEY"

# Initialize Player
player_request = gameball.playerObject("player123", 
    player_attributes = gameball.playerAttributes(
        "Jon Snow",
        "Jon",
        "Snow",
        "+1234567",
        "[e-mail]",
        "M",
        "1980-09-19T00:00:00.000Z",
        "2019-09-19T21:06:29.158Z",
        "Egypt",
        "Cairo",
        "18754",
        tags="VIP,Platinum",
        custom={
            'location':"Miami",
            'graduationDate':"2018-07-04T21:06:29.158Z",
            'isMarried':False
        }
    )
)
player_response = gameball.initialize_player(player_request)

.NET

using Gameball;
var Gameball = new Gameball.Gameball(apiKey: "API_KEY", secretKey: "SECRET_KEY");

var request = new PlayerRequest()
	{
		PlayerUniqueId = "player123",
		PlayerAttributes = new PlayerAttributes()
		{
			DisplayName = "Jon Snow",
			FirstName = "Jon",
			LastName = "Snow",
			Email = "[e-mail]",
			Gender = "M",
			Mobile = "+1234567",
			DateOfBirth = new DateTime(1980, 9, 19),
			JoinDate = new DateTime(2019, 9, 19, 21, 6, 29, 158),
			Country:"Egypt",
			City:"Cairo",
			Zip:"18754"
		}
	};
var response = Gameball.InitializePlayer(request);

Example Two

This example is a request sent to Gameball when player with referralCode“CODE11” successfully refers a new player with playerUniqueId “player456”. Player attributes are also sent within the same request.‌

Note: All attributes inside the playerAttributes object are optional, if the values of any attributes shown below are unavailable, remove the attribute from the playerAttributes object.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "referrerCode":"CODE11",
   "playerUniqueId":"player456",
   "playerAttributes":{
      "displayName":" Tyrion Lannister",
      "firstName":"Tyrion",
      "lastName":"Lannister",
      "email":"[e-mail]",
      "gender":"M",
      "dateOfBirth":"1978-01-11T00:00:00.000Z",
      "joinDate":"2019-09-19T21:06:29.158Z",
      "custom":{
         "location":"Miami",
         "graduationDate":"2018-07-04T21:06:29.158Z",
         "isMarried":false
  	}
   }
  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/player'

Ruby

Gameball::Player.initialize_player({
   referrerCode:"CODE11",
   playerUniqueId:"player456",
   playerAttributes:{
      displayName:" Tyrion Lannister",
      firstName:"Tyrion",
      lastName:"Lannister",
      email:"[e-mail]",
      gender:"M",
      dateOfBirth:DateTime.iso8601("1978-01-11T00:00:00.000Z"),
      joinDate:DateTime.iso8601("2019-09-19T21:06:29.158Z"),
      custom:{
         location:"Miami",
         graduationDate:"2018-07-04T21:06:29.158Z",
         isMarried:false
  	}
   })

PHP

$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Tyrion Lannister";
$playerAttributes->firstName = 'Tyrion';
$playerAttributes->lastName = 'Lannister';
$playerAttributes->gender = 'M';
$playerAttributes->email = '[e-mail]';
$playerAttributes->dateOfBirth = '1978-01-11T00:00:00.000Z';
$playerAttributes->joinDate = '2021-09-19T21:06:29.158Z';
$playerAttributes->addCustomAttribute('isMarried' , true);
$playerAttributes->addCustomAttribute('location' , 'Miami');
$playerAttributes->addCustomAttribute('graduationDate' , '2018-07-04T21:06:29.158Z');

$playerRequest = \Gameball\Models\PlayerRequest::factory(
        "player456",
        null, // Mobile (not null according to your channel merging config)
        null, // Email (not null according to your channel merging config)
        $playerAttributes,
        "CODE11" // ReferrerCode
);

$playerResponse = $gameball->player->initializePlayer($playerRequest);

Python

# Initialize Player
player_request = gameball.playerObject("player123", 
    player_attributes = gameball.playerAttributes(
        "Jon Snow",
        "Jon",
        "Snow",
        "+1234567",
        "[e-mail]",
        "M",
        "1980-09-19T00:00:00.000Z",
        "2019-09-19T21:06:29.158Z",
        tags="VIP,Platinum",
        custom={
            'location':"Miami",
            'graduationDate':"2018-07-04T21:06:29.158Z",
            'isMarried':False
        }    
    ),
    referrer_code="CODE11"
)
player_response = gameball.initialize_player(player_request)

.NET

var request = new PlayerRequest()
	{
		PlayerUniqueId = "player123",
		PlayerAttributes = new PlayerAttributes()
		{
			DisplayName = "Jon Snow",
			FirstName = "Jon",
			LastName = "Snow",
			Email = "[e-mail]",
			Gender = "M",
			Mobile = "+1234567",
			DateOfBirth = new DateTime(1980, 9, 19),
			JoinDate = new DateTime(2019, 9, 19, 21, 6, 29, 158)
		},
		ReferrerCode = "CODE11"
	};
var response = Gameball.InitializePlayer(request);

GET - Retrieve Player

This API call is used to retrieve player's information.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}

mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client APIKey
Lang	string	No	Language to get the player info with. If not provided, the response would be in default language. Note: The language provided should be as per configured languages in your account. Example: "en", "fr".

Path Parameters

Parameter	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player at Gameball. Note: in case your account supports channel merging, mobile or email could be used instead of playerUniqueId

Response

Parameter	Type	Description
playerUniqueId	string	Unique identifier for the player at Gameball.
playerAttributes	object	An object with set of player properties defined previously at the player's creation.
referralCode	string	Player's Referral Code. Used to refer another player.
referralLink	string	Referral URL.
dynamicReferralLink	string	Referral URL for mobile APPs integrations with firebase.
level	object	Level object holds information about the player's current level at Gameball.
levelsProgress	int	The current progress of the player on the level.
points	object	The current balance of the player.

level Object

The level object contains info about the player's current level.

Parameter	Type	Description
name	string	Level Name.
description	string	Level Description.
levelOrder	integer	Level Order.
iconPath	string	Logo icon of the level.
benefits	object	An object contains the benefits of the current level of the specified player. The benefits object is described as follows: scoreEntryReward: Rewarded score on entering the current level. pointsEntryReward: Rewarded points on entering the current level. levelDiscount: Discount rewarded to the player on entering the current level. discountCapping: Maximum order total price that allows the discount to be applied.

Sample Response

{
   "playerUniqueId":"player456",
   "playerAttributes":{
      "displayName":"Jon Snow",
      "email":"[e-mail]",
      "mobileNumber":"0123456789",
      "gender":"M",
      "joinDate":"09/19/2019 21:06:29",
      "tags":[
         "VIP",
         "Elite"
      ],
      "custom":{
         "location":"Miami",
         "graduationDate":"2018-07-04T21:06:29.158Z",
         "isMarried":false
      }
   },
   "referralCode":"CODE12",
   "referralLink":"https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
   "dynamicReferralLink":"https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
   "level":{
      "name":"Gold",
      "description":null,
      "levelOrder":4,
      "iconPath":"https://cdn.gameball.co/uploads/Client 1/[e-mail]",
      "benefits":{
         "scoreEntryReward":0,
         "pointsEntryReward":0,
         "levelDiscount":null,
         "discountCapping":null
      }
   },
    "levelProgress": 0,
    "points": {
        "pointsBalance": 0,
        "pointsValue": 0.0,
        "pendingPoints": 0,
        "pendingPointsValue": 0.0,
        "currency": "USD",
        "walletPointsName": "Points",
        "totalPositivePoints": 0,
        "totalPositivePendingPoints": 0,
        "totalNegativePoints": 0,
        "totalNegativePendingPoints": 0
    }
}

Usage Example

The example shown is a request sent to Gameball to get a player info with playerUniqueId“player456”.

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456'

Ruby

Gameball::Player.get_player_info("player456")

PHP

$playerResponse = $gameball->player->getPlayerInfo("player456");

Python

player_response = gameball.get_player_info("player456")

.NET

var response = Gameball.GetPlayerInfo(“player456”);

GET - Player's Balance

This API call is used to retrieve player's current points balance available for redemption and the corresponding equivalent amount.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/balance

mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client APIKey
secretKey	string	Yes	Client Secret Key

Path Parameters

Parameter	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player at Gameball. Note: in case your account supports channel merging, mobile or email could be used instead of playerUniqueId

Response

Parameter	Type	Description
pointsBalance	integer	Player current points balance.
pointsValue	integer	The player's equivalent monetary value topointsBalance according to your Cashback program configurations.
pendingPoints	integer	Player current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue	integer	The player's equivalent monetary value to pendingPoints according to your Cashback program configurations.
totalPositivePoints	integer	Player current total positive points.
totalPositivePendingPoints	integer	Player current positive pending points.
totalNegativePoints	integer	Player current total negative points.
totalNegativePendingPoints	integer	Player current negative pending points.
currency	string	Store currency.
pointsName	string	The naming of the rewarding points that appears to the player.

Sample Response

{
    "pointsBalance": 11500,
    "pointsValue": 115,
    "pendingPoints": 200,
    "pendingPointsValue": 2,
    "totalPositivePoints": 12500,
    "totalPositivePendingPoints": 135,
    "totalNegativePoints": 1000,
    "totalNegativePendingPoints": 20
    "currency": "USD",
    "pointsName": "Points"
}

Usage Example

The example shown is a request sent to Gameball to get a player's balance with his playerUniqueId

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/balance'

Ruby

Gameball::Player.get_player_balance("player456")

PHP

$playerResponse = $gameball->player->getPlayerBalance("player456");

Python

player_response = gameball.get_player_balance("player456")

.NET

var response = Gameball.GetPlayerBalance(“player456”);

GET - Player's Hash

This API call is used to retrieve player's hash value which is calculated for each player, and rotates with the player's every transaction.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/hash

mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client APIKey
secretKey	string	Yes	Client Secret Key

Path Parameters

Parameter	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player at Gameball. Note: in case your account supports channel merging, mobile or email could be used instead of playerUniqueId

Response

Parameter	Type	Description
playerUniqueId	string	Unique identifier for the player at Gameball.
referralCode	string	Player's Referral Code. Used to refer another player.
referralLink	string	Referral URL.
dynamicReferralLink	string	Referral URL for mobile APPs integrations with firebase.
pointsBalance	integer	Player current points balance.
pointsValue	number	The player's equivalent monetary value topointsBalance according to your Cashback program configurations.
pendingPoints	integer	Player current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue	number	The player's equivalent monetary value to pendingPoints according to your Cashback program configurations.
currency	string	Store currency.
pointsName	string	The naming of the rewarding points that appears to the player.
hash	string	A secret number hash that is calculated for each player, and rotates with the player's every transaction.

Sample Response

   {
    "pLayerId": 406044,
    "playerUniqueId": "6886288195890",
    "displayName": "m3 z3",
    "firstName": "m3",
    "lastName": "z3",
    "gender": null,
    "email": "[e-mail]",
    "mobileNumber": null,
    "dateOfBirth": null,
    "joinDate": "2023-03-01T10:28:30",
    "referralCode": "ED1D58A3vTiok9",
    "referralLink": "https://gbdashboardv2-gbx.myshopify.com/account/register?ReferralCode=ED1D58A3vTiok9",
    "dynamicReferralLink": null,
    "levelName": "Basico",
    "levelIconPath": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.png",
    "pointsBalance": 945,
    "pointsValue": 94.5,
    "pendingPoints": 0,
    "pendingPointsValue": 0,
    "pointsToExpire": 555,
    "pointsToExpireValue": 55.5,
    "expiryDate": "2023-03-02T12:23:59.885053",
    "currency": "AED",
    "pointsName": "Puntos",
    "lastActivePointsStatus": 555,
    "lastPendingPointsStatus": 0,
    "lastLevelStatus": "none",
    "lastActivePointsDate": "2023-03-01T12:23:59.913354",
    "lastPendingPointsDate": null,
    "lastLevelDate": null,
    "hash": "502371"
  }

Usage Example

The example shown is a request sent to Gameball to get a player's balance with his playerUniqueId

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' 
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/balance'

Ruby

Gameball::Player.get_player_balance("player456")

PHP

$playerResponse = $gameball->player->getPlayerBalance("player456");

Python

player_response = gameball.get_player_balance("player456")

.NET

var response = Gameball.GetPlayerBalance(“player456”);

GET - Player's Progress 👑

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/progress

mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

This API call is used to show the overall player's progress in the available challenges, referral program and levels across Gameball programs.

This endpoint is only available for our GURU customers only 👑

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client APIKey
secretKey	string	Yes	Client Secret Key

Path Parameters

Parameter	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player at Gameball.

Response

Parameter	Type	Description
playerUniqueId	string	Unique identifier for the player at Gameball.
referralCode	string	Player's referral code.
referralLink	string	Player's referral link.
dynamicReferralLink	string	Referral URL for mobile APPs integrations with firebase.
playerAttributes	object	An object with set of player properties.
levelsProgress	object	An object contains the level information of the current and the next level (empty if the player is on top level already) of the specified player. The level object is described as follows: order: Level's tier e.g., level 1, level 2, level 3. name: Level name. minProgress: Minimum score to be in that level. icon: The icon URL describing the level. progress: The current progress of player on the level .
challengesProgress	array	An array of challenge objects where each describe an available challenge for the player and his progress in each.
totalReferredPlayers	integer	The total number of the player's referred players.
balance	object	An object that describes the player's current balance.

balanceObject

The balance object contains info about the player's points.

Parameter	Type	Description
pointsBalance	integer	Player current points balance.
pointsValue	number	The player's equivalent monetary value topointsBalance according to your Cashback program configurations.
pendingPoints	integer	Player current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue	number	The player's equivalent monetary value to pendingPoints according to your Cashback program configurations.
currency	string	Your system currency as configured at Gameball.
pointsName	string	The naming of the rewarding points that appears to the player.

challenge Object

The challenge object shows description of the challenge as follows.

Parameter	Type	Description
isUnlocked	boolean	Indicates whether the challenge is unlocked for this player or not.
highScoreAmount	integer	Indicates the player's High Score. Note: This field is provided in case the challenge is a High Score Challenge.
currentStreak	integer	The current streak refers to the count of the most recent and uninterrupted series of consecutive events or occurrences.
highestStreak	integer	The highest streak refers to the count of the longest unbroken sequence of events or occurrences achieved at any point in time.
completionPercentage	number	Shows the player's current progress towards achieving the challenge.
achievedCount	integer	The number of times this challenge has been achieved by the player.
challengeConfig	object	AchallengeConfigObject that describes the details of the challenge.

challengeConfig Object

Attribute	Type	Description
id	integer	Challenge Id.
name	string	Challenge internal name.
description	string	Challenge description.( In default language if not specified in query parameter)
rewards	array	An array of Reward objects, these are the rewards that are achieved by completing the specified challenge.
isRepeatable	boolean	A boolean indicating if the challenge is repeatable for the specified Player or not.
maxAchievement	integer	Maximum number of times the specified challenge can be achieved. (-1 if can be achieved for an unlimited number of times)
type	string	Challenge type, can be one of the following: Amount Based Action Based ActionBasedAndAmountBased HighScore UponLogin NonCumulativeAmountBased JoinAnniversary EventBased SocialActivities ScheduledChallenge Streak
visibility	string	Challenge visibility type, can be one of the following: Always Visible Not Visible Visible If Earned
icon	string	URI indicating the file path to the icon of the challenge.
availability	Object	An availability object specifying the conditions where this challenge is available.
redirectionButtonText	string	The text written on the redirection button. (In case the redirection button is enabled for this challenge).
redirectionButtonLink	string	The redirection link. (In case the redirection button is enabled for this challenge)

reward Object

Attribute	Type	Description
rankReward	integer	Progress rewarded towards rank.
walletReward	integer	Points rewarded in wallet.
couponReward	Object	Coupon object that describes the coupon that is rewarded when completing this challenge.

couponReward Object

Attribute	Type	Description
couponType	string	Coupon type, can be one of the following: Fixed Percentage Free Shipping Free Product Fixed Rate Discount
discountValue	double	Value of coupon, for example if the coupon rewards a fixed amount of points then the amount of points will be in discountValue.
minOrderValue	double	Minimum order value that this coupon can be applied to.
product	Object	In the case of a free product coupon this object indicates the details of the product, The object has the the following attributes: productId productName variantId variantName
collections	array	Array of Collection objects in the case where the coupon can only be applied to specific collections, the collection object has the following attributes: collectionId collectionName

availability Object

Attribute	Type	Description
minLevel	integer	Minimum Level where this challenge is available.
tags	array	An array of Tag names. (string)

Sample Response

{
  "playerUniqueId": "player456",
  "referralCode": "CODE12",
  "referralLink": "https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
  "dynamicReferralLink": "https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
  "playerAttributes": {
    "dateOfBirth": null,
    "communityId": null,
    "tags": ["VIP"]
  },
  "levelsProgress": {
    "current": {
      "order": 1,
      "name": "level 1",
      "minProgress": 0,
      "icon": "https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb.png"
    },
    "next": {
      "order": 2,
      "name": "level 2",
      "minProgress": 2000,
      "icon": "https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb.png"
    }
  },
  "challengesProgress": [
    {
      "isUnlocked": true,
      "highScoreAmount": null,
      "completionPercentage": 0,
      "achievedCount": 0,
      "challengeConfig": {
        "id": 1234,
        "name": "Challenge Name",
        "description": "Challenge Description",
        "rewards": [
          {
            "rankReward": 0,
            "walletReward": 0,
            "couponReward": {
              "couponType": "Free Product",
              "discountValue": null,
              "minOrderValue": null,
              "product": {
                "productId": "123456789",
                "productName": "Chequered Red Shirt",
                "variantId": "123456789",
                "variantName": null
              },
              "collections": []
            }
          }
        ],
        "isRepeatable": true,
        "maxAchievement": -1,
        "type": "EventBased",
        "visibility": "Always Visible",
        "icon": "https://s3.us-east-2.amazonaws.com/gameball.dev.uploads/uploads/gb-library/general/annoncement.png",
        "availability": {
          "minLevel": 1,
          "tags": []
        },
        "redirectionButtonText": "Free Gift",
        "redirectionButtonLink": "https://claires.myshopify.com/products/jeans"
      }
    }
  ],
  "totalReferredPlayers": 0,
  "points": {
    "pointsBalance": 11500,
    "pointsValue": 115,
    "pendingPoints": 200,
    "pendingPointsValue": 2,
    "currency": "USD",
    "pointsName": "Points"
  }
}

Usage Example

The example shown is a request sent to Gameball to get a player's progress with playerUniqueId“player456”.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/progress'

Ruby

Gameball::Player.get_player_progress("player456")

PHP

$playerResponse = $gameball->player->getPlayerProgress("player456");

Python

player_response = gameball.get_player_progress("player456")

.NET

var response = Gameball.GetPlayerProgress(“player456”);

GET - Player's Challenge Progress

This API is used to get a player's specific challenge's progress.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/progress/challenge/{handle}

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key
secretKey	string	Yes	Client Secret Key

Path Parameters

Attribute	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player at Gameball.
handle	string	Yes	Identifier of the challenge, either the challengeId, or the challenge internal name.(Note: If challenge name has the space character please replace it with customer would be New%20customer)

Query Parameters

Attribute	Type	Required	Description
lang	string	No	The language you wish to retrieve the information in.

Response

Attribute	Type	Description
challengesProgress	array	A single object array of ChallengesProgress object.

challengesProgress Object

Attribute	Type	Description
isUnlocked	boolean	A boolean indicating if the challenge is unlocked for the specified player.
highScoreAmount	double	Score reached so far. (Could be highScore or greater) (High Score Challenges)
highScore	double	Score needed to be reached to achieve the challenge. (High Score Challenges)
completionPercentage	double	Percentage completed of challenge. (Event based challenges)
achievedCount	integer	Number of times challenge has been achieved by the specified player.
currentStreak	integer	Current streak the specified player is on.
highestStreak	integer	Highest streak the specified player has reached.
challengeConfig	Object	AchallengeConfigObject that describes the details of the challenge.

Sample Response

{
  "challengesProgress": [
    {
      "isUnlocked": true,
      "highScoreAmount": null,
      "highScore": null,
      "completionPercentage": 50.0,
      "achievedCount": 0,
      "currentStreak": null,
      "highestStreak": null,
      "challengeConfig": {
        "id": 1234,
        "name": "Challenge Name",
        "description": "Challenge Description",
        "rewards": [
          {
            "rankReward": 0,
            "walletReward": 0,
            "couponReward": {
              "couponType": "Free Product",
              "discountValue": null,
              "minOrderValue": null,
              "product": {
                "productId": "123456789",
                "productName": "Chequered Red Shirt",
                "variantId": "123456789",
                "variantName": null
              },
              "collections": []
            }
          }
        ],
        "isRepeatable": true,
        "maxAchievement": -1,
        "type": "EventBased",
        "visibility": "Always Visible",
        "icon": "https://s3.us-east-2.amazonaws.com/gameball.dev.uploads/uploads/gb-library/general/annoncement.png",
        "availability": {
          "minLevel": 1,
          "tags": []
        },
        "redirectionButtonText": "Free Gift",
        "redirectionButtonLink": "https://claires.myshopify.com/products/jeans"
      }
    }
  ]
}

Usage Example

The example shown is a request sent to Gameball to get a player's challenge progress with playerUniqueId“player456” and challengeHandle “New%20customer”

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/progress/challenge/New%20customer'

Ruby

Gameball::Player.get_player_challenge_progress("player456","New Customer")

PHP

/$playerResponse = $gameball->player->getPlayerChallengeProgress("player456","New Customer");

Python

player_response = gameball.get_player_challenge_progress("player456","New Customer")

.NET

var response = Gameball.GetPlayerChallengeProgress(“player456”,"New Customer");

DELETE - Delete Player

This API is used to delete a player along with his attributes, transactions, achievements and actions.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}

mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key
secretKey	string	Yes	Client Secret Key

Path Parameters

Attribute	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player at Gameball.

Usage Example

cURL

curl -X DELETE -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456'

Ruby

Gameball::Player.delete("player456")

PHP

$playerResponse = $gameball->player->delete("player456");

Python

player_response = gameball.deletePlayer("player456")

.NET

var response = Gameball.DeletePlayer(“player456”);

GET - Player's Coupons

https://api.gameball.co/api/v3.0/integrations/transactions/{playerUniqueId}/coupon

mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

This endpoint is used to get the Coupons of a specific player.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key
secretKey	string	Yes	Client Secret Key

Path Parameters

Attribute	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player at Gameball.

Response

Attribute	Type	Description
coupons	array	An array of Coupon objects.

coupon Object

Parameter	Type	Description
code	string	Coupon Code.
isUsed	boolean	A boolean indicating if the coupon was used by the specified player.
value	double	Value of coupon. ( in the case of percentage discount this would be the value in percentage of the coupon)
currency	string	Currency of the coupon.
creationDate	DateTime	The date that the coupon was created on.
couponType	string	Indicates the type of the coupon, the value of the string can be one of the following: free_shipping percentage_discount fixed_discount free_product fixed_rate_discount custom
product	object	In the case of free_product coupon, a product object indicates the details of the free product.
startAt	DateTime	Date that the coupon starts at and can be applied.
endAt	DateTime	Date that the coupon expires at.
isExpired	boolean	Boolean indicating if the coupon is expired.
collections	array	An array of Collection Objects specifying the collections that the coupon can be applied on.
group	object	An object describing the coupon group which the coupon belongs to.
options	object	An object describing the coupon's options.

product Object

Parameter	Type	Description
productId	integer	Unique identifier of the product.
productName	string	Name of the product.
productDisplayName	array	An array of display names for the product.
variantId	integer	In case the product has variants this is the id of the variant.
variantName	string	In case the product has variants this is the name of the variant.

collection Object

Type		Description
collectionId	integer	Unique identifier of the collection.
collectionName	string	Name of the collection.

group Object

Parameter	Type	Description
handle	string	A unique identifier for the coupon group.
title	string	Title of the coupon group.
url	string	URL of the coupon group.
iconPath	string	Icon path of the coupon group.
description	string	Description of the coupon group.
maxPerPlayer	integer	Maximum number of times a player can achieve coupons from this group.
startDate	DateTime	Date at which coupons can start to be redeemed from this group.
expiryDate	DateTime	Date at which you can no longer redeem coupons from this group.
isAvailable	boolean	A boolean flag indicating if there are coupon available to be redeemed from this group.
isValid	boolean	Flag indicating if the group is valid (Current Date is between start and expiry dates).
isActive	boolean	Flag indicating if the group is active or not (Client marked the group as active or not and group’s dates are valid).

optionsObject

Parameter	Type	Description
ExpiryAfter	integer	Number of days until the coupon expires.
UsageLimit	integer	Maximum number of times a coupon or offer can be used.
Capping	double	Maximum limit on the total amount of discount that can be applied to an order.
MinOrderValue	double	The lowest amount a player must spend on an order to qualify for the coupon.
CombinesWith	object	An object that that determines whether specific types of discounts can be combined and consists of three boolean values: ShippingDiscounts ProductDiscounts OrderDiscounts
ProductId	string	Unique identifier of the product.
ProductName	string	Name of the product.
VariantId	string	In case the product has variants this is the id of the variant.
VariantName	string	In case the product has variants this is the name of the variant.
ProductDisplayName	string	Display name for the product.
HasCollections	boolean	Indicates if it has collections.
Platforms	array	List of platforms.

Sample Response

[
    {
        "code": "R7KVWwoT4c",
        "isUsed": false,
        "value": 30.0,
        "currency": "EGP",
        "creationDate": "2022-09-21T11:08:42.298758",
        "couponType": "custom",
        "product": {
            "productId": null,
            "productName": null,
            "productDisplayName": null,
            "variantId": null,
            "variantName": null
        },
        "startAt": "2021-09-21T11:08:42.298758",
        "endAt": "2023-09-21T11:08:42.298758",
        "isExpired": false,
        "collections": [],
        "group": {
            "handle": "free_macdo",
            "title": "Free MACDO",
            "url": "https://www.mcdonalds.eg/eat/menu/Item/Chicken-MACDO-",
            "iconPath": "https://www.mcdonalds.eg/Cms_Data/Contents/En/Media/images/Menu/large-Image/Chicken-MACDO.png",
            "description": "Coupons in this group give a free macdo and can be rdeemed in all Mcdonalds branches"
        }
    },
    {
        "code": "zFHYySXdiy",
        "isUsed": false,
        "value": 50.0,
        "currency": "EGP",
        "creationDate": "2022-09-21T11:07:22.718595",
        "couponType": "percentage_discount",
        "product": {
            "productId": null,
            "productName": null,
            "productDisplayName": null,
            "variantId": null,
            "variantName": null
        },
        "startAt": null,
        "endAt": null,
        "isExpired": false,
        "collections": [],
        "group": null
    },
    
]

Usage Example

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/coupon'

Ruby

Gameball::Player.get_player_coupon("player456")

PHP

$playerResponse = $gameball->player->getPlayerCoupon("player456");

Python

player_response = gameball.get_player_coupon("player456")

.NET

var response = Gameball.GetPlayerCoupon(“player456”);

GET - Player's Referrals

https://api.gameball.co/api/v3.0/integrations/players/{playerUniqueId}/referrals

mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

This endpoint is used to get the Referrals of a specific player with the status of the referral for each referred player, whether the referral has been completed (active) or pending the needed referral action (pending) as per your referral configurations.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key

Path Parameters

Attribute	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player at Gameball.

Query Parameters

Attribute	Type	Required	Description
page	integer	No	Index of required page. (e.g. 1, 2, ..) Default: 1
limit	integer	No	limit of results per page. (e.g. 10, 20, ..) Default: 50 Max: 200

Response

Attribute	Type	Description
referredFriends	array	An array of referredFriend objects.
count	integer	Count of players in current page.
total	integer	Total number of players referred by the given player.
totalPending	integer	Total "pending" number of players referred by the given player but haven't completed the required referral action (e.g. Placed an order).
totalActive	integer	Total "active" number of players successfully referred by the given player and have completed the required referral action (e.g. Placed an order).

referredFriend Object

Parameter	Type	Description
playerUniqueId	string	Unique identifier for the player at Gameball.
displayName	string	Player's display name.
email	string	Player's email.
mobileNumber	string	Player's mobile number.
joinDate	DateTime	The date at which the player joined the store.
status	string	Indicates the status of the referred player, the value of the string can be one of the following: active pending

Sample Response

{
   "referredFriends":[
      {
         "displayName":"Jon Snow",
         "email":"[e-mail]",
         "mobileNumber":"0123456789",
         "joinDate":"09/19/2019 21:06:29",
         "status":"Pending",
         "playerUniqueId":"123"
      },
      {
         "displayName":"Arya Stark",
         "email":"[e-mail]",
         "mobileNumber":"0111111119",
         "joinDate":"09/19/2018 22:16:25",
         "status":"Active",
         "playerUniqueId":"123"
      }
   ],
   "total":2,
   "count":2,
   "totalPending":1,
   "totalActive":1
}

Usage Example

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/players/player456/referrals'

Ruby

Gameball::Player.get_player_referrals("player456")

PHP

$playerResponse = $gameball->players->getPlayerReferrals("player456");

Python

player_response = gameball.get_player_referrals("player456")

.NET

var response = Gameball.GetPlayerReferrals(“player456”);

GET - Get all Player's Referrals

https://api.gameball.co/api/v3.0/integrations/players/referrals

This endpoint is used to retrieve a comprehensive list of all referrals made by all players along with the status of each referral for each referred player, whether the referral has been completed (active) or pending the needed referral action (pending) as per your referral configurations.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key

Query Parameters

Attribute	Type	Required	Description
page	integer	No	Index of required page. (e.g. 1, 2, ..) Default: 1
limit	integer	No	limit of results per page. (e.g. 10, 20, ..) Default: 50 Max: 200

Response

Attribute	Type	Description
referredFriends	array	An array of referredFriend objects.
count	integer	Count of players in current page.
total	integer	Total number of players referred by the given player.

referredFriend Object

Parameter	Type	Description
playerUniqueId	string	Unique identifier for the player at Gameball.
displayName	string	Player's display name.
email	string	Player's email.
mobileNumber	string	Player's mobile number.
joinDate	DateTime	The date at which the player joined the store.
status	string	Indicates the status of the referred player, the value of the string can be one of the following: active pending
referredBy	object	A referredBy object

referredBy Object

Attribute	Type	Description
playerUniqueId	string	Unique identifier for the player at Gameball.
displayName	string	Player's display name.
email	string	Player's email.
mobileNumber	string	Player's mobile number.

Sample Response

{
    "referredFriends": [
        {
            "playerUniqueId": "7181703840036",
            "displayName": "referral1 referral1",
            "email": "[e-mail]",
            "mobileNumber": null,
            "joinDate": "0001-01-01T00:00:00",
            "status": "Pending",
            "referredBy": {
                "playerUniqueId": "7181695156516",
                "displayName": "test test",
                "email": "[e-mail]",
                "mobileNumber": null
            }
        },
        {
            "playerUniqueId": "7181952418084",
            "displayName": "adam referral",
            "email": "[e-mail]",
            "mobileNumber": null,
            "joinDate": "0001-01-01T00:00:00",
            "status": "Active",
            "referredBy": {
                "playerUniqueId": "7181703840036",
                "displayName": "referral1 referral1",
                "email": "[e-mail]",
                "mobileNumber": null
            }
        }
    ],
    "count": 2,
    "total": 2
}

Usage Example

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/players/referrals'

POST - Attach Tags to Player

This API is used to attach tags to a Player.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/tags

mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key

Path Parameters

Attribute	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the player at Gameball.

Body

Attribute	Type	Required	Description
tags	string	Yes	Comma separated string of tags to be attached to the player.

Sample Body

{
   "tags":"VIP,Platinum"
}

Usage Example

The example shown is a request sent to Gameball to attach tags "VIP,Platinum" to a player with playerUniqueId“player456”.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d 
'{
   "tags":"VIP,Platinum"
 }' -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/tags'

Ruby

Gameball::Player.attach_tags("player456","VIP,Platinum")

PHP

$playerResponse = $gameball->player->attachTags("player456", "VIP,Platinum");

Python

player_response = gameball.attach_tags("player456","VIP,Platinum")

.NET

var response = Gameball.AttachTags(“player456”, "VIP,Platinum");

DELETE - Detach Tags

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/tags

mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

This API is used to detach tags from a Player.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key

Path Parameters

Attribute	Required	Type	Description
playerUniqueId	Yes	string	Unique identifier for the player at Gameball.

Body

Attribute	Type	Required	Description
tags	string	Yes	Comma separated string of tags to be removed from the player.

Sample Body

{
   "tags":"VIP"
}

Usage Example

The example shown is a request sent to Gameball to detach tags "VIP" from a player with playerUniqueId“player456”.

cURL

curl -X DELETE -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "tags":"VIP"
  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/tags'

Ruby

Gameball::Player.detach_tags("player456","VIP,Platinum")

PHP

$playerResponse = $gameball->player->detachTags("player456", "VIP");

Python

player_response = gameball.detach_tags("player456","VIP")

.NET

var response = Gameball.DetachTags(“player456”, "VIP");