Player

Search…
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 Progress 👑
/integrations/player/{playerUnqiueIdl}/progress
DELETE
​Delete Player​
/integrations/player/{playerUnqiueId}
GET
​Challenge Progress​
/integrations/player/{playerUnqiueIdl}/progress/challenge/{handle}
GET
​Challenge Config​
/integrations/config/challenge/{handle}
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.
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.
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.
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"
community
string
Describe which community a player belongs to.
Example: ?
custom
object
Key value pairs of any extra player attributes.
{"class" : "E2022", "weight" : 78}
{
   "playerUniqueId":"player123",
   "mobile": "+1234567",
   "email": "[email protected]",
   "playerAttributes":{
      "displayName":"Jon Snow",
      "firstName": "Jon",
      "lastName": "Snow",
      "mobile": "+1234567",
      "email":"[email protected]",
      "gender":"M",
      "dateOfBirth":"1980-09-19T00:00:00.000Z",
      "joinDate":"2019-09-19T21:06:29.158Z",
      "tags": "VIP,Platinum",
    	"custom":{
           "location":"Miami",
           "graduationDate":"2018-07-04T21:06:29.158Z",
           "isMarried":false
        }
    },
    "referrerCode": null,
    "levelOrder": null,
  }
Response
Parameter
Type
Description
gameballId
string
Player's ID at Gameball
Sample Response
{
    "gameballId": "4067"
}
Usage Examples
Example One
This example creates a new player at Gameball, using playerUniqueId, playerAttributes with custom attributes.
cURL
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
  "playerUniqueId":"player123",
  "mobile": "+1234567",
  "email": "[email protected]",
  "playerAttributes":{
      "displayName":"Jon Snow",
      "firstName": "Jon",
      "lastName": "Snow",
      "mobile": "+1234567",
      "email":"[email protected]",
      "gender":"M",
      "dateOfBirth":"1980-09-19T00: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'
Gameball::Player.initialize_player({
   playerUniqueId:"player123",
   mobile: "+1234567",
   email: "[email protected]",
   "playerAttributes":{
      displayName:"Jon Snow",
      firstName: "Jon",
      lastName: "Snow",
      mobile: "+1234567",
      email:"[email protected]",
      gender:"M",
      dateOfBirth:DateTime.iso8601("1980-09-19T00:00:00.000Z"),
      joinDate:DateTime.iso8601("2019-09-19T21:06:29.158Z"),
      tags: "VIP,Platinum",
    	custom:{
           location:"Miami",
           graduationDate:"2018-07-04T21:06:29.158Z",
           isMarried:false
        }
    }
  })
$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Jon Snow";
$playerAttributes->firstName = 'Jon';
$playerAttributes->lastName = 'snow';
$playerAttributes->gender = 'M';
$playerAttributes->email = '[email protected]';
$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(
        "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);
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",
        "[email protected]",
        "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
        }
    )
)
player_response = gameball.initialize_player(player_request)
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 = "[email protected]",
			Gender = "M",
			Mobile = "+1234567",
			DateOfBirth = new DateTime(1980, 9, 19),
			JoinDate = new DateTime(2019, 9, 19, 21, 6, 29, 158)
		}
	};
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
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "referrerCode":"CODE11",
   "playerUniqueId":"player456",
   "playerAttributes":{
      "displayName":" Tyrion Lannister",
      "firstName":"Tyrion",
      "lastName":"Lannister",
      "email":"[email protected]",
      "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'
Gameball::Player.initialize_player({
   referrerCode:"CODE11",
   playerUniqueId:"player456",
   playerAttributes:{
      displayName:" Tyrion Lannister",
      firstName:"Tyrion",
      lastName:"Lannister",
      email:"[email protected]",
      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
  	}
   })
$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Tyrion Lannister";
$playerAttributes->firstName = 'Tyrion';
$playerAttributes->lastName = 'Lannister';
$playerAttributes->gender = 'M';
$playerAttributes->email = '[email protected]';
$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);
# Initialize Player
player_request = gameball.playerObject("player123", 
    player_attributes = gameball.playerAttributes(
        "Jon Snow",
        "Jon",
        "Snow",
        "+1234567",
        "[email protected]",
        "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)
var request = new PlayerRequest()
	{
		PlayerUniqueId = "player123",
		PlayerAttributes = new PlayerAttributes()
		{
			DisplayName = "Jon Snow",
			FirstName = "Jon",
			LastName = "Snow",
			Email = "[email protected]",
			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.
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":"[email protected]",
      "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/[email protected]",
      "benefits":{
         "scoreEntryReward":0,
         "pointsEntryReward":0,
         "levelDiscount":null,
         "discountCapping":null
      }
   }
}
Usage Example
The example shown is a request sent to Gameball to get a player info  with playerUniqueId“player456”.
cURL
Ruby
PHP
Python
.NET
curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456'
Gameball::Player.get_player_info("player456")
$playerResponse = $gameball->player->getPlayerInfo("player456");
player_response = gameball.get_player_info("player456")
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
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.
Sample Response
{
    "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 balance with his playerUniqueId
cURL
Ruby
PHP
Python
.NET
curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/balance'
Gameball::Player.get_player_balance("player456")
$playerResponse = $gameball->player->getPlayerBalance("player456");
player_response = gameball.get_player_balance("player456")
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 order.
name: Level name.
minProgress: Minimum score to be in that level.
icon: The icon URL describing 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.
points
object
An object that describes the player's current balance.
points Object
The points 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
id
string
Unique Identifier for the challenge.
name
string
Challenge Name
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.
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.
isRepeatable
boolean
Indicates whether the challenge is repeatable or not.
icon
string
The challenge's icon URL path.
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":[
      {
         "id":"123",
         "name":"Welcome",
         "isUnlocked":true,
         "highScoreAmount":null,
         "completionPercentage":0,
         "isRepeatable":false,
         "achievedCount":0,
         "icon":"https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb.png"
      },
      {
         "id":"p123",
         "name":"Place Order",
         "isUnlocked":true,
         "highScoreAmount":null,
         "completionPercentage":55,
         "isRepeatable":true,
         "achievedCount":2,
         "icon":"https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb.png"
      }
   ],
   "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
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/progress'
Gameball::Player.get_player_progress("player456")
$playerResponse = $gameball->player->getPlayerProgress("player456");
player_response = gameball.get_player_progress("player456")
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 pleaser replace it with %20, for example: New 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
id
integer
Challenge Id
name
string
Challenge Name
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)
isRepeatable
boolean
A boolean indicating if the challenge is repeatable for the specified Player or not
achievedCount
integer
Number of times challenge has been achieved by the specified player