Achieve Social Campaign
Mark a social campaign as achieved for a customer and grant the configured reward from your backend.
POST
cURL
This API lets your backend mark a social campaign 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 campaign 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
If your Gameball program is currently disabled, the response also includes an informational
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.
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.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 campaign reward (points, coupon, etc.).
How It Works
- The request is accepted immediately (
202) — the points or reward are not granted synchronously in the same call. - Gameball schedules the achievement and processes it within a few minutes (a short, randomized delay).
- Duplicate protection: the same
customerId+challengeIdcannot be triggered again within a short window — a repeat call is rejected (see Errors). - Repeatability is respected: a customer only earns the campaign as many times as the campaign configuration allows (e.g., a one-time “Facebook Friend” campaign is granted once; subsequent attempts are ignored).
- 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.
- 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 HTTP202 Accepted.
gameballStatus, message, and learnMore block (consistent with other V4 endpoints). These fields are omitted while Gameball is enabled.
Errors
Error responses follow the standard V4 shape documented in Status and Error Codes.
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.
Body
application/json
Social challenge achievement payload.
Response
Social challenge achievement accepted for processing