User

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

Available Endpoints

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

Body

playerAttributes Object

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":"jon.snow@example.com",
      "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

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 -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
  "playerUniqueId":"player123",
  "playerAttributes":{
      "displayName":"Jon Snow",
      "firstName": "Jon",
      "lastName": "Snow",
      "mobile": "+1234567",
      "email":"jon.snow@example.com",
      "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'

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 'tyrion@example.com' 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 -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player456",
   "playerAttributes":{
      "displayName":" Tyrion Lannister",
      "firstName":"Tyrion",
      "lastName":"Lannister",
      "email":"tyrion@example.com",
      "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'

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

Path Parameters

Response

Sample Response

{
   "playerUniqueId":"player456",
   "playerAttributes":{
      "displayName":"Jon Snow",
      "email":"jon.snow@example.com",
      "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 -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/player/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

Path Parameters

Usage Example

curl -X DELETE -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/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

Path Parameters

Response

coupon Object

product Object

collection Object

group Object

optionsObject

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 -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/coupon'

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

Path Parameters

Query Parameters

Response

referredFriend Object

Sample Response

{
   "referredFriends":[
      {
         "displayName":"Jon Snow",
         "email":"jon.snow@example.com",
         "mobileNumber":"0123456789",
         "joinDate":"09/19/2019 21:06:29",
         "status":"Pending",
         "playerUniqueId":"123"
      },
      {
         "displayName":"Arya Stark",
         "email":"arya.stark@example.com",
         "mobileNumber":"0111111119",
         "joinDate":"09/19/2018 22:16:25",
         "status":"Active",
         "playerUniqueId":"123"
      }
   ],
   "total":2,
   "count":2,
   "totalPending":1,
   "totalActive":1
}

Usage Example

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

Last updated