Skip to main content
POST
/
api
/
v4.0
/
integrations
/
customers
/
social-challenges
cURL
curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges' \
  -H 'Content-Type: application/json' \
  -H 'apikey: YOUR_API_KEY' \
  -H 'secretkey: YOUR_SECRET_KEY' \
  -d '{"customerId":"customer_123","challengeId":11664}'
{
  "customerId": "customer_123",
  "challengeId": 11664
}
This API lets your backend mark a social challenge as achieved for one of your customers — for example, awarding the “Follow us on Facebook” or “Share on X” reward after your system has confirmed the social action. It is the server-to-server (V4 Integrations) equivalent of the in-widget social action. Previously, a social challenge could only be completed from the Gameball widget in the browser; this endpoint lets you trigger it from your own server when you verify the social action yourself. This endpoint is available on v4.0 and v4.1.
Security: Requires apikey and secretkey headers. This is a sensitive, points-awarding operation.
Channel Merging Available
If your system uses different customer IDs across multiple channels (e.g., online and offline), include the customer’s mobile number or email (based on your merging configuration) to help Gameball identify the correct profile.For more information, see the Omni-Channel Handling Guide.
Asynchronous processing: A successful response (202 Accepted) means the request was accepted, not that the reward was granted. Gameball schedules the achievement and processes it within a few minutes. The configured reward is applied shortly after, and an activity is recorded on the customer’s profile.
Customer must exist first: Create the customer via the Create/Update Customer API before calling this endpoint. This API does not create customers.
Use this endpoint only for campaigns of type Social Activities. Other campaign types are not affected.

​
When to Use

  • A customer performs a social action that you verify on your side (followed a page, shared a link, joined a group, etc.).
  • You want Gameball to grant that customer the configured social-challenge reward (points, coupon, etc.).

​
How It Works

  1. The request is accepted immediately (202) — the points or reward are not granted synchronously in the same call.
  2. Gameball schedules the achievement and processes it within a few minutes (a short, randomized delay).
  3. Duplicate protection: the same customerId + challengeId cannot be triggered again within a short window — a repeat call is rejected (see Errors).
  4. Repeatability is respected: a customer only earns the challenge as many times as the campaign configuration allows (e.g., a one-time “Facebook Friend” challenge is granted once; subsequent attempts are ignored).
  5. Eligibility still applies: the customer must exist and be eligible for the campaign (audience, targeting, active dates, etc.). If the campaign is not achievable for that customer, no reward is granted.
  6. Reward depends on the campaign: the customer receives whatever that social campaign is configured to give. If the campaign has no points configured, the achievement is recorded but no points are added.

​
Response

On success, the endpoint returns HTTP 202 Accepted. 
{
  "customerId": "customer_123",
  "challengeId": 11664
}
If your Gameball program is currently disabled, the response also includes an informational gameballStatus, message, and learnMore block (consistent with other V4 endpoints). These fields are omitted while Gameball is enabled.

​
Errors

HTTPCodeMessage (example)Meaning
4003000customer id is missingcustomerId was not provided.
4003000rewards campaign handle is missingchallengeId was not provided.
4004000can't send this action multiple timesThe same customer + challenge was already submitted within the dedup window.
4011006your request is missing the secret key.Missing or invalid secret key.
4044004customer does not existNo customer with that customerId was found.
500—generic errorUnexpected server error.
Error responses follow the standard V4 shape documented in Status and Error Codes. 
{
  "code": 4004,
  "type": "GENERAL_ERROR",
  "message": "customer does not exist",
  "documentationUrl": "https://docs.gameball.co/api-reference/customers/management/achieve-social-challenge",
  "requestId": "…"
}

​
Limitations

  • Asynchronous: success means “accepted,” not “rewarded.” If a flow needs immediate confirmation of points, this endpoint is not the right fit.
  • Idempotency window: the short dedup window prevents accidental double submissions; it is not a permanent idempotency key.
  • Reward visibility: the resulting reward and activity appear on the customer’s profile and activity log in the dashboard once processed.

Authorizations

​
apikey
string
header
required
​
secretkey
string
header
required

Body

application/json

Social challenge achievement payload.

​
customerId
string
required

The customer's unique ID in your system. The customer must already exist in Gameball.

Maximum string length: 100
Example:

"customer_123"

​
challengeId
integer
required

The ID of the Social Activities campaign to award.

Required range: x >= 1
Example:

11664

​
email
string

Customer's email address. Helps identify the customer when channel merging is enabled.

Example:

"john.doe@example.com"

​
mobile
string

Customer's mobile number. Helps identify the customer when channel merging is enabled.

Example:

"+1234567890"

Response

Social challenge achievement accepted for processing

​
customerId
string

The customer ID from the request.

Example:

"customer_123"

​
challengeId
integer

The social challenge campaign ID from the request.

Example:

11664

​
gameballStatus
string

Present when the Gameball program is disabled. Omitted while Gameball is enabled.

​
message
string

Informational message when the Gameball program is disabled.

​
learnMore
string

Link to learn more when the Gameball program is disabled.