# User

## Available Endpoints

<table data-header-hidden><thead><tr><th width="116.33333333333331">Type</th><th width="266">Description</th><th>Endpoint</th></tr></thead><tbody><tr><td>Type</td><td>Description</td><td>Endpoint</td></tr><tr><td><strong>POST</strong></td><td><a href="#post-create-user"><strong>Create User</strong></a></td><td>/integrations/player</td></tr><tr><td><strong>GET</strong></td><td><a href="#get-retrieve-user"><strong>Retrieve User</strong></a></td><td>/integrations/player/{playerUnqiueId}</td></tr><tr><td><strong>DELETE</strong></td><td><a href="#delete-delete-user"><strong>Delete User</strong></a></td><td>/integrations/player/{playerUnqiueId}</td></tr><tr><td><strong>GET</strong></td><td><a href="#get-users-coupons"><strong>User's Coupons</strong></a></td><td>/integrations/transactions/{playerUniqueId}/coupon</td></tr><tr><td><strong>GET</strong></td><td><a href="#get-users-referrals"><strong>Get User's Referrals</strong></a></td><td>/integrations/players/{playerUniqueId}/referrals</td></tr></tbody></table>

## POST - Create User

```http
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      | <p>Unique identifier for the user in your database.</p><p>Could be database ID, random string, email or anything that uniquely identifies the user.</p>                                                                   |
| `playerAttributes` | **object** | No       | <p>An <a href="#playerattributes-object"><strong>object</strong></a> with set of properties that you want to set for the user.<br>This object also includes a <code>custom</code>object inside for custom attributes.</p> |
| `deviceToken`      | **string** | No       | <p>The FCM token (Firebase Cloud Messaging) needed for sending mobile push notifications.<br>(Used only in case of mobile app)</p>                                                                                        |
| `osType`           | **string** | No\*     | <p>OS Type according to the mobile device used (if any).<br><strong>Note:</strong> Required in case <strong><code>deviceToken</code></strong> is sent in the payload (e.g. "android", "ios")</p>                          |

#### `playerAttributes` Object

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

{% hint style="info" %}
To ensure that a referral is properly counted, it is a must that the newly created user includes the same **`email`**&#x6F;r **`mobile`**&#x69;n the **`playerAttributes`**(specified in the request body) same as provided during the referral landing page submission.
{% endhint %}

```javascript
{
   "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

| 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**

```javascript
{
    "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.

{% tabs %}
{% tab title="cURL" %}

```javascript
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'
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
Gameball::Player.initialize_player({
   playerUniqueId:"player123",
   mobile: "+1234567",
   email: "jon.snow@example.com",
   "playerAttributes":{
      displayName:"Jon Snow",
      firstName: "Jon",
      lastName: "Snow",
      mobile: "+1234567",
      email:"jon.snow@example.com",
      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
        }
    }
  })
```

{% endtab %}

{% tab title="PHP" %}

```php
$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Jon Snow";
$playerAttributes->firstName = 'Jon';
$playerAttributes->lastName = 'snow';
$playerAttributes->gender = 'M';
$playerAttributes->email = 'jon.snow@example.com';
$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);
```

{% endtab %}

{% tab title="Python" %}

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

{% endtab %}

{% tab title=".NET" %}

```aspnet
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 = "jon.snow@example.com",
			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);
```

{% endtab %}
{% endtabs %}

#### 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 **`email`**&#x6F;r **`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.

{% tabs %}
{% tab title="cURL" %}

```typescript
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'
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
Gameball::Player.initialize_player({
   playerUniqueId:"player456",
   playerAttributes:{
      displayName:" Tyrion Lannister",
      firstName:"Tyrion",
      lastName:"Lannister",
      email:"tyrion@example.com",
      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
  	}
   })
```

{% endtab %}

{% tab title="PHP" %}

```php
$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Tyrion Lannister";
$playerAttributes->firstName = 'Tyrion';
$playerAttributes->lastName = 'Lannister';
$playerAttributes->gender = 'M';
$playerAttributes->email = 'tyrion@example.com';
$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);
```

{% endtab %}

{% tab title="Python" %}

```python
# Initialize Player
player_request = gameball.playerObject("player123", 
    player_attributes = gameball.playerAttributes(
        "Jon Snow",
        "Jon",
        "Snow",
        "+1234567",
        "jon.snow@example.com",
        "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)
```

{% endtab %}

{% tab title=".NET" %}

