Skip to main content

​
Overview

Customer management is the foundation of your Gameball integration. Before you can track events, process orders, or enable redemption, you need to create and manage customer profiles using the Gameball REST API.
Unlike mobile SDKs that handle customer creation automatically, web integration requires explicit API calls to create and update customer profiles from your backend.

​
Why Customer Management Matters

A Gameball customer profile is essential for:
  • Tracking customer activity - Events and orders must be associated with a customer profile
  • Awarding rewards - Points, campaigns, and rewards are tied to customer profiles
  • Enabling redemption - Customers need profiles to redeem their earned points
  • Personalization - Customer attributes enable targeted campaigns and experiences

​
Creating Customer Profiles

Use the Create/Update Customer API to create new customer profiles or update existing ones.

​
Basic Customer Creation

When a customer signs up or logs in to your website, create their Gameball profile: 
curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'TransactionKey: YOUR_TRANSACTION_KEY' \
  -d '{
    "customerId": "user_12345",
    "customerAttributes": {
      "displayName": "John Doe",
      "email": "john@example.com",
      "mobile": "+1234567890"
    }
  }'

{
  "customerId": "user_12345",
  "displayName": "John Doe",
  "email": "john@example.com",
  "mobile": "+1234567890",
  "createdAt": "2024-01-15T10:30:00Z"
}

​
Required Fields

At minimum, you must provide:
  • customerId - A unique identifier that persists across the customer’s lifetime
  • email OR mobile - At least one contact method (required for channel merging)
Choose a Persistent Customer IDThe customerId should be a permanent identifier that never changes. Using email or mobile number as the customerId is not recommended, as customers may change these values. Instead, use a database ID or UUID that remains constant.

​
Updating Customer Profiles

The same API endpoint is used for updates. If a customer with the same customerId already exists, the profile will be updated: 
curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'TransactionKey: YOUR_TRANSACTION_KEY' \
  -d '{
    "customerId": "user_12345",
    "customerAttributes": {
      "displayName": "John Doe Updated",
      "email": "john.newemail@example.com",
      "custom": {
        "preferred_category": "Electronics",
        "membership_tier": "Gold"
      }
    }
  }'

​
Customer Attributes

You can enrich customer profiles with additional attributes:

​
Standard Attributes

  • displayName - Customer’s display name
  • firstName - First name
  • lastName - Last name
  • email - Email address
  • mobile - Mobile number
  • gender - Gender (M/F/Other)
  • dateOfBirth - Date of birth (YYYY-MM-DD)
  • joinDate - Customer join date (YYYY-MM-DD)

​
Custom Attributes

Use the custom object to store business-specific data: 
{
  "customerId": "user_12345",
  "customerAttributes": {
    "displayName": "John Doe",
    "email": "john@example.com",
    "custom": {
      "preferred_category": "Electronics",
      "subscription_type": "Premium",
      "loyalty_tier": "Gold"
    }
  }
}

​
Implementation Best Practices

1

Create Profile on Signup

Create the customer profile immediately when a user signs up or logs in for the first time
2

Update Profile on Changes

Update the profile whenever customer information changes (email, preferences, etc.)
3

Use Server-Side Calls

Always make API calls from your backend server, never expose API keys in client-side code
4

Handle Errors Gracefully

Implement proper error handling for API failures and network issues

​
Channel Merging

If you use different customer IDs across channels (web, mobile app, POS), Gameball can merge profiles using email or mobile number. Include these fields in every customer creation/update request.
For more information, see the Channel Merging Guide.

​
Next Steps