v4.0

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 Customer

https://api.gameball.co/api/v4/integrations/customers

The API call is used to create or update a customer in Gameball based on the provided unique customerId and optional attributes. This allows for effective management of customer profiles

Security: Requires apiKey header.

Channel Merging Available If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Channel Merging Guide.

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.

email string Optional Customer's email address.

mobile string Optional Customer's mobile number.

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.

customerAttributes object

displayName string Optional Display name for the customer.

firstName string Optional Customer's first name.

lastName string Optional Customer's last name.

email string Optional Customer's email address.

gender string Optional Customer's gender.

mobile string Optional Customer's mobile number.

dateOfBirth string Optional Customer's date of birth.

joinDate string Optional Date the customer joined.

country string Optional Customer's country.

city string Optional Customer's city.

zip string Optional Customer's postal code.

preferredLanguage string Optional The customer's preferred language for communication and interactions. This is typically used to personalize notifications, messages, and other system interactions based on the customer's language preference.

tags string Optional A list of tags or labels associated with the customer. These tags are used to categorize customers for personalized marketing campaigns, rewards, and tailored communications. Tags can represent customer preferences, behaviors, or any other custom categories relevant to your business.

Example: A customer could have tags like "VIP", "High Spender", or "Frequent Shopper" to indicate their status or behavior patterns, allowing for more targeted engagement.

source string Optional Source of the customer registration.

utms array Optional List of UTM attributes associated with the customer.

devices array Optional List of devices associated with the customer.

paymentMethods array Optional List of payment methods used by the customer.This array may include various forms of payment, such as credit cards, PayPal, or other payment providers.Each payment method is represented as a string.

Example:[ "Credit Card", "PayPal", "Apple Pay" ]

totalSpent float Optional Total amount spent by the customer.

lastOrderDate string Optional Date of the last order placed by the customer.

totalOrders integer Optional Total number of orders placed by the customer.

avgOrderAmount float Optional Average amount spent per order by this customer.

channel string Optional Represents the platform or medium through which the customer interacts with your business. This could refer to various sales or communication channels like physical stores, your mobile application, social media, or third-party services.

Example: "channel": "Mobile App"

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}

The API call retrieves customer information identified by customerId while excluding personal identifiable information (PII). This ensures that sensitive information remains protected while still providing essential customer details.

This endpoint returns general customer info (no personal data) with the public key. To access PII, use Get Customer Details with the secret key.

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.

This is a minimized customerAttributes object, excluding all personally identifiable information (PII) for privacy protection.

customerAttributes object

custom Object Key-value pairs that allow you to store additional attributes for the customer. This can include any extra information specific to your needs, enabling more personalized interactions and offerings.

gender string Customer's gender.

country string Customer's country.

city string Customer's city.

tags array Tags associated with the customer.

source string Source of the customer registration.

utMs array List of UTM attributes associated with the customer.

devices array List of devices associated with the customer.

paymentMethods array List of payment methods used by the customer.

totalSpent number Total amount spent by the customer.

lastOrderDate string Date of the last order placed by the customer.

totalOrders number Total number of orders placed by the customer.

manualDate string Custom date for manual entries.

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

The API call retrieves information identified by customerId, including personal identifiable information (PII). This endpoint is secured by a secret key, ensuring that access to sensitive customer profiles is restricted and protected.

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.

customerAttributes object

displayName string

Display name for the customer.

firstName string

Customer's first name.

lastName string

Customer's last name.

email string

Customer's email address.

gender string

Customer's gender.

mobile string

Customer's mobile number.

dateOfBirth string

Customer's date of birth.

joinDate string

Date the customer joined.

country string

Customer's country.

city string

Customer's city.

zip string

Customer's postal code.

preferredLanguage string

The customer's preferred language for communication and interactions. This is typically used to personalize notifications, messages, and other system interactions based on the customer's language preference.

tags string

A list of tags or labels associated with the customer. These tags are used to categorize customers for personalized marketing campaigns, rewards, and tailored communications. Tags can represent customer preferences, behaviors, or any other custom categories relevant to your business.

Example:

  • "VIP"

  • "High Spender"

  • "Frequent Shopper"

These tags allow for more targeted engagement based on customer status or behavior patterns.

source string

Source of the customer registration.

utms array

List of UTM attributes associated with the customer.

devices array

List of devices associated with the customer.

paymentMethods array

List of payment methods used by the customer. This array may include various forms of payment, such as credit cards, PayPal, or other payment providers. Each payment method is represented as a string.

Example:

  • ["Credit Card", "PayPal", "Apple Pay"]

totalSpent number

Total amount spent by the customer.

lastOrderDate string

Date of the last order placed by the customer.

totalOrders number

Total number of orders placed by the customer.

avgOrderAmount number

Average amount spent per order by this customer.

channel string

Represents the platform or medium through which the customer interacts with your business. This could refer to various sales or communication channels like physical stores, your mobile application, social media, or third-party services.

Example:

  • "Mobile App"

  • "Website"

  • "In-store"

  • "Social Media"

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": "johndoe@company.com",
        "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"
}

DELETE - Delete Customer

https://api.gameball.co/api/v4/integrations/customers/{customerId}

The API call deletes the customer identified by customerId from the system. This removes the customer profile and associated data.

This API can also be accessed using the POST method for systems that do not support DELETE. In such cases, simply use /customers/{customerId}/delete endpoint to achieve the same functionality.

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

PreviousCustomersNextCustomer Progress

Last updated