Customer Management
Manage customer data by creating, updating, or removing customer profiles. These endpoints provide essential functionality for handling customer information across Gameball.
Available APIs
POST - Create or Update Customer
https://api.gameball.co/api/v4.0/integrations/customers
This API enables you to create or update a customer profile in Gameball using a unique customerId
. Serving as a consistent identity, this customerId
allows you to track a customer’s entire journey, linking them to all associated events, purchases, and loyalty activities across their lifetime. This ensures comprehensive customer management within the Gameball platform.
Security: Requires apiKey header.
Request
Body
application/json
customerId string
Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Its recommended not to use sequence for customerId
email string
Optional
Customer's email address.
Note: This is required if your account uses email-based channel merging.
mobile string
Optional
Customer's mobile number.
Note: This is required if your account uses mobile-based channel merging.
deviceToken string
Optional
Token used to identify the device.
osType string
Optional
Operating system type of the device.
customerAttributes Object
Optional
Additional customer-specific attributes. Includes attributes such as the customer’s name, contact details, and purchase history.
referrerCode string
Optional
The referral code of an existing customer who is referring the customer being created. This is required in the create customer request to process the referral.
guest boolean
Optional
A flag indicating if the individual interacting with your system is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default.
Sample request
{
"customerId": "cust_abc12345xyz67890",
"customerAttributes": {
"country": "USA",
"city": "Los Angeles",
"zip": "90001",
"dateOfBirth": "1985-10-25",
"joinDate": "2023-05-01",
"custom": {
"membershipLevel": "Gold",
},
"tags": [
"loyal",
"VIP"
],
"source": "website",
"utMs": [],
"devices": [],
"paymentMethods": [],
"totalSpent": 1500,
"lastOrderDate": "2024-09-15T00:00:00",
"totalOrders": 25
}
}
Response
application/json
gameballId number
The customer’s unique ID within the Gameball system. This ID is used to store the customer in our database and is different from the customerId used in the dashboard.
Sample Response
{
"gameballId": 417984
}
GET - Customer
https://api.gameball.co/api/v4/integrations/customers/{customerId}
This API allows you to retrieve essential customer information from Gameball using a unique customerId
. While focused on providing key profile details, the response excludes personally identifiable information (PII), ensuring secure access to customer data for seamless integration and personalized engagement.
Security: Requires apiKey header.
Request
Path Parameters
customerId string
Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Response
application/json
gameballId number
The customer’s unique ID within the Gameball system. This ID is used to store the customer in our database and is different from the customerId used in the dashboard.
customerId string
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
customerAttributes Object
Optional
Additional customer-specific attributes. Includes attributes such as the customer’s name, contact details, and purchase history.
referralCode string
The referral code of the customer. Used to refer other customers.
referralLink string
The referral link generated for the customer.
dynamicReferralLink string
A dynamic referral link for mobile apps, enabling users to share a unique URL with others for referral purposes.
Sample Response
{
"gameballId": 417384,
"customerId": "cust_abc12345xyz67890",
"customerAttributes": {
"gender": "Male",
"community": "Gaming",
"country": "USA",
"city": "Los Angeles",
"zip": "90001",
"custom": {},
"tags": [
"loyal",
"VIP"
],
"source": "website",
"utMs": [],
"devices": [],
"paymentMethods": [],
"totalSpent": 1500,
"lastOrderDate": "2024-09-15T00:00:00",
"totalOrders": 25,
"manualDate": null
},
"referralCode": "n13jACFC400AYZ",
"referralLink": "https://myapp.com/register?ReferralCode=n13jACFC400AYZ",
"dynamicReferralLink": null
}
GET - Customer Details
https://api.gameball.co/api/v4/integrations/customers/{customerId}/details
This API provides access to comprehensive customer information in Gameball, including personally identifiable information (PII), using a unique customerId
. Secured by a secret key, this endpoint ensures that sensitive customer data remains protected, offering a complete view of the customer profile for more personalized and secure interactions.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string
Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Response
application/json
customerId string
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
gameballId number
The customer’s unique ID within the Gameball system. This ID is used to store the customer in our database and is different from the customerId used in the dashboard.
customerAttributes Object
Additional customer-specific attributes. Includes attributes such as the customer’s name, contact details, and purchase history.
referralCode string
The referral code of the customer. Used to refer other customers.
referralLink string
The referral link generated for the customer.
dynamicReferralLink string
A dynamic referral link for mobile apps, enabling users to share a unique URL with others for referral purposes.
Sample Response
{
"customerId": "cust_abc12345xyz67890",
"gameballId": 418384,
"customerAttributes": {
"displayName": "John Doe",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"manualDate": null,
"gender": "Male",
"mobile": "+11234567890",
"dateOfBirth": "1985-10-25T00:00:00",
"joinDate": "2023-05-01T00:00:00",
"country": "USA",
"city": "Los Angeles",
"zip": "90001",
"custom": {
"favoriteCategory": "Electronics",
"purchaseIntent": "High"
},
"tags": [
"loyal",
"VIP"
],
"source": "website",
"utMs": [],
"devices": [],
"paymentMethods": [],
"totalSpent": 1024,
"lastOrderDate": "2024-09-15T00:00:00",
"totalOrders": 20
},
"referralCode": "n13jACFC400AYZ",
"referralLink": "https://myapp.com/account/register?ReferralCode=n13jACFC400AYZ",
"dynamicReferralLink": "https://myapp.page.link/xyz123?d=1"
}
GET - Customer Coupons
https://api.gameball.co/api/v4/integrations/customers/{customerId}/coupons
This API retrieves a customer’s available coupons in Gameball, offering detailed information on each coupon's type, status, and usage. Use this endpoint to access current coupon data associated with the customer for better engagement.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string
Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Response
application/json
coupons array
List of coupon objects associated with the customer.
Sample Response
{
"coupons": [
{
"name": "Welcome Discount",
"code": "WELCOME2024",
"value": 10,
"type": "percentage",
"target": "Reward",
"isManualCoupon": false,
"currency": "USD",
"startDate": "2024-01-01T00:00:00.000Z",
"expiryDate": "2024-12-31T23:59:59.999Z",
"isExpired": false,
"isActive": true,
"usageLimit": 999,
"limitPerCustomer": 1,
"usedCount": 10,
"customerUsedCount": 0,
"capping": 50,
"minOrderValue": 20,
"entitledProductIds": ["prod_123", "prod_456"],
"entitledVariantIds": ["var_789"],
"entitledCollectionIds": ["col_101112"],
"entitledMerchantIds": [],
"entitledPlatforms": ["online", "mobile"],
"combinesWith": {
"orderDiscounts": true,
"productDiscounts": false,
"shippingDiscounts": true
},
"group": {
"handle": "welcome-offers",
"url": "https://example.com/coupons/welcome-offers",
"iconPath": "/images/icons/welcome.png"
},
"isAvlaibleToUse": false
}
]
}
DELETE - Delete Customer
https://api.gameball.co/api/v4/integrations/customers/{customerId}
The API call removes the customer identified by customerId
from the system. This removes the customer profile and associated data.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string
Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
GET - Customer Hash
https://api.gameball.co/api/v4/integrations/customers/{customerId}/hash
The API call generates a hash for an existing customer based on their unique customerId. This hash is used to securely redeem loyalty points during transactions.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string
Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Response
application/json
hash string
A unique, rotating identifier generated for each customer, used as an additional layer of security and verification during redemptions and hold operations. This number is dynamically regenerated with each transaction to ensure secure validation and prevent unauthorized actions. The hash
serves as a key to verify the legitimacy of the redemption or hold request. Refer to the Hold Management Section for more details about using the hash generated here.
Sample Response
{
"hash": "039684"
}
Last updated