> ## 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.
# Achieve Social Challenge
> Mark a social challenge as achieved for a customer and grant the configured reward from your backend.
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](/tutorials/experiences/more/omni-channel).
**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](/api-reference/customers/management/create-customer) 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](#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`**.
```json theme={null}
{
"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
| HTTP | Code | Message (example) | Meaning |
| ----- | ---- | ----------------------------------------- | ---------------------------------------------------------------------------- |
| `400` | 3000 | `customer id is missing` | `customerId` was not provided. |
| `400` | 3000 | `rewards campaign handle is missing` | `challengeId` was not provided. |
| `400` | 4000 | `can't send this action multiple times` | The same customer + challenge was already submitted within the dedup window. |
| `401` | 1006 | `your request is missing the secret key.` | Missing or invalid secret key. |
| `404` | 4004 | `customer does not exist` | No customer with that `customerId` was found. |
| `500` | — | generic error | Unexpected server error. |
Error responses follow the standard V4 shape documented in [Status and Error Codes](/api-reference/overview/status-error-codes).
```json theme={null}
{
"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.
## OpenAPI
````yaml POST /api/v4.0/integrations/customers/social-challenges
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/social-challenges:
post:
summary: Achieve Social Challenge
description: >-
Mark a social challenge 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
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 challenge 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
security:
- apiKey: []
secretKey: []
x-codeSamples:
- lang: curl
label: cURL
source: >-
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}'
- lang: javascript
label: JavaScript
source: >-
await
fetch('https://api.gameball.co/api/v4.0/integrations/customers/social-challenges',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
apikey: 'YOUR_API_KEY',
secretkey: 'YOUR_SECRET_KEY'
},
body: JSON.stringify({ customerId: 'customer_123', challengeId: 11664 })
});
- lang: python
label: Python
source: |-
import requests
requests.post(
'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges',
json={'customerId': 'customer_123', 'challengeId': 11664},
headers={'apikey': 'YOUR_API_KEY', 'secretkey': 'YOUR_SECRET_KEY', 'Content-Type': 'application/json'}
)
- lang: csharp
label: C#
source: >-
using System.Net.Http;
using System.Text;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY");
client.DefaultRequestHeaders.Add("secretkey", "YOUR_SECRET_KEY");
var content = new
StringContent("{\"customerId\":\"customer_123\",\"challengeId\":11664}",
Encoding.UTF8, "application/json");
var response = await
client.PostAsync("https://api.gameball.co/api/v4.0/integrations/customers/social-challenges",
content);
response.EnsureSuccessStatusCode();
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
in: header
name: apikey
secretKey:
type: apiKey
in: header
name: secretkey
````