User

The User API can be used to create, update and display users' information on Referd. Users are uniquely identified by playerUniqueId.

Available Endpoints

Type	Description	Endpoint
POST		/integrations/player
GET		/integrations/player/{playerUnqiueId}
DELETE		/integrations/player/{playerUnqiueId}
GET		/integrations/transactions/{playerUniqueId}/coupon
GET		/integrations/players/{playerUniqueId}/referrals

POST - Create User

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

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

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key

Body

Attribute	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the user in your database. Could be database ID, random string, email or anything that uniquely identifies the user.
playerAttributes	object	No
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	User's display name.
firstName	string	User's first name.
lastName	string	User's last name.
mobile	string	User's mobile number.
gender	string	User's gender. Example: M or F, Male or Female.
email	string	User's email.
dateOfBirth	string	User's date of birth. Example: "1980-09-19T00:00:00.000Z"
joinDate	string	User's join date at your system. Example: "2019-09-19T21:06:29.158Z"
tags	string	Comma separated string of tags to be attached to the user. Example: "VIP,Platinum"
country	string	Country of the user.
city	string	City of the user.
zip	string	ZIP of the user.
totalSpent	float	Total amount spent by user.
totalOrders	int	Total orders by user.
lastOrderDate	date	Last order date.
avgOrderAmount	float	Average order amount.
custom	object	Key value pairs of any extra player attributes. {"class" : "E2022", "weight" : 78}

To ensure that a referral is properly counted, it is a must that the newly created user includes the same emailor mobilein the playerAttributes(specified in the request body) same as provided during the referral landing page submission.

{
   "playerUniqueId":"player123",
   "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
      }
    },
    "levelOrder": null
  }

Response

Parameter	Type	Description
playerUniqueId	string	Unique identifier for the user at Referd.
gameballId	string	User's ID at Referd.
referralLink	string	Referral URL.

Sample Response

{
    "playerUniqueId": "player123",
    "gameballId": 160281869,
    "referralCode": "QQAF9B02734oKn",
    "referralLink": "https://invite.myrfrl.link/aa8d2507"
}

Usage Examples

Example One

This example creates a new user at Referd, using playerUniqueId, playerAttributes with custom attributes.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
  "playerUniqueId":"player123",
  "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

To complete the referral process, the new user must visit the referral link provided by the referrer and input their mobile phone number or email based on the client's specified configuration. Subsequently, a request should be sent to Referd to register this user. It is crucial that the new user re-enters the same emailor mobile, which was initially provided on the landing page, within the playerAttributes sent in the create user request.

In the following example, a request is sent to Referd to create a user with the email '[e-mail]' who was successfully referred by another user. The email is included within the playerAttributes. To ensure the referral is counted, the user must input the same email during the referred player's registration on the landing page.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "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({
   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);

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.

GET - Retrieve User

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

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

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client APIKey
Lang	string	No	Language to get the user's 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 user at Referd.

Response

Parameter	Type	Description
playerUniqueId	string	Unique identifier for the user at Referd.
playerAttributes	object
referralLink	string	Referral URL.

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"
}

Usage Example

The example shown is a request sent to Referd to get a user 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”);

DELETE - Delete User

This API is used to delete a user along with his attributes, rewards and actions.

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

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 user at Referd.

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 - User's Coupons

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

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

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 user at Referd.

Response

Attribute	Type	Description
coupons	array

coupon Object

Parameter	Type	Description
code	string	Coupon Code.
isUsed	boolean	A boolean indicating if the coupon was used by the specified user.
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
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
options	object

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 user 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 minimum amount a user 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 - User's Referrals

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

This endpoint is used to get the Referrals of a specific user with the status of the referral for each referred user, 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 user at Referd.

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
count	integer	Count of users in the in current page.
total	integer	Total number of users referred by the given user.
totalPending	integer	Total "pending" number of users referred by the given user but haven't completed the required referral action (e.g. Placed an order).
totalActive	integer	Total "active" number of users successfully referred by the given user and have completed the required referral action (e.g. Placed an order).

referredFriend Object

Parameter	Type	Description
playerUniqueId	string	Unique identifier for the user at Referd.
displayName	string	User's display name.
email	string	User's email.
mobileNumber	string	User's mobile number.
joinDate	DateTime	The date at which the user joined the store.
status	string	Indicates the status of the referred user, 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”);