Gameball REST API

{
  "openapi": "3.1.0",
  "info": {
    "title": "Gameball API",
    "description": "Gameball REST API v4.0 - Complete API reference for integrating loyalty, gamification, and customer engagement features",
    "version": "4.0.0"
  },
  "servers": [ { "url": "https://api.gameball.co" } ],
  "security": [ { "bearerAuth": [] } ],
  "paths": {
    "/api/v4.0/integrations/customers": {
      "post": {
        "summary": "Create Customer",
        "description": "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.",
        "operationId": "createCustomer",
        "security": [ { "apiKey": [] } ],
        "requestBody": {
          "description": "Customer payload containing identifiers and attributes.",
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpsertCustomerRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Customer created or updated successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UpsertCustomerResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v4.0/integrations/customers/{customerId}": {
      "get": {
        "summary": "Get Customer",
        "description": "Retrieve essential customer information from Gameball using a unique customerId. Returns general customer info (no personal data) with the public key.",
        "operationId": "getCustomer",
        "security": [{ "apiKey": [] }],
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Unique identifier for the customer"
          }
        ],
        "responses": {
          "200": {
            "description": "Customer found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CustomerResponse" }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete Customer",
        "description": "Remove a customer profile and associated data from the system.",
        "operationId": "deleteCustomer",
        "security": [{ "apiKey": [], "secretKey": [] }],
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Unique identifier for the customer"
          }
        ],
        "responses": {
          "200": { "description": "Customer deleted successfully" }
        }
      }
    },
    "/api/v4.0/integrations/customers/{customerId}/details": {
      "get": {
        "summary": "Get Customer Details",
        "description": "Retrieve comprehensive customer information including personally identifiable information (PII).",
        "operationId": "getCustomerDetails",
        "security": [{ "apiKey": [], "secretKey": [] }],
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Unique identifier for the customer"
          }
        ],
        "responses": {
          "200": {
            "description": "Customer details found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CustomerDetailsResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v4.0/integrations/customers/{customerId}/activate": {
      "put": {
        "summary": "Update Customer Activation",
        "description": "Set a customer's loyalty program participation state (active/inactive). This mirrors the include/exclude toggle in the Gameball dashboard.\n\nThe endpoint is idempotent: opting out an already opted-out customer (or opting in an already opted-in customer) produces no side effects. `stateChanged` indicates whether the state actually changed.\n\nWhen a customer is opted out (`isActive: false`): no points are earned from events or purchases, no rewards or coupons are generated, and the customer is excluded from all campaign eligibility. Prior activity is not undone.\n\n**Security:** Requires `apiKey` header. `secretKey` is required on v4.1; on v4.0 required when High Security Mode is enabled.\n\n**Requires an existing customer.** Unknown customers return `404 Not Found`.",
        "operationId": "updateCustomerActivation",
        "tags": ["Customers"],
        "security": [{ "apiKey": [], "secretKey": [] }],
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "maxLength": 100 },
            "description": "The customer's unique external identifier in your system.",
            "example": "cust-12345"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["isActive"],
                "properties": {
                  "isActive": {
                    "type": "boolean",
                    "description": "Set to `true` to opt the customer in (Include); set to `false` to opt the customer out (Exclude).",
                    "example": false
                  }
                }
              },
              "examples": {
                "optOut": {
                  "summary": "Opt customer out",
                  "value": { "isActive": false }
                },
                "optIn": {
                  "summary": "Opt customer in",
                  "value": { "isActive": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Customer activation state updated (or already in the requested state)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "customerId": {
                      "type": "string",
                      "description": "Echo of the customer ID from the request.",
                      "example": "cust-12345"
                    },
                    "isActive": {
                      "type": "boolean",
                      "description": "The customer's activation state after this request.",
                      "example": false
                    },
                    "stateChanged": {
                      "type": "boolean",
                      "description": "`true` if the state was different before this request and changed as a result; `false` if the customer was already in the target state (idempotent no-op).",
                      "example": true
                    }
                  }
                },
                "examples": {
                  "changed": {
                    "summary": "State changed",
                    "value": {
                      "customerId": "cust-12345",
                      "isActive": false,
                      "stateChanged": true
                    }
                  },
                  "idempotent": {
                    "summary": "Already in target state",
                    "value": {
                      "customerId": "cust-12345",
                      "isActive": false,
                      "stateChanged": false
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid request payload (e.g. missing `isActive`), or a concurrent request for this customer is in progress."
          },
          "401": {
            "description": "Missing, invalid, or expired API key; or invalid secret key (when required)."
          },
          "404": {
            "description": "Customer does not exist in your Gameball account, or customer ID is malformed."
          }
        }
      }
    },
    "/api/v4.0/integrations/customers/{customerId}/coupons": {
      "get": {
        "summary": "Get Customer Coupons",
        "description": "Retrieve customer's available coupons with detailed information on each coupon's type, status, and usage.",
        "operationId": "getCustomerCoupons",
        "security": [{ "apiKey": [], "secretKey": [] }],
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Unique identifier for the customer"
          }
        ],
        "responses": {
          "200": {
            "description": "Customer coupons found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CustomerCouponsResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v4.0/integrations/customers/social-challenges": {
      "post": {
        "summary": "Achieve Social Campaign",
        "description": "Mark a social campaign as achieved for a customer and grant the configured reward from your backend. This is the server-to-server equivalent of the in-widget social action for Social Activities campaigns.",
        "operationId": "achieveSocialChallenge",
        "security": [{ "apiKey": [], "secretKey": [] }],
        "requestBody": {
          "description": "Social challenge achievement payload.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["customerId", "challengeId"],
                "properties": {
                  "customerId": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "The customer's unique ID in your system. The customer must already exist in Gameball.",
                    "example": "customer_123"
                  },
                  "challengeId": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "The ID of the Social Activities campaign to award.",
                    "example": 11664
                  },
                  "email": {
                    "type": "string",
                    "description": "Customer's email address. Helps identify the customer when channel merging is enabled.",
                    "example": "john.doe@example.com"
                  },
                  "mobile": {
                    "type": "string",
                    "description": "Customer's mobile number. Helps identify the customer when channel merging is enabled.",
                    "example": "+1234567890"
                  }
                }
              },
              "examples": {
                "sample": {
                  "summary": "Sample request",
                  "value": {
                    "customerId": "customer_123",
                    "challengeId": 11664
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Social challenge achievement accepted for processing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "customerId": {
                      "type": "string",
                      "description": "The customer ID from the request.",
                      "example": "customer_123"
                    },
                    "challengeId": {
                      "type": "integer",
                      "description": "The social campaign ID from the request.",
                      "example": 11664
                    },
                    "gameballStatus": {
                      "type": "string",
                      "description": "Present when the Gameball program is disabled. Omitted while Gameball is enabled."
                    },
                    "message": {
                      "type": "string",
                      "description": "Informational message when the Gameball program is disabled."
                    },
                    "learnMore": {
                      "type": "string",
                      "description": "Link to learn more when the Gameball program is disabled."
                    }
                  }
                },
                "examples": {
                  "accepted": {
                    "value": {
                      "customerId": "customer_123",
                      "challengeId": 11664
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (missing fields, duplicate submission, etc.)"
          },
          "401": {
            "description": "Missing or invalid secret key"
          },
          "404": {
            "description": "Customer does not exist"
          },
          "500": {
            "description": "Unexpected server error"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges' \\\n  -H 'Content-Type: application/json' \\\n  -H 'apikey: YOUR_API_KEY' \\\n  -H 'secretkey: YOUR_SECRET_KEY' \\\n  -d '{\"customerId\":\"customer_123\",\"challengeId\":11664}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "await fetch('https://api.gameball.co/api/v4.0/integrations/customers/social-challenges', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    apikey: 'YOUR_API_KEY',\n    secretkey: 'YOUR_SECRET_KEY'\n  },\n  body: JSON.stringify({ customerId: 'customer_123', challengeId: 11664 })\n});"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nrequests.post(\n  'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges',\n  json={'customerId': 'customer_123', 'challengeId': 11664},\n  headers={'apikey': 'YOUR_API_KEY', 'secretkey': 'YOUR_SECRET_KEY', 'Content-Type': 'application/json'}\n)"
          },
          {
            "lang": "csharp",
            "label": "C#",
            "source": "using System.Net.Http;\nusing System.Text;\n\nvar client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar content = new StringContent(\"{\\\"customerId\\\":\\\"customer_123\\\",\\\"challengeId\\\":11664}\", Encoding.UTF8, \"application/json\");\nvar response = await client.PostAsync(\"https://api.gameball.co/api/v4.0/integrations/customers/social-challenges\", content);\nresponse.EnsureSuccessStatusCode();"
          }
        ]
      }
    },
    "/api/v4.0/integrations/customers/{customerId}/hash": {
      "get": {
        "summary": "Get Customer Hash",
        "description": "Generate a hash for an existing customer based on their unique customerId.",
        "operationId": "getCustomerHash",
        "security": [{ "apiKey": [], "secretKey": [] }],
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Unique identifier for the customer"
          }
        ],
        "responses": {
          "200": {
            "description": "Customer hash generated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CustomerHashResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v4.0/integrations/referrals/validate": {
      "get": {
        "summary": "Validate Referrer Code",
        "description": "Validate whether a provided referral code is valid and eligible for use during customer signup.",
        "operationId": "validateReferrerCode",
        "security": [{ "apiKey": [] }],
        "parameters": [
          {
            "name": "referrerCode",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "The referral code to validate"
          },
          {
            "name": "forCustomerId",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Customer ID to prevent self-referral"
          }
        ],
        "responses": {
          "200": {
            "description": "Referral code validation result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ReferralValidationResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v4.0/integrations/payments": {
      "post": {
        "description": "The API call tracks new payments, specifically tailored for fintech solutions. It captures key payment details, ensuring accurate tracking of customer transactions.\n\nThis API triggers the **\"Payment Processed\"** event, allowing you to automate follow-up actions such as initiating workflows, sending notifications, or rewarding customers with badges.\n\nThe event includes all properties provided in the payload.",
        "security": [ { "apiKey": [], "secretKey": [] } ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["customerId", "paymentId", "paymentDate", "totalPaid"],
                "properties": {
                  "customerId": { 
                    "type": "string",
                    "description": "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.",
                    "example": "cust456"
                  },
                  "email": { 
                    "type": "string",
                    "description": "Customer's email address. This is required if your account uses email-based channel merging.",
                    "example": "john.doe@example.com"
                  },
                  "mobile": { 
                    "type": "string",
                    "description": "Customer's mobile number. This is required if your account uses mobile-based channel merging.",
                    "example": "+1234567890"
                  },
                  "paymentId": { 
                    "type": "string",
                    "description": "Unique identifier for the payment on your system.",
                    "example": "6253e03b"
                  },
                  "paymentDate": { 
                    "type": "string", 
                    "format": "date-time",
                    "description": "Timestamp of when the payment was occurred.",
                    "example": "2024-09-21T16:53:28.190Z"
                  },
                  "totalPaid": { 
                    "type": "number",
                    "description": "The actual amount paid by the customer for the payment, accounting for any discounts or coupons applied. Unlike totalAmount, which reflects the original cost of the payment, totalPaid represents the final amount the customer paid after all adjustments. This value is used for reward calculations in Gameball to determine the points or benefits earned from the payment. Example: A customer makes a bill payment for their electricity bill of $120, including taxes and processing fees. If a $20 coupon is applied, the totalPaid becomes $100, reflecting the discounted amount the customer paid.",
                    "example": 100
                  },
                  "totalAmount": { 
                    "type": "number",
                    "description": "The total cost of the payment, including all item prices, processing fees and taxes. This value does not account for any discounts or coupons applied and is not used for calculations in Gameball; it is solely saved as historical data linked to the payment. Must be a positive value. Example: A customer makes a bill payment for their electricity bill of $120, including taxes and processing fees. If a $20 coupon is applied, the totalAmount remains $120 as it represents the original cost of the payment before any discounts are applied.",
                    "example": 120
                  },
                  "totalDiscount": { 
                    "type": "number",
                    "description": "Total discount applied to the payment.",
                    "example": 20
                  },
                  "totalProcessingFees": { 
                    "type": "number",
                    "description": "Total processing fees associated with the payment.",
                    "example": 10
                  },
                  "totalTax": { 
                    "type": "number",
                    "description": "Total tax amount for the payment.",
                    "example": 10
                  },
                  "paymentDetails": {
                    "type": "array",
                    "description": "An array containing details about each element in the payment bill. If not provided, the calculation will only consider the total payment values.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "serviceId": { 
                          "type": "string",
                          "description": "Unique identifier for the service.",
                          "example": "s_1234"
                        },
                        "serviceName": { 
                          "type": "string",
                          "description": "Service title or name.",
                          "example": "Vodafone Topup"
                        },
                        "serviceProvider": { 
                          "type": "string",
                          "description": "Company or entity that provides the service being paid for. This could be a telecom operator, an electricity provider, a streaming platform, or any other service vendor.",
                          "example": "Vodafone"
                        },
                        "amount": { 
                          "type": "number",
                          "description": "The original amount of a single service before any tax or discount is applied. This reflects the cost of the service, not the total for multiple quantities in a payment.",
                          "example": 100
                        },
                        "tax": { 
                          "type": "number",
                          "description": "The total amount of taxes applied to the service. This amount must be positive and reflects the total taxes.",
                          "example": 10
                        },
                        "discount": { 
                          "type": "number",
                          "description": "The total discount applied to this service, expressed as a positive value. This amount should reflect the total discounts.",
                          "example": 20
                        },
                        "tags": { 
                          "type": "array", 
                          "items": { "type": "string" },
                          "description": "Tags associated with the service for categorization or promotional purposes.",
                          "example": ["Telecom", "Topup"]
                        },
                        "category": { 
                          "type": "array", 
                          "items": { "type": "string" },
                          "description": "Service category, such as Telecom top-up or electricity. It can include one or multiple categories. Example: [\"Telecom Top-up\", \"Internet Bill\", \"Streaming Subscription\"]",
                          "example": ["Telecom Topup"]
                        },
                        "extra": { 
                          "type": "object", 
                          "additionalProperties": true,
                          "description": "Key-value pairs containing any extra information about the service, such as size, color, or other custom attributes. The values must be of type string or number.",
                          "example": {}
                        }
                      }
                    }
                  },
                  "redemption": {
                    "type": "object",
                    "description": "Redemption details for the payment, including points held for redemption.",
                    "properties": {
                      "pointsHoldReference": { 
                        "type": "string",
                        "description": "Reference from the Hold Points API for redeeming held points. For more details on how hold references are generated and utilized, refer to the Transactions section.",
                        "example": "HOLD123"
                      },
                      "couponsLockReference": { 
                        "type": "string",
                        "description": "The lock reference for the coupon is a unique identifier used to \"lock\" a coupon for a specific customer or order. This prevents the coupon from being used by others or on multiple transactions. For more details on how to generate and use lock references, refer to the Coupons section. Example: If you lock a coupon for a specific transaction, the lockReference could look like \"lockReference\": \"abc123def456\".",
                        "example": "LOCK123"
                      },
                      "couponCodes": { 
                        "type": "array", 
                        "items": { "type": "string" },
                        "description": "A list of coupon codes that were applied to the payment. Each code in the array represents a different discount or promotional coupon used during the checkout process. Coupon codes must be locked before they can be used for redemption. Example: If a customer applied two coupon codes, one for a 10% discount and another for free fees, the couponCodes array might look like this: [\"DISCOUNT10\", \"FREEFEES2024\"]",
                        "example": ["DISCOUNT10"]
                      }
                    }
                  },
                  "extra": { 
                    "type": "object", 
                    "additionalProperties": true,
                    "description": "Key-value pairs containing any extra information about the payment. The values must be of type string or number. Example: The extra attribute can store additional details like the billing address and payment status. For instance, when a customer completes a payment, the billing address ensures accurate invoicing by including details like the company name and tax identification number. At the same time, the payment status helps track the transaction—whether it's \"Pending\" for deferred payments or \"Completed\" when successfully processed—ensuring smooth order management and financial compliance.",
                    "example": {
                      "billingAddress": "Jane Smith, Acme Corp, 456 Elm St, Springfield, IL 62704, USA, Tax ID: US987654321",
                      "paymentStatus": "Pending"
                    }
                  },
                  "merchant": {
                    "type": "object",
                    "description": "This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place.",
                    "properties": {
                      "uniqueId": { 
                        "type": "string",
                        "description": "Unique identifier for the merchant."
                      },
                      "name": { 
                        "type": "string",
                        "description": "Name of the merchant."
                      },
                      "branch": {
                        "type": "object",
                        "required": ["uniqueId"],
                        "properties": {
                          "uniqueId": { 
                            "type": "string",
                            "description": "Unique identifier for the branch where the payment took place."
                          },
                          "name": { 
                            "type": "string",
                            "description": "Name of the branch where the payment took place."
                          }
                        }
                      }
                    }
                  },
                  "guest": { 
                    "type": "boolean",
                    "description": "Indicates whether the customer is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default.",
                    "example": false
                  },
                  "channel": { 
                    "type": "string", 
                    "enum": ["mobile", "pos", "web", "callcenter"],
                    "description": "The channel through which the payment was placed helps track the origin of the payment, particularly useful for systems that support multiple sales or communication channels. By identifying the channel, you can gain valuable insights into customer behavior, optimize channel-specific strategies, and ensure efficient handling of payments across platforms. Possible values: mobile (The payment was placed through your mobile application), pos (The payment was placed in person using a Point of Sale system), web (The payment was placed through your website), callcenter (The payment was placed over the phone by contacting a customer service representative).",
                    "example": "web"
                  },
                  "cashbackConfigurations": {
                    "type": "object",
                    "description": "This object contains configurations related to the cashback settings.",
                    "properties": {
                      "returnWindow": { 
                        "type": "integer",
                        "description": "The number of days the cashback will stay in a pending state, typically aligning with the return window in e-commerce to account for potential order cancellations or refunds. The value should be between 0 and 7,300 days (20 years).",
                        "example": 7
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment tracked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "customerId": { 
                      "type": "string",
                      "description": "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.",
                      "example": "cust_123456789"
                    },
                    "redeemedPoints": { 
                      "type": "number",
                      "description": "Points redeemed by the customer for this payment, if applicable. Example: If a customer has accumulated 500 points and decides to redeem 100 points for a discount on their current payment, the redeemedPoints value for that transaction will be 100. This helps track how many points were used in the transactio

# --- truncated at 32 KB (420 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gameball/refs/heads/main/openapi/gameball-openapi.json