```
var request = new PlayerRequest()
	{
		PlayerUniqueId = "player123",
		PlayerAttributes = new PlayerAttributes()
		{
			DisplayName = "Jon Snow",
			FirstName = "Jon",
			LastName = "Snow",
			Email = "jon.snow@example.com",
			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);
```

{% endtab %}
{% endtabs %}

**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.

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

### Request

#### Header

| Attribute | Type       | Required | Description                                                                                                                                                                                                                                                                              |
| --------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APIKey`  | **string** | Yes      | Client APIKey                                                                                                                                                                                                                                                                            |
| `Lang`    | **string** | No       | <p>Language to get the user's info with. If not provided, the response would be in default language.</p><p><strong>Note:</strong> The language provided should be as per configured languages in your account.</p><p><strong>Example:</strong> <code>"en"</code>, <code>"fr"</code>.</p> |

#### Path Parameters

<table data-header-hidden><thead><tr><th width="218">Parameter</th><th width="150">Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td><code>playerUniqueId</code></td><td><strong>string</strong></td><td>Yes</td><td>Unique identifier for the user at <strong>Referd.</strong></td></tr></tbody></table>

### Response

<table data-header-hidden><thead><tr><th width="242.33333333333331">Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td></tr><tr><td><code>playerUniqueId</code></td><td><strong>string</strong></td><td>Unique identifier for the user at <strong>Referd.</strong></td></tr><tr><td><code>playerAttributes</code></td><td><strong>object</strong></td><td>An <a href="#playerattributes-object"><strong>object</strong></a> with set of user properties defined previously at the user's creation.</td></tr><tr><td><code>referralLink</code></td><td><strong>string</strong></td><td>Referral URL.</td></tr></tbody></table>

#### Sample Response

```javascript
{
   "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”.**

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Ruby" %}

```ruby
Gameball::Player.get_player_info("player456")
```

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title="Python" %}

```python
player_response = gameball.get_player_info("player456")
```

{% endtab %}

{% tab title=".NET" %}

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

{% endtab %}
{% endtabs %}

## DELETE - Delete User

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

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

### Request

#### Header

<table data-header-hidden><thead><tr><th>Attribute</th><th width="186">Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td><code>APIKey</code></td><td><strong>string</strong></td><td>Yes</td><td>Client API key</td></tr><tr><td><code>secretKey</code></td><td><strong>string</strong></td><td>Yes</td><td>Client Secret Key</td></tr></tbody></table>

#### Path Parameters

<table data-header-hidden><thead><tr><th width="237">Attribute</th><th width="122">Type</th><th width="130">Required</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td><code>playerUniqueId</code></td><td><strong>string</strong></td><td>Yes</td><td>Unique identifier for the user at <strong>Referd</strong>.</td></tr></tbody></table>

### Usage Example

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Ruby" %}

```ruby
Gameball::Player.delete("player456")
```

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title="Python" %}

```python
player_response = gameball.deletePlayer("player456")
```

{% endtab %}

{% tab title=".NET" %}

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

{% endtab %}
{% endtabs %}

## GET - User's Coupons

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

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

### Request

#### Header

<table data-header-hidden><thead><tr><th width="192">Attribute</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td><code>APIKey</code></td><td><strong>string</strong></td><td>Yes</td><td>Client API key</td></tr><tr><td><code>secretKey</code></td><td><strong>string</strong></td><td>Yes</td><td>Client Secret Key</td></tr></tbody></table>

#### Path Parameters

<table data-header-hidden><thead><tr><th width="220">Attribute</th><th width="117">Type</th><th width="123">Required</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td><code>playerUniqueId</code></td><td><strong>string</strong></td><td>Yes</td><td>Unique identifier for the user at <strong>Referd</strong>.</td></tr></tbody></table>

### Response

<table data-header-hidden><thead><tr><th width="232">Attribute</th><th width="126.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Description</td></tr><tr><td><code>coupons</code></td><td><strong>array</strong></td><td>An array of <strong>Coupon</strong> <a href="#coupon-object"><strong>objects</strong></a>.</td></tr></tbody></table>

#### `coupon` Object

