> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Create/Update Customer
> Create or update a customer profile in Gameball using a unique customerId.
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.
**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 [Omni-Channel Handling Guide](/tutorials/experiences/more/omni-channel).
## OpenAPI
````yaml POST /api/v4.0/integrations/customers
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
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'
security:
- apiKey: []
components:
schemas:
UpsertCustomerRequest:
type: object
required:
- customerId
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.
email:
type: string
description: >-
Customer's email address. Required if your account uses email-based
channel merging.
mobile:
type: string
description: >-
Customer's mobile number. Required if your account uses mobile-based
channel merging.
deviceToken:
type: string
description: Token used to identify the device.
osType:
type: string
description: Operating system type of the device.
customerAttributes:
type: object
description: >-
Additional customer-specific attributes. Includes attributes such as
the customer's name, contact details, and purchase history.
properties:
displayName:
type: string
description: Display name for the customer.
firstName:
type: string
description: Customer's first name.
lastName:
type: string
description: Customer's last name.
email:
type: string
description: Customer's email address.
gender:
type: string
description: Customer's gender.
mobile:
type: string
description: Customer's mobile number.
dateOfBirth:
type: string
description: Customer's date of birth.
joinDate:
type: string
description: Date the customer joined.
country:
type: string
description: Customer's country.
city:
type: string
description: Customer's city.
zip:
type: string
description: Customer's postal code.
preferredLanguage:
type: string
description: >-
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.
source:
type: string
description: Source of the customer registration.
utms:
type: array
description: List of UTM attributes associated with the customer.
devices:
type: array
description: List of devices associated with the customer.
paymentMethods:
type: array
description: >-
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.
totalSpent:
type: number
description: Total amount spent by the customer.
lastOrderDate:
type: string
description: Date of the last order placed by the customer.
totalOrders:
type: integer
description: Total number of orders placed by the customer.
avgOrderAmount:
type: number
description: Average amount spent per order by this customer.
channel:
type: string
description: >-
Indicates the channel through which the customer was acquired or
engaged. This is especially useful for systems that support
multiple channels to track customer origin and interactions.
Understanding the acquisition or engagement channel helps in
tailoring marketing strategies, optimizing communication, and
analyzing customer preferences.
enum:
- mobile
- pos
- web
- callcenter
custom:
type: object
additionalProperties: true
description: >-
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.
referrerCode:
type: string
description: >-
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:
type: boolean
description: >-
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.
UpsertCustomerResponse:
type: object
properties:
gameballId:
type: number
description: >-
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.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
in: header
name: apikey
````