<table><thead><tr><th width="247">Parameter</th><th width="143">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>code</code></td><td><strong>string</strong></td><td>Coupon Code.</td></tr><tr><td><code>isUsed</code></td><td><strong>boolean</strong></td><td>A <strong>boolean</strong> indicating if the coupon was used by the specified user.</td></tr><tr><td><code>value</code></td><td><strong>double</strong></td><td>Value of coupon. ( in the case of percentage discount this would be the value in percentage of the coupon)</td></tr><tr><td><code>currency</code></td><td><strong>string</strong></td><td>Currency of the coupon.</td></tr><tr><td><code>creationDate</code></td><td><strong>DateTime</strong></td><td>The date that the coupon was created on.</td></tr><tr><td><code>couponType</code></td><td><strong>string</strong></td><td><p>Indicates the type of the coupon, the value of the string can be one of the following:</p><ul><li><strong><code>free_shipping</code></strong></li><li><strong><code>percentage_discount</code></strong></li><li><strong><code>fixed_discount</code></strong></li><li><strong><code>free_product</code></strong></li><li><strong><code>fixed_rate_discount</code></strong></li><li><strong><code>custom</code></strong></li></ul></td></tr><tr><td><code>product</code></td><td><strong>object</strong></td><td>In the case of <strong><code>free_product</code></strong> coupon, a <code>product</code> <a href="#product-object"><strong>object</strong> </a>indicates the details of the free product.</td></tr><tr><td><code>startAt</code></td><td><strong>DateTime</strong></td><td>Date that the coupon starts at and can be applied.</td></tr><tr><td><code>endAt</code></td><td><strong>DateTime</strong></td><td>Date that the coupon expires at.</td></tr><tr><td><code>isExpired</code></td><td><strong>boolean</strong></td><td>Boolean indicating if the coupon is expired.</td></tr><tr><td><code>collections</code></td><td><strong>array</strong></td><td>An array of <strong>Collection</strong> Objects specifying the collections that the coupon can be applied on.</td></tr><tr><td><code>group</code></td><td><strong>object</strong></td><td>An <a href="#group-object"><strong>object</strong> </a>describing the coupon group which the coupon belongs to.</td></tr><tr><td><code>options</code></td><td><strong>object</strong></td><td>An <a href="#optionsobject"><strong>object</strong> </a>describing the coupon's options.</td></tr></tbody></table>

#### **`product` Object**

<table><thead><tr><th width="257">Parameter</th><th width="106">Type</th><th>Description</th><th data-hidden>Parameter</th></tr></thead><tbody><tr><td><code>productId</code></td><td><strong>integer</strong></td><td>Unique identifier of the product.</td><td><code>productId</code></td></tr><tr><td><code>productName</code></td><td><strong>string</strong></td><td>Name of the product.</td><td><code>productName</code></td></tr><tr><td><code>productDisplayName</code></td><td><strong>array</strong></td><td>An array of display names for the product.</td><td><code>productDisplayNames</code></td></tr><tr><td><code>variantId</code></td><td><strong>integer</strong></td><td>In case the product has variants this is the id of the variant.</td><td><code>variantId</code></td></tr><tr><td><code>variantName</code></td><td><strong>string</strong></td><td>In case the product has variants this is the name of the variant.</td><td><code>variantName</code></td></tr></tbody></table>

**`collection` Object**

<table><thead><tr><th width="257">Type</th><th width="106"></th><th>Description</th><th data-hidden>Parameter</th></tr></thead><tbody><tr><td><code>collectionId</code></td><td><strong>integer</strong></td><td>Unique identifier of the collection.</td><td><code>productId</code></td></tr><tr><td><code>collectionName</code></td><td><strong>string</strong></td><td>Name of the collection.</td><td><code>productName</code></td></tr></tbody></table>

#### **`group` Object**

<table><thead><tr><th width="257">Parameter</th><th width="113">Type</th><th>Description</th><th data-hidden>Parameter</th></tr></thead><tbody><tr><td><code>handle</code></td><td><strong>string</strong></td><td>A unique identifier for the coupon group.</td><td><code>productId</code></td></tr><tr><td><code>title</code></td><td><strong>string</strong></td><td>Title of the coupon group.</td><td><code>productName</code></td></tr><tr><td><code>url</code></td><td><strong>string</strong></td><td>URL of the coupon group.</td><td></td></tr><tr><td><code>iconPath</code></td><td><strong>string</strong></td><td>Icon path of the coupon group.</td><td></td></tr><tr><td><code>description</code></td><td><strong>string</strong></td><td>Description of the coupon group.</td><td></td></tr><tr><td><code>maxPerPlayer</code></td><td><strong>integer</strong></td><td>Maximum number of times a user can achieve coupons from this group.</td><td></td></tr><tr><td><code>startDate</code></td><td><strong>DateTime</strong></td><td>Date at which coupons can start to be redeemed from this group.</td><td></td></tr><tr><td><code>expiryDate</code></td><td><strong>DateTime</strong></td><td>Date at which you can no longer redeem coupons from this group.</td><td></td></tr><tr><td><code>isAvailable</code></td><td><strong>boolean</strong></td><td>A <strong>boolean</strong> flag indicating if there are coupon available to be redeemed from this group.</td><td></td></tr><tr><td><code>isValid</code></td><td><strong>boolean</strong></td><td>Flag indicating if the group is valid (Current Date is between start and expiry dates).</td><td></td></tr><tr><td><code>isActive</code></td><td><strong>boolean</strong></td><td>Flag indicating if the group is active or not (Client marked the group as active or not and group’s dates are valid).</td><td></td></tr></tbody></table>

#### `options`Object

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

#### Sample Response

```json
[
    {
        "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

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Ruby" %}

```ruby
Gameball::Player.get_player_coupon("player456")
```

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title="Python" %}

```python
player_response = gameball.get_player_coupon("player456")
```

{% endtab %}

{% tab title=".NET" %}

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

{% endtab %}
{% endtabs %}

## GET - User's Referrals

```http
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

<table data-header-hidden><thead><tr><th width="192">Attribute</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td><code>APIKey</code></td><td><strong>string</strong></td><td>Yes</td><td>Client API key</td></tr></tbody></table>

#### Path Parameters

<table data-header-hidden><thead><tr><th width="220">Attribute</th><th width="117">Type</th><th width="123">Required</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td><code>playerUniqueId</code></td><td><strong>string</strong></td><td>Yes</td><td>Unique identifier for the user at <strong>Referd</strong>.</td></tr></tbody></table>

#### Query Parameters

<table data-header-hidden><thead><tr><th width="220">Attribute</th><th width="117">Type</th><th width="123">Required</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td><code>page</code></td><td><strong>integer</strong></td><td>No</td><td>Index of required page. (e.g. 1, 2, ..)<br><strong>Default:</strong> 1</td></tr><tr><td><code>limit</code></td><td><strong>integer</strong></td><td>No</td><td>limit of results per page. (e.g. 10, 20, ..)<br><strong>Default:</strong> 50<br><strong>Max:</strong> 200</td></tr></tbody></table>

### Response

<table data-header-hidden><thead><tr><th width="232">Attribute</th><th width="126.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Description</td></tr><tr><td><code>referredFriends</code></td><td><strong>array</strong></td><td>An array of <strong>referredFriend</strong> <a href="#referredfriend-object"><strong>objects</strong></a>.</td></tr><tr><td><code>count</code></td><td><strong>integer</strong></td><td>Count of users in the in current page.</td></tr><tr><td><code>total</code></td><td><strong>integer</strong></td><td>Total number of users referred by the given user.</td></tr><tr><td><code>totalPending</code></td><td><strong>integer</strong></td><td>Total <strong><code>"pending"</code></strong> number of users referred by the given user but haven't completed the required referral action (e.g. Placed an order).</td></tr><tr><td><code>totalActive</code></td><td><strong>integer</strong></td><td>Total <strong><code>"active"</code></strong> number of users successfully referred by the given user and have completed the required referral action (e.g. Placed an order).</td></tr></tbody></table>

#### **referredFriend** Object

<table><thead><tr><th width="247">Parameter</th><th width="143">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>playerUniqueId</code></td><td><strong>string</strong></td><td>Unique identifier for the user at <strong>Referd</strong>.</td></tr><tr><td><code>displayName</code></td><td><strong>string</strong></td><td>User's display name.</td></tr><tr><td><code>email</code></td><td><strong>string</strong></td><td>User's email.</td></tr><tr><td><code>mobileNumber</code></td><td><strong>string</strong></td><td>User's mobile number.</td></tr><tr><td><code>joinDate</code></td><td><strong>DateTime</strong></td><td>The date at which the user joined the store.</td></tr><tr><td><code>status</code></td><td><strong>string</strong></td><td><p>Indicates the status of the referred user, the value of the string can be one of the following:</p><ul><li><strong><code>active</code></strong></li><li><strong><code>pending</code></strong></li></ul></td></tr></tbody></table>

#### **Sample Response**

```json
{
   "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

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Ruby" %}

```ruby
Gameball::Player.get_player_referrals("player456")
```

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title="Python" %}

```python
player_response = gameball.get_player_referrals("player456")
```

{% endtab %}

{% tab title=".NET" %}

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

{% endtab %}
{% endtabs %}