Introduction
Welcome to the Social Scavenger API v1! You can use our API to interact with the Social Scavenger Platform without using one of our user experiences.
You can use any programming language with the Social Scavenger Platform. We provide examples you can run in your operating system shell or terminal, but feel free to use your favourite programming language and http library to build on top of our Platform.
If you're using a Web browser, you'll need to use the XMLHttpRequest object - a standard in the JavaScript Object model. The open() method on the object takes the HTTP Method as an argument including GET, PATCH, POST, PUT and DELETE, as specified by RFC 2616.
HTTP API Authentication
Social Scavenger uses email and password over a secure connection to allow access to the HTTP API. You can register a new account at our platform portal.
Once you have an account, you have two different mechanisms to authenticate each API call.
Credentials as Parameters
To check your account exists, use the verify API endpoint:
curl "https://app.socialscavenger.com/v1/users/verify.json?email=EMAIL" \
-H "X-Whitelabel: ss" \
-i
A verify request will return a JSON payload similar to below, if the account exists:
{
"id": 14096,
"email": "paul@socialscavenger.com",
"name": "Anonymous"
}
To check your account authorizes correctly using your credentials, make a request to the signin API endpoint:
curl "https://app.socialscavenger.com/v1/users/signin.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"email": "EMAIL", "password": "PASSWORD"}'
A successful signin request will return a JSON payload like:
{
"id": 37239,
"email": "s3@s3.com",
"name": "Anonymous"
}
Make sure to replace
PASSWORD
with your values. Always make your request using https to ensure your credentials are secure.
As you'll be making every call via a secure HTTPS connection, you may attach your credentials to each API call and they will be safe in transit.
Using this mechanism simply include user_id
, user_type
and password
to each GET
,POST
,PATCH
,PUT
or DELETE
HTTP request.
This is the simplest and fastest solution as it does not require generation of an additional token and does not have to deal with token expiry. Although it is simple and fast, it is not the preferred method; using tokens is preferred.
Consumed by Player
and Builder
apps.
HTTP Request Parameters
GET
using query string ?user_id=EMAIL&user_type=email&password=PASSWORD
POST
using JSON '{"user_id": "EMAIL", "user_type": "email", "password": "PASSWORD"}'
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
user_id | nil | Authentication | required |
user_type | nil | Authentication | required |
password | nil | Authentication | required |
Response Codes
When evaluating the verify and signin endpoints:
Code | Meaning |
---|---|
200 | The user exists or can be authenticated. |
401 | Unauthorized. |
404 | The user is not found. |
Related Events
Source | Comment |
---|---|
ss.user.verify | Emitted if a user is verified. |
ss.user.signin | Emitted if a user is successfully signed in. |
JWT as Header
To generate a JWT token use the authenticate method:
curl "https://app.socialscavenger.com/v1/users/authenticate.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"email": "EMAIL", "password": "PASSWORD"}'
An authenticate request will return a JSON payload like:
{
"lifespan": 60,
"token": "eyJhbGc...d3-xXm6QTozgQM",
"refresh_token": "XXX"
}
You can now use the token value in subsequent API calls, passing it in the Authorization header, until the lifespan (in minutes) elapses.
curl "https://app.socialscavenger.com/v1/users/list.json?code=UNLOCKCODE" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
An authenticate request will return a JSON payload like:
{
"id": 7018,
"users": [{
"id": 10754,
"email": "shaun.cowles@gmail.com",
"name": "Anonymous"
}, {
"id": 14096,
"email": "paul@socialscavenger.com",
"name": "Anonymous"
}]
}
Make sure to replace
TOKEN
with your value. Always make your request using https to ensure your credentials are secure.You can validate a token independently via:
curl "https://app.socialscavenger.com/v1/users/validate.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
A validate request will return a JSON payload like:
{
"id": 14096,
"email": "name@domain.com",
"name": "Anonymous"
}
Using this approach, you will first generate a JWT token, then attach the token you receive to every subsequent API call. If passing a token, you do not need to include your account credentials with each and every call to the API.
Each JWT token will be valid for a short period of time. If delegating responsibilities, this may be your preferred method as it limits exposure to your actual account credentials.
Consumed by Player
and Builder
apps.
HTTP Request Header
Authorization: 'Bearer TOKEN'
Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
token | nil | Authentication | required |
Use the HTTP API to read and write to the Social Scavenger platform on demand. The HTTP API is the way you mutate things on the Social Scavenger platform programmatically.
Response Codes
When evaluating the authenticate endpoint:
Code | Meaning |
---|---|
200 | Token and lifespan returned. |
401 | Unauthorized. |
Related Events
Source | Comment |
---|---|
ss.user.verify | Emitted if a token is validated. |
ss.user.signin | Emitted if a token is granted. |
Refreshing a JWT Token
To refresh a JWT token use the refresh method:
curl "https://app.socialscavenger.com/v1/users/refresh.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"refresh_token": "REFRESH_TOKEN"}' \
-i
An authenticate request will return a JSON payload like:
{
"lifespan": 60,
"token": "eyJhbGc...d3-xXm6QTozgQM",
"refresh_token": "XXX"
}
JWT tokens expire after an hour. The refresh token can be used one time only for up to 1 day to get a new JWT token. In this way, the refresh token is valid for a much longer period.
Consumed by Player
and Builder
apps.
Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
refresh_token | nil | A refresh token can be exchanged once for a new token and refresh_token. | required |
Response Codes
When evaluating the authenticate endpoint:
Code | Meaning |
---|---|
200 | Token, refresh_token and lifespan returned. |
401 | Unauthorized. |
Related Events
Source | Comment |
---|---|
ss.user.signin | Emitted if a token is granted. |
Websocket API Authentication
To authenticate and listen for events, use this sample python script:
#!/usr/bin/env python
import asyncio
import websockets
import json
uri = "wss://ws.socialscavenger.com?email={}&password={}&whitelabel={}&subscriptions={}".format("EMAIL", "PASSWORD", "ss", "SCOPE")
async def wsrun(uri):
async with websockets.connect(uri) as websocket:
while True:
print(await websocket.recv())
asyncio.get_event_loop().run_until_complete(wsrun(uri))
You may also connect using a personal unlock code instead of a password:
uri = "wss://ws.socialscavenger.com?email={}&password={}&whitelabel={}&subscriptions={}".format("EMAIL", "PERSONAL_UNLOCK_CODE", "ss", "SCOPE")
You may also connect using a JWT obtained from the HTTP API:
uri = "wss://ws.socialscavenger.com?token={}&whitelabel={}&subscriptions={}".format("TOKEN", "ss", "SCOPE")
Make sure to replace
PASSWORD
,PERSONAL_UNLOCK_CODE
,TOKEN
andSCOPE
with your values. Always make your request using wss to ensure your credentials are secure.
Social Scavenger uses email and password over a Websocket secure connection to allow access to the API. You can register a new account at our platform portal.
Social Scavenger will only send you messages for system notifications and events occurring in games you are part of.
Set your scope appropriately:
- "ss," subscribes you to all events.
- "ss.reward," subscribes you to all the reward events
- "ss.reward.update," subscribes you just to the reward update events
- "ss.reward.update,ss.answer.flag," subscribes you to reward update and answer flag events
The more targeted your scope, the faster you will receive events. You are incentivized by design to keep your scope as small as possible.
Use the Websocket API to listen to the Social Scavenger platform for events happening in real-time. The Websocket API is read-only and does not allow you to mutate things on the Social Scavenger platform - for that you will need to use the HTTP API.
Consumed by Player
and Builder
apps.
Response Codes
Code | Meaning |
---|---|
200 | Authorized and the connection is established. |
401 | Unauthorized. |
Webhooks
If you want to quickly test the webhook system you can use a tool like https://webhook.site/
Want to receive events and then move them elsewhere? Try Zapier
The Social Scavenger platform can send real-time game events to your own server and application via HTTPS POST. Game coordinators and administrators, as well as system super administrators, can configure a game with a single URL (the game.webhook attribute) to receive events.
URLs must start with https://
Your application should be ready to receive POST requests and return a 2XX http status code if the JSON data is successfully received.
You can use the same webhook URL for multiple games.
Achievements
Create Game Level Reward
curl "https://app.socialscavenger.com/v1/achievements.json" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}'
The above command returns JSON structured like this:
{
"id": 1145,
"description": null,
"first": 0,
"points": 0,
"push": null,
"style": 1,
"title": "Untitled",
"trig": 1,
"photo_thumb": "https://ss-assets.socia...tos/thumb_691.jpg",
"photos": [{
"thumb": "https://ss-assets.socia...tos/thumb_691.jpg",
"original": "https://ss-assets.socia...tos/original_691.jpeg"
}],
"videos": []
}
This endpoint creates a new achievement (also used as a reward, or clue) for the game specified. You must be a game administrator, a system super administrator, or the game creator to use this API endpoint.
There are two levels of rewards. Challenge or task level, which are configured as part of tasks themselves, and game level, which are created using this endpoint.
When we talk about rewards on the system, we talk about their definition (challenge or game level) and then also the actual granting or awarding of the reward that is made to players. The rewards given out to players by the system can be discovered via Retreive Team with Players. Rewards are granted or awarded based on submissions the players make in a game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/achievements.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
201 | A reward has been created. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.reward.create | Emitted after a reward is created. |
Retrieve Game Level Rewards
curl "https://app.socialscavenger.com/v1/achievements.json?game_id=GAME_ID" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
The above command returns JSON structured like this:
{
"id": 785,
"achievements": [{
"id": 691,
"description": "",
"first": 0,
"points": 0,
"push": "",
"style": 1,
"title": "Test",
"trig": 1,
"assets": {
"photos": [{
"name": "thumb",
"url": null,
"width": 0,
"height": 0
}, {
"name": "standard",
"url": null,
"width": 0,
"height": 0
}]
}
}]
}
This endpoint retrieves a list of all rewards or achievements in a particular game as specified by the game unlock code or the game id. You must be a game administrator, a system super administrator, or the game creator to use this API endpoint. This is a list of reward definitions themselves, and only the game rewards. When a player is granted a reward, it can be retrieved via the Retrieve Team with Players endpoint.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/achievements.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | A list of rewards for the game are returned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a player in the game, or a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
Paginated Game Level Rewards
curl "https://app.socialscavenger.com/v1/achievements/game/GAME_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"page": PAGE, "per_page": PER_PAGE}' \
-i
The above command returns JSON structured like this:
{
"achievements": [
{
"id": 691,
"description": "",
"first": 0,
"points": 0,
"push": "",
"style": 1,
"title": "Test",
"trig": 1,
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 75,
"height": 75
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 1024,
"height": 768
}
]
}
}
],
"meta": {
"page": 1,
"pages": 1,
"per_page": 10,
"count": 2,
"lottery_groups": [
"Blur",
"Hats"
]
}
}
This endpoint will retrieve a paginated list of rewards for a game, ordered by time, starting with the latest first. This is a list of reward definitions themselves, and only the game rewards. When a player is granted a reward, it can be retrieved via the Retrieve Team with Players endpoint.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/achievements/game/GAME_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to list rewards for. | required |
page | 1 | Page of results you which to retrieve. | optional |
per_page | 25 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of rewards for the game are returned. |
401 | Unauthorized. |
404 | The game is not found. |
Update Game Level Reward
curl "https://app.socialscavenger.com/v1/achievements/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "style": STYLE}'
If the system was able to update the achievement you will get a 200 http status code in the response.
This endpoint updates a reward or achievement as specified by the achievement ID
. You must be a game administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/achievements/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
description | nil | The text description. | optional |
first | nil | A value of 0 gives the reward to everyone. Otherwise only the first N people will receive the reward. | optional |
points | 0 | Bonus points to award to the player upon achieving the reward. | optional |
push | nil | A message you want sent to every player upon achieving the reward. | optional |
style | 1 | A value of 1 means any submission. A value of 3 means the submission must be a photo challenge submission. 4=video,5=sticker photo,6=text,7=QR,8=trivia,9=multiple choice,10=AR Photo,11=AR Video,12=Background Photo,13=Background Video,14=Path | optional |
title | nil | The text title. | optional |
trig | nil | The player achieves this reward after accomplishing this many submissions of the configured style. | optional |
photo_media_uuid | nil | The uuid of the media uploaded directly to AWS S3. | optional |
photo_media_extension | nil | The file extension of the media asset uploaded directly to AWS S3. | optional |
unlock_by_task_ids | nil | The id numbers, and optionally specific answers, of the tasks that unlock this task. The format is id_1;a_1:a_2,id_2;a_3:a_4 For multiple choice and trivia tasks being referenced, if specific answers are not provided, all answers are accepted for unlocking purposes. | optional |
lottery | false | If set to 0 or false, the reward is to be given every time the criterion are met. If set to 1 or true, the reward is to be given out randomly, in a coin-toss manner with 50% odds or 1 in lottery_group.count if in a lottery_group with another reward, when the criterion are met. | optional |
lottery_group | nil | A group name for a set of rewards eg. "cards" or "monopoly". If a group contains more than 1 reward, the count of rewards in the group will be used in setting odds of allocation using the lottery feature. | optional |
lottery_min | 1 | Assuming this reward's trigger is fired by its criterion being met, if set to 0 or 1, the player will be eligible for, and possibly receive, this reward only. If set to N, the player will be elegible for, and possibly receive a minimum of N rewards from this reward group. | optional |
lottery_max | 1 | Assuming this reward's trigger is fired by its criterion being met, if set to 0 or 1, the player will be eligible for, and possibly receive, this reward only. If set to N, the player will be elegible for, and possibly receive a maximum of N rewards from this reward group. If this value exceeds the lottery_group.count, it will be interpreted as lottery_group.count | optional |
Response Codes
Code | Meaning |
---|---|
200 | The reward has been updated. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game or achievement is not found. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.reward.update | Emitted after a reward is updated. |
Delete Game Level Reward
curl "https://app.socialscavenger.com/v1/achievements/ID.json" \
-X DELETE \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}'
If the system was able to delete the achievement you will get a 200 http status code in the response.
This endpoint deletes a reward or achievement as specified by the achievement ID
. You must be a game administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/achievements/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | The reward has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game or achievement is not found. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.reward.delete | Emitted after a reward is deleted. |
Adjustments
An adjustment is an award or penalty registered against an answer or submission.
Answers have a set of adjustments attached to them.
Adjustments impact the leaderboard. Game coordinators and administrators can manage adjustments.
Create Adjustment
curl "https://app.socialscavenger.com/v1/adjustments.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "answer_id": ANSWER_ID, "comment": "COMMENT", "summary": "SUMMARY", "correct": CORRECT, "decremental": DECREMENTAL, "greatness": GREATNESS, "points": POINTS, "category": "CATEGORY"}' \
-i
The above command returns an HTTP status code.
This endpoint will add an adjustment. You must attach an adjustment to an answer.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/adjustments.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to attach the adjustment to. | required |
answer_id | nil | The id for the answer to which the adjustment applies. | required |
comment | nil | The comment for the players. | optional |
summary | nil | A recap of reasoning for the adjustment. | optional |
correct | 0 | The answer is either 0 (incorrect) or 1 (correct) | optional |
decremental | 0 | The points are added (0) or subtracted (1) on the leaderboard. Set decremental to be 1 to change an award to a penalty. | optional |
greatness | 0 | A score between 1 and 100 for the greatness of the answer. | optional |
points | 0 | The number of points to be added or subtracted with this adjustment. | optional |
category | judgement | The type of adjustment. Only the most recent adjustment for the category will apply to the leaderboard. | optional |
Response Codes
Code | Meaning |
---|---|
201 | An adjustment has been created and added to the game. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
404 | The game or answer are not found. |
Related Events
Source | Comment |
---|---|
ss.adjustment.create | Emitted after an adjustment is created. |
Delete Adjustment
curl "https://app.socialscavenger.com/v1/adjustments/ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
If the system was able to delete the adjustment you will get a 200 http status code in the response.
This endpoint deletes an adjustment as specified by the adjustment ID
. You must be a game coordinator or administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/adjustments/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id for the adjustment. | required |
game_id | nil | The id for the game you wish to attach the adjustment to. | required |
Response Codes
Code | Meaning |
---|---|
200 | The adjustment has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.adjustment.delete | Emitted after an adjustment is deleted. |
Retrieve Adjustments
curl "https://app.socialscavenger.com/v1/adjustments.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID, "answer_id": ANSWER_ID}' \
-i
The above command returns JSON structured like this:
{
"adjustments": [
{
"answer_id": 1,
"category": "judgement",
"comment": "Way to go! Not a bunt, but a single.",
"correct": true,
"created_at": "2024-10-04T05:56:58Z",
"decremental": false,
"game_id": 1,
"greatness": 55,
"id": 2,
"impacts_leaderboard": false,
"judge_id": null,
"points": 5,
"summary": "The photo is of a single fig. The photo is average.",
"task_id": 263712,
"team_id": 103679,
"updated_at": "2024-10-04T05:56:58Z"
}
],
"game": {
"id": 1
}
}
This endpoint will list the adjustments for the answer.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/adjustments.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game the adjustments are attached to. | required |
answer_id | nil | The id for the answer for which the adjustments apply. | required |
Response Codes
Code | Meaning |
---|---|
200 | A list of adjustments for the answer are returned. |
401 | Unauthorized. |
404 | The game or answer is not found. |
Update Adjustment
curl "https://app.socialscavenger.com/v1/adjustments/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"points": POINTS, "game_id": GAME_ID}' \
-i
If the system was able to update the adjustment you will get a 200 http status code in the response.
This endpoint will update an existing adjustment. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/adjustments/ID.json
Query Parameters
See the list of attributes in the Create Adjustment section. Note, game_id is required.
Response Codes
Code | Meaning |
---|---|
200 | The adjustment has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The adjustment or game is not found. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.adjustment.update | Emitted after successfully updating the adjustment. |
Answers
Create Answer
curl "https://app.socialscavenger.com/v1/answers.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "task_id": TASK_ID}' \
-i
The above command returns JSON structured like this:
{
"answer": {
"id": 609550,
"created_at": "2021-10-14T22:50:20Z",
"approved_at": "2021-10-14T22:50:20Z",
"featured_at": null,
"rejected_at": null,
"type": 0,
"sub_type": 0,
"early": false,
"late": true,
"latitude": null,
"longitude": null,
"points": 0,
"trivia": null,
"comment": "",
"duration": null,
"assets": {
"photos": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-sticker",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-merged",
"url": null,
"width": 0,
"height": 0
}
],
"videos": [
{
"name": "standard",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
},
{
"name": "background-merged",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}
],
"audios": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
},
"team": {
"id": 48130,
"name": "XXX",
"submissions_count_for_task": 2
},
"task": {
"id": 73182,
"name": "Timer - Text",
"description": "Should have 10 seconds to do this text."
},
"game": {
"id": 785,
"name": "Sample Game - TRY ME!"
},
"user": {
"id": 14096,
"email": "paul@socialscavenger.com"
},
"media_processing": false
}
}
This endpoint will create a new answer or submission in a particular game as specified by the game unlock code or the game id.
Consumed by Player
apps. Response applies Personalization
.
HTTP Request
POST https://app.socialscavenger.com/v1/answers.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
os | nil | The operating system of the player. iOS, Android or Other. | optional |
os_version | nil | The operating system version. eg. 4.11.0 | optional |
app_version | nil | The version of the player app making the submission. eg. 11.1 | optional |
created_at | nil | The seconds since epoch at the time of submission. As soon as a player submits, this timestamp should be taken and passed along without mutation despite background processing, retries etc. | required |
comment | nil | A text string or comment. | optional |
task_id | nil | The id of the task being completed. | required |
latitude | nil | The latitude of the player. | optional |
longitude | nil | The longitude of the player. | optional |
media_uuid | nil | The uuid of the media uploaded to s3. | optional |
media_extension | nil | The file extension for the media uploaded to s3. | optional |
Response Codes
Code | Meaning |
---|---|
201 | A submission has been successfully received and an answer has been created. |
401 | Unauthorized. |
404 | The game, team, or task is not found. |
409 | There is a conflict as we already have a submission with the same exact timestamp by the same player for the same task and game. |
422 | We were unable to persist or save your submission. |
Related Events
Source | Comment |
---|---|
ss.answer.create | Emitted after successfully storing the submission. |
ss.badge.create | Emitted if a new reward is granted to the player based on the submission. |
ss.badge.delete | Emitted if a reward is revoked for the player based on the submission. |
Retrieve Answer
curl "https://app.socialscavenger.com/v1/answers/ANSWER_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
If you request a json payload:
{
"answer": {
"id": 68114,
"created_at": "2016-04-11T06:05:14Z",
"approved_at": "2021-06-10T08:22:21Z",
"featured_at": null,
"rejected_at": null,
"type": 0,
"sub_type": 0,
"early": false,
"late": false,
"latitude": 49.1111,
"longitude": -123.1111,
"points": 8,
"trivia": "correct",
"comment": "Princess Bride...correct!",
"duration": null,
"assets": {
"photos": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-sticker",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-merged",
"url": null,
"width": 0,
"height": 0
}
],
"videos": [
{
"name": "standard",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
},
{
"name": "background-merged",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}
],
"audios": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
},
"team": {
"id": 13300,
"name": "William Dale"
},
"task": {
"id": 20115,
"name": "Trivia - Saul Berenson",
"description": "Question: HTML"
},
"user": {
"email": "name@domain.com"
},
"media_processing": false
}
}
This endpoint will retrieve a single answer in a particular game as specified by the game unlock code or the game id.
Consumed by Player
apps. Response applies Personalization
.
HTTP Request
GET https://app.socialscavenger.com/v1/answers/ANSWER_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
answer_id | nil | The submission id. | required |
game_id | nil | The game the submission is part of. | required |
code | nil | If the caller is not joined to the game, a game code must be provided. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The submission or answer. |
401 | Unauthorized. |
404 | The answer is not found or the game is not found or the game and answer do not belong together. |
Retrieve Answers for Game
curl "https://app.socialscavenger.com/v1/answers.json?code=UNLOCKCODE&user_id=EMAIL&user_type=email&password=PASSWORD" \
-H "X-Whitelabel: ss"
The above command returns JSON structured like this:
{
"id": 7018,
"answers": [{
"id": 567977,
"created_at": "2021-06-26T12:20:43Z",
"approved_at": null,
"featured_at": null,
"rejected_at": "2021-07-13T04:26:14Z",
"answer_type": 9,
"answer_subtype": 0,
"late": 1,
"latitude": 49.0,
"longitude": -123.0,
"points": 0,
"trivia": null,
"name": "",
"task_description": "I'm hiding where you'll never find me.",
"task_name": "Hanging Around",
"task_id": 166337,
"team_id": 66110,
"team_name": "Team 2",
"photo_url": "https://ss-assets.socialscavenger.com/images/....jpg",
"sticker_url": "https://ss-assets.socialscavenger.com/images/....png",
"mp4_url": null,
"webm_url": null,
"mp4a_url": null,
"game_id": 7018,
"game_name": "Name of Game",
"share_location": "show",
"duration": null,
"media_processing": false
}]
}
This endpoint retrieves a list of all submissions in a particular game as specified by the game unlock code or the game id.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/answers.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list submissions for. | requires code or game_id |
game_id | nil | The id for the game you wish to list submissions for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | A list of submissions for the game are returned. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Payload
Object | Attribute | Type | Comment |
---|---|---|---|
id | Integer | Game identification number | |
answer | id | Integer | Submission identification number |
Filtered Answers for Game
curl "https://app.socialscavenger.com/v1/answers/filter/GAME_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"per_page": PER_PAGE, "page": PAGE}' \
-i
The above command returns JSON structured like this:
{
"answers": [
{
"id": 603133,
"created_at": "2021-09-25T00:11:12Z",
"approved_at": null,
"featured_at": null,
"rejected_at": null,
"type": 0,
"sub_type": 0,
"early": false,
"late": false,
"latitude": null,
"longitude": null,
"points": 0,
"trivia": "incorrect",
"comment": "Another ...wrong!",
"duration": null,
"assets": {
"photos": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-sticker",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-merged",
"url": null,
"width": 0,
"height": 0
}
],
"videos": [
{
"name": "standard",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
},
{
"name": "background-merged",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}
],
"audios": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
},
"team": {
"id": 70526,
"name": "Team 835",
"submissions_count_for_task": 1
},
"task": {
"id": 121656,
"name": "MC with long answers",
"description": "Testing MC challenge with long answers"
},
"game": {
"id": 785,
"name": "Sample Game - TRY ME!"
},
"user": {
"id": 66653,
"email": "chat@domain.com"
},
"media_processing": false,
"reviewer": null,
"review_key": "1632528672"
}
],
"meta": {
"leaderboard": [
{
"game_id": 785,
"reel": "g_785_t_34391_s.mp4",
"team_id": 34391,
"tasks": 143,
"points": 1252,
"total_tasks": 158,
"total_teams": 170,
"points_place": 1,
"name": "Beacons 375",
"last_answer": false,
"imageURL": "https://ss....jpg",
"imageURLWidth": 75,
"imageURLHeight": 75,
"largeImageURL": "https://ss.....jpg",
"largeImageURLWidth": 576,
"largeImageURLHeight": 768,
"achievements": null,
"updated": "2021-09-15T01:51:04.000Z"
}
],
"page": 4615,
"pages": 4618,
"per_page": 1,
"count": 4618,
"filters": {
"task_id": null,
"team_id": null
}
}
}
This endpoint retrieves a raw list of all submissions in a particular game as specified by the game unlock code or the game id. The submissions can be filtered by team or task.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/answers/filter/GAME_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list submissions for. | requires code or game_id |
game_id | nil | The id for the game you wish to list submissions for. | requires code or game_id |
page | 1 | Page of results you which to retrieve. | optional |
per_page | 25 | Number of results per page. | optional |
task_id | nil | Limit the set to answers to the task with this id. | optional |
team_id | nil | Limit the set to answers by the team with this id. | optional |
style | alltime | Include the leaderboard of this style. One of daily, weekly or alltime. | optional |
metric | points | Include the leaderboard of this metric. One of points or completed. | optional |
aggregate | teams | Include the leaderboard of this aggregate. One of players, teams or groups. | optional |
type | nil | The type of challenge, 0 (Text), 1 (Photo), 2 (Video), 3 (Sticker + Photo), 4 (QR Scan), 5 (Trivia), 6 (Multiple Choice), 7 (Augmented Reality + Photo), 8 (Augmented Reality + Video), 9 (Background + Photo), 10 (Background + Video), 11 (Path) | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of submissions for the game are returned. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Paginated Answers for Team
curl "https://app.socialscavenger.com/v1/answers/team/TEAM_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "per_page": PER_PAGE, "token": PAGINATION_TOKEN}' \
-i
The above command returns JSON structured like this:
{
"pages": 8,
"per_page": 10,
"count": 84,
"featured": 7,
"token": 0,
"team": {
"id": 48130,
"name": "Paul",
"completed": 6,
"place": 7,
"points": 503
},
"game": {
"id": 785,
"tasks": 158,
"teams": 173,
"name": "Sample Game - TRY ME!"
},
"answers": [
{
"id": 600276,
"created_at": "2021-09-19T04:13:12Z",
"approved_at": null,
"featured_at": null,
"rejected_at": null,
"type": 0,
"sub_type": 0,
"early": false,
"late": false,
"latitude": null,
"longitude": null,
"points": 0,
"trivia": "incorrect",
"comment": "Answered...wrong!",
"duration": null,
"assets": {
"photos": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-sticker",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-merged",
"url": null,
"width": 0,
"height": 0
}
],
"videos": [
{
"name": "standard",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
},
{
"name": "background-merged",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}
],
"audios": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
},
"team": {
"id": 66070,
"name": "Jean-Luc Picard",
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 3456,
"height": 4608
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 3456,
"height": 4608
}
]
},
"submissions_count_for_task": 1
},
"task": {
"id": 145343,
"name": "Resize Me Test",
"description": "We HTML"
},
"game": {
"id": 785,
"name": "Sample Game - TRY ME!"
},
"user": {
"id": 62599,
"email": "user@domain.com"
},
"media_processing": false,
"likes": 0,
"liked": 0,
"comments": 0,
"commented": 0,
"percentage_completed": 12,
"place": 536
},
],
"achievements": {
"available": [
{
"id": 1145,
"description": null,
"first": 0,
"points": 0,
"push": null,
"style": 1,
"title": "Untitled",
"trig": 2,
"assets": {
"photos": [
{
"name": "thumb",
"url": null,
"width": 0,
"height": 0
},
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
}
},
{
"id": 691,
"description": "",
"first": 0,
"points": 0,
"push": "",
"style": 1,
"title": "Test",
"trig": 1,
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 75,
"height": 75
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 1024,
"height": 768
}
]
}
}
],
"granted": [
{
"id": 5438,
"user_id": 14096,
"achievement_id": 691,
"game_id": 785,
"answer_id": 384575,
"created_at": "2020-04-22T04:01:41Z",
"updated_at": "2020-04-22T04:01:41Z"
}
]
}
}
This endpoint will retrieve a paginated list of submissions/answers for a team, ordered by time, starting with the latest first.
Consumed by Player
and Builder
apps. Response applies Personalization
.
HTTP Request
GET https://app.socialscavenger.com/v1/answers/team/TEAM_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list answers for. | requires code or game_id |
game_id | nil | The id for the game you wish to list answers for. | requires code or game_id |
team_id | nil | The id for the team you wish to list answers for. | required |
token | nil | The last answer id in the previous page is the pagination token. | optional |
per_page | 10 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of answers or submissions for the game and team are returned. |
401 | Unauthorized. |
404 | The game or team is not found. |
Paginated Answers for Task
curl "https://app.socialscavenger.com/v1/answers/task/TASK_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "per_page": PER_PAGE, "token": PAGINATION_TOKEN}' \
-i
The above command returns JSON structured like this:
{
"pages": 8,
"per_page": 10,
"count": 84,
"featured": 7,
"token": 0,
"team": {
"id": 48130,
"name": "Paul",
"completed": 6,
"place": 7,
"points": 503
},
"game": {
"id": 785,
"tasks": 158,
"teams": 173,
"name": "Sample Game - TRY ME!"
},
"answers": [
{
"id": 600276,
"created_at": "2021-09-19T04:13:12Z",
"approved_at": null,
"featured_at": null,
"rejected_at": null,
"type": 0,
"sub_type": 0,
"early": false,
"late": false,
"latitude": null,
"longitude": null,
"points": 0,
"trivia": "incorrect",
"comment": "Answered...wrong!",
"duration": null,
"assets": {
"photos": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-sticker",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-merged",
"url": null,
"width": 0,
"height": 0
}
],
"videos": [
{
"name": "standard",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
},
{
"name": "background-merged",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}
],
"audios": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
},
"team": {
"id": 66070,
"name": "Jean-Luc Picard",
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 3456,
"height": 4608
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 3456,
"height": 4608
}
]
},
"submissions_count_for_task": 1
},
"task": {
"id": 145343,
"name": "Resize Me Test",
"description": "We HTML"
},
"game": {
"id": 785,
"name": "Sample Game - TRY ME!"
},
"user": {
"id": 62599,
"email": "user@domain.com"
},
"media_processing": false,
"likes": 0,
"liked": 0,
"comments": 0,
"commented": 0,
"percentage_completed": 12,
"place": 536
},
],
"achievements": {
"available": [
{
"id": 1145,
"description": null,
"first": 0,
"points": 0,
"push": null,
"style": 1,
"title": "Untitled",
"trig": 2,
"assets": {
"photos": [
{
"name": "thumb",
"url": null,
"width": 0,
"height": 0
},
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
}
},
{
"id": 691,
"description": "",
"first": 0,
"points": 0,
"push": "",
"style": 1,
"title": "Test",
"trig": 1,
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 75,
"height": 75
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 1024,
"height": 768
}
]
}
}
],
"granted": [
{
"id": 5438,
"user_id": 14096,
"achievement_id": 691,
"game_id": 785,
"answer_id": 384575,
"created_at": "2020-04-22T04:01:41Z",
"updated_at": "2020-04-22T04:01:41Z"
}
]
}
}
This endpoint will retrieve a paginated list of submissions/answers for a task, ordered by time, starting with the latest first.
Consumed by Player
and Builder
apps. Response applies Personalization
.
HTTP Request
GET https://app.socialscavenger.com/v1/answers/task/TASK_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list answers for. | requires code or game_id |
game_id | nil | The id for the game you wish to list answers for. | requires code or game_id |
task_id | nil | The id for the task you wish to list answers for. | required |
token | nil | The last answer id in the previous page is the pagination token. | optional |
per_page | 10 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of answers or submissions for the game and task are returned. |
401 | Unauthorized. |
404 | The game or task is not found. |
Paginated Answers for Game
curl "https://app.socialscavenger.com/v1/answers/game/GAME_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"per_page": PER_PAGE, "token": PAGINATION_TOKEN}' \
-i
The above command returns JSON structured like this:
{
"pages": 8,
"per_page": 10,
"count": 84,
"featured": 7,
"token": 0,
"team": {
"id": 48130,
"name": "Paul",
"completed": 6,
"place": 7,
"points": 503
},
"game": {
"id": 785,
"tasks": 158,
"teams": 173,
"name": "Sample Game - TRY ME!"
},
"answers": [
{
"id": 600276,
"created_at": "2021-09-19T04:13:12Z",
"approved_at": null,
"featured_at": null,
"rejected_at": null,
"type": 0,
"sub_type": 0,
"early": false,
"late": false,
"latitude": null,
"longitude": null,
"points": 0,
"trivia": "incorrect",
"comment": "Answered...wrong!",
"duration": null,
"assets": {
"photos": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-sticker",
"url": null,
"width": 0,
"height": 0
},
{
"name": "background-merged",
"url": null,
"width": 0,
"height": 0
}
],
"videos": [
{
"name": "standard",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
},
{
"name": "background-merged",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}
],
"audios": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
},
"team": {
"id": 66070,
"name": "Jean-Luc Picard",
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 3456,
"height": 4608
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 3456,
"height": 4608
}
]
},
"submissions_count_for_task": 1
},
"task": {
"id": 145343,
"name": "Resize Me Test",
"description": "We HTML"
},
"game": {
"id": 785,
"name": "Sample Game - TRY ME!"
},
"user": {
"id": 62599,
"email": "user@domain.com"
},
"media_processing": false,
"likes": 0,
"liked": 0,
"comments": 0,
"commented": 0,
"percentage_completed": 12,
"place": 536
},
],
"achievements": {
"available": [
{
"id": 1145,
"description": null,
"first": 0,
"points": 0,
"push": null,
"style": 1,
"title": "Untitled",
"trig": 2,
"assets": {
"photos": [
{
"name": "thumb",
"url": null,
"width": 0,
"height": 0
},
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
}
},
{
"id": 691,
"description": "",
"first": 0,
"points": 0,
"push": "",
"style": 1,
"title": "Test",
"trig": 1,
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 75,
"height": 75
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 1024,
"height": 768
}
]
}
}
],
"granted": [
{
"id": 5438,
"user_id": 14096,
"achievement_id": 691,
"game_id": 785,
"answer_id": 384575,
"created_at": "2020-04-22T04:01:41Z",
"updated_at": "2020-04-22T04:01:41Z"
}
]
}
}
This endpoint will retrieve a paginated list of submissions/answers for a game, ordered by time, starting with the latest first.
Consumed by Player
and Builder
apps. Response applies Personalization
.
HTTP Request
GET https://app.socialscavenger.com/v1/answers/game/GAME_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list answers for. | requires code or game_id |
game_id | nil | The id for the game you wish to list answers for. | requires code or game_id |
token | nil | The last answer id in the previous page is the pagination token. | optional |
per_page | 10 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of answers or submissions for the game are returned. |
401 | Unauthorized. |
404 | The game is not found. |
Update Answer
Answers are immutable and cannot be updated as a general rule. Specific attributes may be altered using other endpoints documented below.
Delete Answer
Answers may be rejected, which will hide them from players, but cannot be deleted via API for legal archival purposes. If you must have a submission deleted in order to comply with a GDPR request-to-be-forgotten contact us.
Flag Answer
curl "https://app.socialscavenger.com/v1/answers/flag.json" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-d '{"id": ID, "comment":"COMMENT"}'
The above command returns JSON. See Retrieve Answer for a sample payload.
This endpoint will send a message to a moderator in order to flag a submission.
Consumed by Player
apps. Message applies Personalization
.
HTTP Request
PATCH https://app.socialscavenger.com/v1/answers/flag.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id number of the submission you are flagging. | required |
comment | nil | A comment you would like to append to the flag. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The submission has been flagged and an email has been sent to a moderator. |
404 | The answer is not found. |
Related Events
Source | Comment |
---|---|
ss.answer.flag | Emitted after successfully flagging the submission. |
Like Answer
curl "https://app.socialscavenger.com/v1/answers/like.json" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-d '{"id": ID, "user_id":"EMAIL", "user_type":"email", "password":"PASSWORD"}'
The above command returns JSON. See Retrieve Answer for a sample payload.
This endpoint will like the submission. If the submission is already liked, it will remain liked.
Consumed by Player
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/answers/like.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id number of the submission you are liking. | required |
Response Codes
Code | Meaning |
---|---|
200 | The answer is liked. |
401 | Unauthorized. |
404 | The answer is not found. |
Related Events
Source | Comment |
---|---|
ss.answer.like | Emitted after successfully liking the submission. |
Unlike Answer
curl "https://app.socialscavenger.com/v1/answers/unlike.json" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-d '{"id": ID, "user_id":"EMAIL", "user_type":"email", "password":"PASSWORD"}'
The above command returns JSON. See Retrieve Answer for a sample payload.
This endpoint will unlike (or remove a like from) the submission. If the submission is already unliked, it will remain unliked.
Consumed by Player
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/answers/unlike.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id number of the submission you are unliking. | required |
Response Codes
Code | Meaning |
---|---|
200 | The answer is not liked. |
401 | Unauthorized. |
404 | The answer is not found. |
Related Events
Source | Comment |
---|---|
ss.answer.unlike | Emitted after successfully unliking the submission. |
Regenerate Media for Answer
curl "https://app.socialscavenger.com/v1/answers/regenerate.json" \
-X PUT \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-d '{"id": ID, "user_id": "EMAIL", "user_type": "email", "password": "PASSWORD"}'
The above command returns a 200 or 404 HTTP response status code.
This endpoint will trigger the platform to regenerate any derivative medias from the original submission.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/answers/regenerate.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id number of the submission you are regenerating. | required |
Response Codes
Code | Meaning |
---|---|
200 | The media for the answer will be regenerated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The answer is not found. |
406 | The media for the answer cannot be regenerated. |
Accept Answer
curl "https://app.socialscavenger.com/v1/answers/accept/ID/REVIEW_KEY.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
The above command returns an HTTP status code.
curl "https://app.socialscavenger.com/v1/answers/accept/ID/REVIEW_KEY.json" \
-X PATCH \
-H "X-Whitelabel: ss"
The above command returns an HTTP status code.
This endpoint will mark a submission as accepted. It may be called from an email link, and so may be called via PATCH or GET to extend browser and email client compatibility. If you do not use the standard JWT or credentials based authentication, it will process the acceptance anonymously and messages will be sent from the Social Scavenger platform rather than a specific user.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/answers/accept/ANSWER_ID/REVIEW_KEY.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The answer or submission identifier. | required |
review_key | nil | A unique secret that is used instead of authentication. | required |
points | nil | Override the points granted by setting it to this value. | optional |
message | nil | Add an additional message to the chat and push notifications. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The answer or submission was approved. |
404 | The answer and/or the game the answer is part of, could not be found. |
Related Events
Source | Comment |
---|---|
ss.answer.accept | Emitted after successfully accepting the submission. |
Reject Answer
curl "https://app.socialscavenger.com/v1/answers/reject/ANSWER_ID/REVIEW_KEY.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
The above command returns an HTTP status code.
This endpoint will mark an answer or submission as rejected. Rejecting an answer also sets the points awarded to zero. Rejecting an answer may impact the rewards granted to the player, causing a reward to be revoked in some cases. It may be called from an email link, and so may be called via PATCH or GET to extend browser and email client compatibility. If you do not use the standard JWT or credentials based authentication, it will process the acceptance anonymously and messages will be sent from the Social Scavenger platform rather than a specific user.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/answers/reject/ANSWER_ID/REVIEW_KEY.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The answer or submission identifier. | required |
review_key | nil | A unique secret that is used instead of authentication. | required |
message | nil | Add an additional message to the chat and push notifications. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The answer or submission was rejected. |
404 | The answer and/or the game the answer is part of, could not be found. |
Related Events
Source | Comment |
---|---|
ss.answer.reject | Emitted after successfully rejecting the submission. |
Feature Answer
curl "https://app.socialscavenger.com/v1/answers/feature/ANSWER_ID/REVIEW_KEY.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
The above command returns an HTTP status code.
This endpoint will mark an answer or submission as featured. If the answer was previously rejected, it will now be accepted. Featuring does not impact the points allotted, so if the answer was previously rejected you may wish to accept it first, set a points value, and then feature it.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/answers/feature/ANSWER_ID/REVIEW_KEY.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The answer or submission identifier. | required |
review_key | nil | A unique secret that is used instead of authentication. | required |
Response Codes
Code | Meaning |
---|---|
200 | The answer or submission was featured. |
404 | The answer and/or the game the answer is part of, could not be found. |
Related Events
Source | Comment |
---|---|
ss.answer.feature | Emitted after successfully featuring the submission. |
Review Answer
curl "https://app.socialscavenger.com/v1/answers/review/ANSWER_ID/REVIEW_KEY.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"action": "reject"}' \
-i
The above command returns an HTTP status code.
This endpoint can be used to approve, reject or feature an answer silently. If you want to change the points granted for an answer, or reject an answer outright, without push and chat notifications, you may use this multipurpose endpoint.
HTTP Request
PATCH https://app.socialscavenger.com/v1/answers/review/ANSWER_ID/REVIEW_KEY.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The answer or submission identifier. | required |
review_key | nil | A unique secret that is used instead of authentication. | required |
action | approve | Valid actions are approve, reject or feature. | optional |
points | nil | Override the points granted by setting it to this value if performing an approve action. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The answer or submission was reviewed. |
404 | The answer and/or the game the answer is part of, could not be found. |
Related Events
Source | Comment |
---|---|
ss.answer.review | Emitted after successfully reviewing the submission. |
Share Answer
curl "https://app.socialscavenger.com/v1/answers/share/WHITELABEL/ANSWER_ID.html" \
-X GET \
-H "Content-Type: text/html" \
-i
If you request an html payload:
<html>
<head>
<meta property="og:url" content="https://builder.socialscavenger.com/answers/show/1/1" />
<meta property="og:title" content="Team 1 completed Hanging Around." />
<meta property="og:description" content="I'm hiding where you'll never find me. When you do, get a portrait mode photo of you balancing me on your head." />
<meta property="og:type" content="website" />
<meta property="og:image:alt" content="Comment shows up here" />
<meta property="og:image" content="https://ss-assets.socialscavenger.com/images/XXX.jpg" />
<meta property="og:image:width" content="3024" />
<meta property="og:image:height" content="4032" />
<script> location.href = 'https://builder.socialscavenger.com/answers/show/1/1'; </script>
</head>
</html>
This endpoint will retrieve an HTML page optimized for sharing. It presents meta tags to crawlers and redirects humans to the correct landing page.
Consumed by Player
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/answers/share/WHITELABEL/ANSWER_ID.html
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
answer_id | nil | The submission id. | required |
Response Codes
Code | Meaning |
---|---|
200 | The submission or answer. |
404 | The answer is not found or the game is not found. |
Chats
Create Message
curl "https://app.socialscavenger.com/v1/chats.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "message": "MESSAGE", "category": CATEGORY}' \
-i
The above command returns JSON structured like this:
{
"id": 752,
"user_id": 66408,
"game_id": 785,
"team_id": 70254,
"private_team_id": null,
"display_name": "Name",
"avatar_url": null,
"message": "Message!",
"created_at": "2021-08-29T17:17:35Z",
"category": 0,
"pagination_token": 1630257455
}
This endpoint creates a message in a game chat room.
Consumed by Player
and Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/chats.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The game id to which the message is being posted. | required |
private_team_id | nil | The team id to which the message is being limited to. | optional |
message | nil | The message to be displayed. | required |
category | nil | 0 if the message is from a player, 1 if the message is from a game administrator, 2 if the message is from the platform or system, 3 if the message is from a non player character. | required |
latitude | nil | The latitude of the player. | optional |
longitude | nil | The longitude of the player. | optional |
Response Codes
Code | Meaning |
---|---|
201 | Message created successfully. |
401 | Unauthorized. |
422 | Message was not able to be created. |
Related Events
Source | Comment |
---|---|
ss.chat.create | Emitted after successfully saving the message. |
Retrieve Messages
curl "https://app.socialscavenger.com/v1/chats.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "before": "PAGINATION_TOKEN", "page_size": PAGE_SIZE}' \
-i
The above command returns JSON structured like this:
{
"results": [{
"id": 323,
"user_id": 159,
"game_id": 785,
"team_id": 0,
"display_name": "Administrator",
"avatar_url": null,
"message": "Hi!",
"created_at": "2021-07-22T18:14:15Z",
"category": 2,
"pagination_token": 1626977655
}, {
"id": 322,
"user_id": 65004,
"game_id": 785,
"team_id": 68608,
"display_name": "Warren",
"avatar_url": null,
"message": "Jean Luc - second best captain ever",
"created_at": "2021-07-22T18:13:37Z",
"category": 0,
"pagination_token": 1626977617
}],
"meta": {
"count": 215,
"teams": 539,
"players": 698,
"bidirectional": 1
}
}
This endpoint lists all the chat messages for a game. It is capable of pagination. In the meta attribute, you will find count (message count), teams (teams count), players (player count) and bidirectional (whether or not players can send messages or if it is restricted only to administrators).
Consumed by Player
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/chats.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
before | nil | The pagination token of the last message in the last payload. | optional |
page_size | 10 | The page size you wish to receive in the payload. | optional |
game_id | nil | The id for the game you wish to list messages for. | required |
Response Codes
Code | Meaning |
---|---|
200 | List of messages returned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a player in the game, or a game coordinator, game administrator or system super administrator. |
404 | A list of messages could not be returned as the game was not found. |
Comments
Create Comment
curl "https://app.socialscavenger.com/v1/comments.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"comment": "That is too funny.", "answer_id": ANSWER_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will add a comment. You must attach a comment to an answer. A comment at minimum must have a non-empty value for the comment attribute.
Consumed by Player
and Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/comments.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
answer_id | nil | The id for the answer you wish to attach the comment to. | required |
comment | nil | A text blob. | required |
Response Codes
Code | Meaning |
---|---|
201 | A comment has been created and added to the answer. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The answer is not found. |
406 | The comment must not be empty. |
Related Events
Source | Comment |
---|---|
ss.comment.create | Emitted after a comment is created. |
Delete Comment
curl "https://app.socialscavenger.com/v1/comments/ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"answer_id": ANSWER_ID}' \
-i
If the system was able to delete the comment you will get a 200 http status code in the response.
This endpoint deletes a comment as specified by the comment ID
. You must be a player in the game, game coordinator, game administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/comments/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The comment ID. | required |
answer_id | nil | The id for the answer the comment is attached to. | required |
game_id | nil | The id for the game that contains the answer. | required |
Response Codes
Code | Meaning |
---|---|
200 | The comment has been deleted. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a player in the game, or a game coordinator, game administrator or system super administrator. |
404 | The answer, comment or game are not found. |
422 | The deletion could not be processed, perhaps due to permissions. |
Related Events
Source | Comment |
---|---|
ss.comment.delete | Emitted after a comment is deleted. |
Retrieve Comments for Answer
curl "https://app.socialscavenger.com/v1/comments.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"answer_id": ANSWER_ID}' \
-i
The above command returns JSON structured like this:
{
"comments": [
{
"id": 2,
"user_id": 14096,
"team_id": 93391,
"task_id": 234604,
"game_id": 9122,
"answer_id": 811637,
"comment": "That is too funny.",
"created_at": "2023-03-31T21:47:13Z",
"likes": 0,
"liked": 0
}
],
"answer": {
"id": 811637
}
}
This endpoint will list the comments for the answer.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/comments.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
answer_id | nil | The id for the answer the comments are attached to. | required |
Response Codes
Code | Meaning |
---|---|
200 | A list of comments for the answer are returned. |
401 | Unauthorized. |
404 | The answer is not found. |
Paginated Comments for Answer
curl "https://app.socialscavenger.com/v1/comments/answer/ANSWER_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"per_page": PER_PAGE, "token": PAGINATION_TOKEN}' \
-i
The above command returns JSON structured like this:
{
"pages": 1,
"per_page": 1,
"count": 1,
"token": 0,
"comments": [
{
"id": 2,
"user_id": 14096,
"team_id": 93391,
"task_id": 234604,
"game_id": 9122,
"answer_id": 811637,
"comment": "That is too funny.",
"created_at": "2023-03-31T21:47:13Z",
"likes": 0,
"liked": 0
}
]
}
This endpoint will retrieve a paginated list of comments for an answer, ordered by time, starting with the latest first.
Consumed by Player
and Builder
apps. Response applies Personalization
.
HTTP Request
GET https://app.socialscavenger.com/v1/comments/answer/ANSWER_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
answer_id | nil | The id for the answer you wish to list comments for. | required |
token | nil | The last comment id in the previous page is the pagination token. | optional |
per_page | 10 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of comments for the answer are returned. |
401 | Unauthorized. |
404 | The answer is not found. |
Like Comment
curl "https://app.socialscavenger.com/v1/comments/like.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"comment_id": COMMENT_ID, "answer_id": ANSWER_ID}' \
-i
The above command returns JSON.
This endpoint will like the comment. If the comment is already liked, it will remain liked.
Consumed by Player
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/comments/like.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
comment_id | nil | The id number of the comment you are liking. | required |
answer_id | nil | The id of the submission the comment is attached to. | required |
Response Codes
Code | Meaning |
---|---|
200 | The comment is liked, and already was. |
201 | The comment is liked, but wasn't previously. |
401 | Unauthorized. |
404 | The answer is not found. |
Related Events
Source | Comment |
---|---|
ss.comment.like | Emitted after successfully liking the comment. |
Unlike Comment
curl "https://app.socialscavenger.com/v1/comments/unlike.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"comment_id": COMMENT_ID, "answer_id": ANSWER_ID}' \
-i
The above command returns JSON.
This endpoint will unlike (or remove a like from) the comment. If the comment is already unliked, it will remain unliked.
Consumed by Player
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/comments/unlike.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
comment_id | nil | The id number of the comment you are liking. | required |
answer_id | nil | The id of the submission the comment is attached to. | required |
Response Codes
Code | Meaning |
---|---|
200 | The comment is not liked. |
401 | Unauthorized. |
404 | The answer or comment are not found. |
422 | The comment could not be unliked. |
Related Events
Source | Comment |
---|---|
ss.comment.unlike | Emitted after successfully unliking the comment. |
Designations
A designation is a status given to a player when they reach a certain level on the leaderboard.
Games have a set of designations attached to them.
Create Designation
curl "https://app.socialscavenger.com/v1/designations.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will add a designation. You must attach a designation to a game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/designations.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to attach the designation to. | required |
media_uuid | nil | The uuid of the media uploaded to s3. | optional |
media_extension | nil | The file extension for the media uploaded to s3. | optional |
name | nil | A name for the designation. | optional |
description | nil | A description for the designation. Maximum 250 characters. | optional |
trigger_type | points | One of "points" (team point total), or "tasks" (team task total). | optional |
trigger_value | 1 | The team achieves this status or designation after accomplishing this many units of the configured style. | optional |
Response Codes
Code | Meaning |
---|---|
201 | An designation has been created and added to the game. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.designation.create | Emitted after a designation is created. |
Delete Designation
curl "https://app.socialscavenger.com/v1/designations/ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
If the system was able to delete the designation you will get a 200 http status code in the response.
This endpoint deletes a designation as specified by the designation ID
. You must be a game coordinator or administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/designations/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id for the designation. | required |
game_id | nil | The id for the game you wish to attach the designation to. | required |
Response Codes
Code | Meaning |
---|---|
200 | The designation has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.designation.delete | Emitted after a designations is deleted. |
Retrieve Designations
curl "https://app.socialscavenger.com/v1/designations.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"game": {
"id": 785
},
"designations": [
{
"created_at": "2023-06-27T07:41:24Z",
"game_id": 785,
"id": 1,
"media_extension": "png",
"media_url": "https://ss-assets.socialscavenger.com/images/designation.png",
"media_uuid": "designation",
"name": "Wizard",
"description": "You're a wizard!",
"updated_at": "2023-06-27T07:41:24Z",
"trigger_type": "points",
"trigger_value": 10
}
]
}
This endpoint will list the designations for the game.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/designations.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game the designations are attached to. | required |
Response Codes
Code | Meaning |
---|---|
200 | A list of designations for the game are returned. |
401 | Unauthorized. |
404 | The game is not found. |
Update Designation
curl "https://app.socialscavenger.com/v1/designations/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"name": "NAME", "game_id": GAME_ID}' \
-i
If the system was able to update the designation you will get a 200 http status code in the response.
This endpoint will update an existing designation. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/designations/ID.json
Query Parameters
See the list of attributes in the Create Designation section. Note, game_id is required.
Response Codes
Code | Meaning |
---|---|
200 | The designation has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The designation or game is not found. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.designation.update | Emitted after successfully updating the designation. |
Games
Emit Game Event
curl "https://app.socialscavenger.com/v1/games/emit.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": 785, "event_type": "start"}' \
-i
The above command returns an http status code.
This endpoint will emit the desired system event for real-time coordination of players. You must be a game administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Player
and Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/games/emit.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The game id. | required |
event_type | nil | One of start, advance, leaderboard, end. | required |
Response Codes
Code | Meaning |
---|---|
201 | An event has been created. |
401 | Unauthorized. This method requires authentication. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
Related Events
Source | Comment |
---|---|
ss.game.live | Relays the provided event eg. "start" to the bus for consumption by listeners. |
ss.game.update | Emitted after start and end events if the start_anytime attribute has changed value. |
Create Game
curl "https://app.socialscavenger.com/v1/games.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Test API Game", "description": "This is a game created via the API.", "code": "testapigame", "signed_legal": true}' \
-i
The above command returns JSON structured like this:
{
"id": 7296,
"name": "Test API Game",
"code": "testapigame",
"created_at": "2021-09-23T00:10:45Z",
"updated_at": "2021-09-23T00:10:45Z",
"access": "Created",
"category": "Draft",
"export_player_enabled": false,
"finish_at": null,
"join_existing_team": false,
"late": "approve",
"game_type": 1,
"license_type": 1,
"notifications_bidirectional": true,
"photo_media_extension": null,
"photo_media_uuid": null,
"primary_email": "paul@socialscavenger.com",
"review": null,
"reviewers": null,
"searchability": true,
"share_location": true,
"shuffled": false,
"signed_legal": true,
"soundtrack": null,
"start_anytime": 1,
"start_at": null,
"time_to_play": null,
"description": "This is a game created via the API.",
"tz": "Eastern Time (US & Canada)",
"unlock_by_game_id": null,
"unlock_requires_network": true,
"creator_user_id": 14096,
"help": "HTML snippet",
"webhook": null
}
This endpoint will create a new game. You must be a game administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/games.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
category | Draft | One of Template, Draft, Active or Archive. | optional |
export_player_enabled | false | If set to 1 or true, this will enable players to be able to export their game submissions. | optional |
finish_at | nil | A date and time at which time the game is over. Use the format %m/%d/%Y %I:%M %p eg. 09/09/2020 02:00 am | optional |
join_existing_team | false | If set to 1 or true, this will give players the option to join an existing team as they enter the game. | optional |
late | approve | One of approve or reject. If reject, any submissions that are late are automatically rejected. | optional |
leaderboard_visible | true | If set to 0 or false the leaderboard will be hidden from players. | optional |
license_type | 1 | One of 1 (Commercial), 2 (Personal), 3 (Educational), 4 (Non-profit) | optional |
game_type | 1 | One of 0 (private), 1 (public), 2(featured) or 3 (featured but requiring unlock code) | optional |
name | nil | The name of the game. | required |
notifications_bidirectional | true | If 1 or true then players can participate in the chat. If 0 or false then players cannot send chat messages. | optional |
photo_media_extension | nil | The file extension of the game image uploaded directly to s3 | optional |
photo_media_uuid | nil | The file uuid of the game image uploaded directly to s3 | optional |
primary_email | creator email | The email address of the primary contact for this game. | optional |
review | nil | One of "pre", "post" or ""/nil. If set to pre, then submission must be approved before they show in the stream. If set to post, then submissions are accepted by default. | optional |
reviewers | nil | A comma delimited string of email addresses you wish to have review emails sent to for submissions in the game. | optional |
searchability | true | One of 0/false or 1/true. If true, the game is visible in the game seach results. If false, the game is hidden from search results. | optional |
share_location | false | One of "show"/true or "hide"/false. If show, then locations will be shared for submissions. | optional |
shuffled | false | One of 0/false or 1/true. If true, then tasks will be shuffled into a random order for each team. | optional |
collect_reviews | false | One of 0/false or 1/true. If true, then reviews should be solicited for the game. | optional |
signed_legal | false | Must be 1/true to create a game. | required |
soundtrack | nil | The filename of the soundtrack file to apply as the background music to reels. | optional |
start_anytime | 1 | One of 0 (Scheduled), 1 (Anytime) or 2 (Stopped). If scheduled, the game has a set start and end date and time. If anytime, can be played anytime without restriction. If stopped, game is in stopped state. | required |
start_at | nil | The start date and time of the game. Use the format %m/%d/%Y %I:%M %p eg. 09/09/2020 02:00 am | optional |
time_to_play | nil | The length of the game in English. eg. 3 hours or 50 minutes | optional |
timer_visible | 1 | If set to 0 or false, the timer item will be hidden. | optional |
description | nil | The description for the game. | required |
tz | "Eastern Time (US & Canada)" | The text label for the timezone settings. See Retrieve Timezones for valid values. | optional |
unlock_by_game_id | nil | The id of the game you wish to make a precondition of playing the current game. A team must complete 25% of the tasks in the precondition game to be able to join the current game. | optional |
code | nil | The unique unlock code for the game that players must enter in order to join. | required |
unlock_style | 1 | One of 0 (Offline) or 1 (Online). Offline unlocking means unlocking will occur without a round trip to the server or a network connection. | optional |
webhook | nil | A webhook url to HTTPS POST game events to. | optional |
post_join_drop_view | nil | The view to drop players in post game join. | optional |
challenges_list_view | nil | The view players see for the tasks or challenges list. | optional |
reel_duration | 0 | The duration of the reel in seconds. | optional |
leaderboard_aggregate | teams | One of players, teams or groups. | optional |
push_required | 0 | One of 0 (not required) or 1 (required). Indicates whether or not push notifications are a critical component of game play. | optional |
Response Codes
Code | Meaning |
---|---|
201 | A game has been created. |
401 | Unauthorized. This method requires authentication. |
422 | The game cannot be processed. |
Related Events
Source | Comment |
---|---|
ss.game.create | Emitted after successfully creating the game. |
ss.team.create | Emitted after successfully creating the first team. |
Retrieve Game
curl "https://app.socialscavenger.com/v1/games/GAME_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
Returns a json payload:
{
"game": {
"body_background_color": "ffffff",
"body_high_color": "e71323",
"body_tint_color": "e71323",
"body_txt_color": "000000",
"assets": {
"photos": [
{
"name": "standard",
"url": "https://....jpg",
"width": 1024,
"height": 489
},
{
"name": "logo",
"url": "https://....png",
"width": 0,
"height": 0
}
],
"icons": [
{
"name": "challenges",
"url": "https://....png",
"width": 0,
"height": 0
},
{
"name": "custom",
"url": "https://....png",
"width": 0,
"height": 0
}
]
},
"category": "Template",
"challenges_subtitle": "Complete missions to earn points",
"challenges_title": "Secret Missions",
"challenges_visible": true,
"created_at": "2014-12-22T23:29:11Z",
"creator_user_id": 156,
"custom_subtitle": "Come say hello",
"custom_title": "Events!",
"custom_url": "https://www.coca-cola.com/",
"theme": 0,
"custom_visible": true,
"dropbox_enabled": true,
"export_player_enabled": false,
"finish_at": null,
"font_bold": "Lato-Bold",
"font_regular": "Lato-Regular",
"font_size": 16,
"game_already_paid": true,
"game_type": 1,
"grey_enabled": true,
"help": "HTML CHUNK",
"help_subtitle": "This...screen",
"help_title": "Help",
"help_visible": true,
"id": 785,
"join_existing_team": true,
"join_subtitle": "Join a new program",
"join_title": "Switch Programs",
"join_visible": true,
"late": "approve",
"leaderboard_subtitle": "Reach for the top",
"leaderboard_title": "Podium",
"leaderboard_visible": true,
"library_enabled": true,
"license_type": 1,
"name": "Sample Game - TRY ME!",
"notifications_bidirectional": true,
"notifications_subtitle": "Messages sent to you",
"notifications_title": "Chat",
"notifications_visible": true,
"primary_email": "name@gmail.com",
"purchased_players": 50000,
"reel": "https://....mp4",
"reels_enabled": true,
"reels_subtitle": "Fun videos to share",
"reels_title": "Highlight Reels",
"reels_visible": true,
"review": "post",
"reviewers": "submissions@socialscavenger.com",
"rewards_subtitle": "The good stuff",
"rewards_title": "Rewards",
"rewards_visible": true,
"searchability": true,
"share_location": true,
"shuffled": false,
"signed_legal": true,
"soundtrack": "Scott_....m4a",
"start_anytime": 1,
"start_at": null,
"stream_subtitle": "Watch the action",
"stream_title": "Spy Zone",
"stream_visible": true,
"task_reels": [
{
"id": 1,
"url": "https://....mp4",
"name": "Show More Example"
}
],
"team_reels": [
{
"id": 1,
"url": "https://....mp4",
"name": "Test123"
}
],
"time_to_play": "",
"top_nav_background_color": "FFFFFF",
"top_nav_tint_color": "e71323",
"top_nav_txt_color": "e71323",
"tour": [
{
"id": 1,
"url": null
},
{
"id": 2,
"url": null
},
{
"id": 3,
"url": null
},
{
"id": 4,
"url": null
}
],
"description": "...Social Scavenger ",
"tz": "Eastern Time (US & Canada)",
"unlock_by_game_id": null,
"code": "XXX",
"unlock_requires_network": true,
"updated_at": "2021-09-22T23:43:13Z",
"user": {
"id": 123,
"super_admin": true,
"dropbox_linked": false,
"access": "Managing"
},
"webhook": null,
"theme": 0,
"timer_visible": true,
"tz": "Pacific Time (US & Canada)",
"cheats": [
{
"id": 0,
"code": "XXX-000000",
"help": "Use this code to shorten the game by setting the finish time to 15 minutes earlier.",
"admin_required": true
},
{
"id": 1,
"code": "XXX-111111",
"help": "Use this code to lengthen the game by setting the finish time to 15 minutes later.",
"admin_required": true
}
]
}
}
This endpoint will return a single game.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/games/GAME_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The game id. | required |
Response Codes
Code | Meaning |
---|---|
200 | The game. |
Retrieve Game (Alt)
curl "https://app.socialscavenger.com/v1/games/search/GAME_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
Returns a json payload:
{
"more": false,
"results": {
"HTML_description": "https://app.so...85.html",
"assets": {
"photos": [
{
"height": 683,
"name": "standard",
"url": "https://ss-as....jpg",
"width": 1024
}
]
},
"author": {
"id": 156,
"name": "Paul"
},
"branding": true,
"code": "intent",
"description": "​Hey there friend.",
"easy_merge": true,
"id": 785,
"locked": false,
"name": "Paul C's Sample Game - TRY ME!",
"prompt_for_password": true,
"team": {
"id": 48130,
"photo": true
},
"unlocked_by": "",
"user": {
"creator": false,
"id": 14096,
"joined": true
}
}
}
This endpoint will return a single game.
Consumed by Player
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/games/search/GAME_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The game id. | required |
Response Codes
Code | Meaning |
---|---|
200 | The game. |
Update Game
curl "https://app.socialscavenger.com/v1/games/GAME_ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"review": "post"}' \
-i
If the system was able to update the game you will get a 200 http status code in the response.
This endpoint will update an existing game. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/games/GAME_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game. | required |
See the list of attributes in the Create Game section.
Response Codes
Code | Meaning |
---|---|
200 | The game has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.game.update | Emitted after successfully updating the game. |
Delete Game
curl "https://app.socialscavenger.com/v1/games/GAME_ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
If the system was able to delete the game you will get a 200 http status code in the response.
This endpoint deletes a game. You must be a game administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/games/GAME_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to destroy. | required |
Response Codes
Code | Meaning |
---|---|
200 | The game has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.game.delete | Emitted after successfully deleting the game. |
Empty Game
curl "https://app.socialscavenger.com/v1/games/GAME_ID/empty.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
The endpoint returns a status code.
This endpoint will empty a game of submissions and chat messages. Due to the sensitivities of deleting user submissions, this action may only be taken by a system super administrator.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/games/GAME_ID/empty.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to empty. | required |
Response Codes
Code | Meaning |
---|---|
200 | The game has been emptied. |
401 | Unauthorized. This method requires authentication and the user must be a system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.answer.delete | Emitted after successfully deleting each answer. |
Clone Game
curl "https://app.socialscavenger.com/v1/games/GAME_ID/clone.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
The above command returns JSON structured like this:
{
"id": 7370,
"name": "Copy Dequace of XXX Birthday",
"code": "XXXAAAA",
"updated_at": "2021-10-16T01:30:37Z",
"user": {
"access": "Created"
},
"category": "Active"
}
This endpoint will clone a game, making a copy of it into a new game. All tasks will be copied to the new game as part of cloning. The caller is the game's creator and its first administrator.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/games/GAME_ID/clone.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id of the game you wish to clone. | required |
Response Codes
Code | Meaning |
---|---|
200 | The game has been cloned. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
422 | The system was unable to process the cloning of the game. |
Related Events
Source | Comment |
---|---|
ss.game.create | Emitted after successfully saving the new game. |
ss.game.clone | Emitted after successfully cloning the old game to the new game. |
ss.task.create | Emitted after creating each new task. |
ss.team.create | Emitted after successfully creating the first team in the new game. |
ss.reward.create | Emitted after creating each new game level reward. |
Migrate Game Assets
curl "https://app.socialscavenger.com/v1/games/GAME_ID/migrate.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
The above command returns an HTTP response code.
This endpoint will migrate all game rich media assets from the old attachment style to the new attachment style. Games created with earlier versions of the platform did not leverage the rich media pipeline in place today. The act of migrating the assets will push all the rich media through the pipeline so images will be watermarked again, videos will be re-transcoded etc. A migration for a game is meant to happen once.
HTTP Request
POST https://app.socialscavenger.com/v1/games/GAME_ID/migrate.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id of the game you wish to migrate. | required |
Response Codes
Code | Meaning |
---|---|
200 | The game has been migrated. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
Related Events
Source | Comment |
---|---|
ss.answer.update | Emitted after successfully updating each answer. |
ss.game.update | Emitted after successfully updating the game. |
ss.task.update | Emitted after successfully updating each task. |
ss.team.update | Emitted after successfully updating each team. |
ss.reward.update | Emitted after successfully updating each reward. |
Retrieve Game Branding
curl "https://app.socialscavenger.com/v1/games/GAME_ID/grey.json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
The above command returns JSON structured like this:
{
"top_nav_background_color": "FFFFFF",
"top_nav_text_color": "e71323",
"top_nav_tint_color": "e71323",
"body_highlight_color": "e71323",
"body_background_color": "ffffff",
"body_text_color": "000000",
"body_tint_color": "e71323",
"grey_url_prefix": "https://app.socialscavenger.com/v1/proxy/grey/785/",
"icon_logo": "logo",
"font_bold": "Lato-Bold",
"font_regular": "Lato-Regular",
"font_size": 16,
"tour": [
{
"id": 1,
"url": null
},
{
"id": 2,
"url": null
},
{
"id": 3,
"url": null
},
{
"id": 4,
"url": null
}
],
"main_menu": {
"challenges": {
"visible": true,
"order": 0,
"title": "Secret Missions",
"subtitle": "Complete missions to earn points",
"icon_enabled": "challengesenabled"
},
"stream": {
"visible": true,
"order": 1,
"title": "Spy Zone",
"subtitle": "Watch the action",
"icon_enabled": "streamenabled"
},
"leaderboard": {
"visible": true,
"order": 2,
"title": "Podium",
"subtitle": "Reach for the top",
"icon_enabled": "leaderboardenabled"
},
"reels": {
"visible": true,
"order": 3,
"title": "Highlight Reels",
"subtitle": "Fun videos to share",
"icon_enabled": "reelsenabled"
},
"rewards": {
"visible": true,
"order": 4,
"title": "Rewards",
"subtitle": "The good stuff",
"icon_enabled": "rewardsenabled"
},
"join": {
"visible": true,
"order": 5,
"title": "Switch Programs",
"subtitle": "Join a new program",
"icon_enabled": "joinenabled"
},
"notifications": {
"visible": true,
"order": 6,
"title": "Chat",
"subtitle": "Messages sent to you",
"icon_enabled": "notificationsenabled"
},
"help": {
"visible": true,
"order": 7,
"title": "Help",
"subtitle": "This is a long-winded byline that will get truncated once it runs off the screen",
"icon_enabled": "helpenabled"
},
"custom": {
"visible": true,
"order": 8,
"title": "Events",
"subtitle": "Come say hello",
"icon_enabled": "customenabled",
"url": "https://www.coca-cola.com/"
}
},
"help": null,
"default_help": "HTML code",
"timer": {
"active": false,
"seconds_remaining": 0,
"seconds_until": 0,
"visible": true
}
}
This endpoint retrieves the branding configuration for a game.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/games/GAME_ID/grey.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to retreive branding for. | required |
Response Codes
Code | Meaning |
---|---|
200 | Game branding is returned. |
401 | Not authorized. |
404 | The game is not found. |
Payload
Object | Attribute | Type | Comment |
---|---|---|---|
grey_url_prefix | string | The stem to be used when building urls. | |
icon_logo | string | If not empty, you can build a url for an asset. grey_url_prefix + this + one of (.png, @2x.png or @3x.png) eg. https://app.socialscavenger.com/v1/proxy/grey/785/logo@2x.png | |
main_menu challenges | icon_enabled | string | If not empty, you can build a url for an asset. grey_url_prefix + this + one of (.png, @2x.png or @3x.png) eg. https://app.socialscavenger.com/v1/proxy/grey/785/challengesenabled@2x.png |
Update Game Branding
curl "https://app.socialscavenger.com/v1/games/GAME_ID/grey.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"custom_title": "Custom Title"}' \
-i
If the system was able to update the game you will get a 200 http status code in the response.
This endpoint will update a grey label game's branding. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/games/GAME_ID/grey.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game. | required |
top_nav_background_color | nil | A hexadecimal color eg. FFFFFF | optional |
top_nav_txt_color | nil | A hexadecimal color eg. FFFFFF | optional |
top_nav_tint_color | nil | A hexadecimal color eg. FFFFFF | optional |
body_high_color | nil | A hexadecimal color eg. FFFFFF | optional |
body_txt_color | nil | A hexadecimal color eg. FFFFFF | optional |
body_background_color | nil | A hexadecimal color eg. FFFFFF | optional |
body_tint_color | nil | A hexadecimal color eg. FFFFFF | optional |
font_size | nil | An integer font size eg. 10 | optional |
font_regular | nil | The font name eg. Lato-Regular | optional |
font_bold | nil | The bold font name eg. Lato-Bold | optional |
logo_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
logo_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
challengesenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
challengesenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
challenges_title | nil | The tile you would like to use for the menu item. | optional |
challenges_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
challenges_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
challenges_order | 0 | An integer number that defines the ascending order of the main menu. | optional |
streamenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
streamenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
stream_title | nil | The tile you would like to use for the menu item. | optional |
stream_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
stream_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
stream_order | 1 | An integer number that defines the ascending order of the main menu. | optional |
leaderboardenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
leaderboardenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
leaderboard_title | nil | The tile you would like to use for the menu item. | optional |
leaderboard_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
leaderboard_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
leaderboard_order | 2 | An integer number that defines the ascending order of the main menu. | optional |
npcsenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
npcsenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
npcs_title | nil | The tile you would like to use for the NPC or character menu item. | optional |
npcs_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
npcs_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
npcs_order | 3 | An integer number that defines the ascending order of the main menu. | optional |
reelsenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
reelsenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
reels_title | nil | The tile you would like to use for the menu item. | optional |
reels_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
reels_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
reels_order | 4 | An integer number that defines the ascending order of the main menu. | optional |
rewardsenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
rewardsenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
rewards_title | nil | The tile you would like to use for the menu item. | optional |
rewards_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
rewards_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
rewards_order | 5 | An integer number that defines the ascending order of the main menu. | optional |
joinenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
joinenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
join_title | nil | The tile you would like to use for the menu item. | optional |
join_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
join_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
join_order | 6 | An integer number that defines the ascending order of the main menu. | optional |
notificationsenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
notificationsenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
notifications_title | nil | The tile you would like to use for the menu item. | optional |
notifications_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
notifications_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
notifications_order | 7 | An integer number that defines the ascending order of the main menu. | optional |
helpenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
helpenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
help_title | nil | The tile you would like to use for the menu item. | optional |
help_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
help_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
help_order | 8 | An integer number that defines the ascending order of the main menu. | optional |
customenabled_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
customenabled_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
custom_title | nil | The tile you would like to use for the menu item. | optional |
custom_subtitle | nil | The subtile or byline you would like to use for the menu item. | optional |
custom_url | nil | A url to open for the custom menu item. | optional |
custom_visible | nil | If set to 0 or false, the menu item will be hidden. | optional |
custom_order | 9 | An integer number that defines the ascending order of the main menu. | optional |
help | nil | A custom HTML snippet to display instead of the default help contents. | optional |
terms | nil | A custom HTML terms of use to display for acceptance post game join. | optional |
tour_1_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
tour_1_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
tour_2_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
tour_2_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
tour_3_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
tour_3_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
tour_4_media_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
tour_4_media_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
theme | 0 | Whether or not the branding theme is light (0) or dark (1). | optional |
timer_visible | 1 | If set to 0 or false, the timer item will be hidden. | optional |
watermark_uuid | nil | The filename uuid of the file uploaded directly to Amazon S3. | optional |
watermark_extension | nil | The filename extension of the file uploaded directly to Amazon S3. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The game has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.game.update | Emitted after successfully updating the game. |
Generate Game Reels
curl "https://app.socialscavenger.com/v1/games/GAME_ID/generate_reels.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"reel_type": "game"}' \
-i
The above command returns an HTTP status code.
This endpoint will generate or regenerate the reels for a particular game.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/generate_reels.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
reel_type | game | One of game, challenges or teams. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The reels have been queued for generation or regeneration. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
406 | The action is not acceptable. Likely that reels have not been enabled for the game in question. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.game.reel | Emitted after successfully generating the game reel. |
ss.task.reel | Emitted after successfully generating each task reel. |
ss.team.reel | Emitted after successfully generating each team reel. |
Paginated Games (Recommended or Term)
curl "https://app.socialscavenger.com/v1/games/search.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"term": "TERM", "token": PAGINATION_TOKEN}' \
-i
The above command returns JSON structured like this:
{
"results": [
{
"id": 7160,
"easy_merge": false,
"name": "Birthday",
"author": {
"id": 14096,
"name": "Social Scavenger"
},
"description": "Finn's turning six and to celebrate...",
"prompt_for_password": true,
"user": {
"id": 14096,
"joined": true,
"creator": true
},
"team": {
"id": 69006,
"photo": false
},
"code": "XXXX",
"assets": {
"photos": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
},
"locked": false,
"unlocked_by": "",
"branding": false
}
],
"more": false
}
This endpoint can be used to return recommended games or a list of games filtered by a search term. If recommended is set to true, then pagination is not supported and you will get a complete list.
Consumed by Player
apps. Response applies Personalization
.
HTTP Request
GET https://app.socialscavenger.com/v1/games/search.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
term | "" | A search term to filter games by. If not provided, results will limited to recommended or joined. | optional |
token | nil | The last answer id in the previous page is the pagination token. | optional |
recommended | false | True or false. If true, results will be recommended games only and ignore search term. | optional |
joined_only | false | True or false. If true, results will be limited to games the caller has joined. You must authenticate if passing joined_only as true. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of games. |
Related Events
Source | Comment |
---|---|
ss.game.search | Emitted after successfully searching for a game. |
Paginated Games (Category and Time)
curl "https://app.socialscavenger.com/v1/games.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"history": HISTORY, "category": "CATEGORY", "page": PAGE, "per_page": PER_PAGE, "term": "TERM"}' \
-i
The above command returns JSON structured like this:
{
"games": [
{
"id": 7337,
"name": "Who Kidnapped Michael Scott?! - PWC",
"code": "XXXX",
"updated_at": "2022-12-15T16:34:24Z",
"user": {
"id": 14096,
"access": "Managing",
"super_admin": true
},
"category": "Active",
"export_player_enabled": false,
"liberated": {
"teams": true,
"branding": true,
"reels": false,
"library": false
}
}
],
"meta": {
"term": "",
"page": 1,
"pages": 42,
"per_page": 30,
"count": 1246,
"category": "Active"
}
}
This endpoint will return a list of games by category and historical window.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/games.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
history | 365 | The number of days backwards from now to include. | optional |
term | nil | The search term to filter the list for. Name, id, and code will be searched. | optional |
category | nil | One of Template, Draft, Active, or Archive if provided. | optional |
page | 1 | Page of results you which to retrieve. | optional |
per_page | 25 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of games. |
401 | Unauthorized. |
Verify Game Code
curl "https://app.socialscavenger.com/v1/games/verify.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"code": "UNLOCKCODE"}'
The above command returns JSON structured like this:
{
"id": 785,
"user": {
"email": "user@domain.com",
"id": 63050
},
"team": {
"id": 1,
"photo": true
},
"jwt": {
"lifespan": 1440,
"token": "eyJhbGciOiJIUzI1...rCuxvWKNbOro",
"refresh_token": "XXX"
}
}
or like this:
{
"id": 785,
"user": nil,
"team": nil,
"jwt": nil
}
This endpoint will verify a game unlock code to determine if the code is a personal unlock code. A personal code will return details about the game and the user (including team and tokens).
It can also verify a game unlock code to determine if the code is a cheat code. A cheat code will return details about the game only.
Consumed by Player
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/games/verify.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code you wish to validate. | required |
Response Codes
Code | Meaning |
---|---|
200 | Game details are returned. |
401 | Unauthorized as personal unlock code is invalid. |
Related Events
Source | Comment |
---|---|
ss.user.signin | Emitted after authenticating the user. |
Join Game
curl "https://app.socialscavenger.com/v1/games/GAME_ID/join.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"user_joining_id": USER_ID, "code": "UNLOCKCODE"}' \
-i
The above command returns an HTTP status code and if successful json like:
{
"id": 785,
"name": "Sample Game - TRY ME!",
"code": "unlockme",
"user": {
"id": 23008,
"code": "XXX",
"joined": true,
"creator": false
},
"team": {
"id": 26040,
"photo": false
},
"assets": {
"photos": [
{
"name": "standard",
"url": "https://ss...jpg",
"width": 1024,
"height": 489
}
]
},
"branding": true,
"reel": "https://app...._785_s.mp4"
}
This endpoint joins a player to a game.
Consumed by Player
apps. Response applies Personalization
.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/join.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id of the game to join. | required |
user_joining_id | nil | The id of the user, if not the caller, to join to the game. | optional |
code | nil | The unlock code. | required |
name | nil | A name for the team. | optional |
photo_media_uuid | nil | The uuid of the media uploaded directly to AWS S3 to be used for the team photo. | optional |
photo_media_extension | nil | The file extension of the media asset uploaded directly to AWS S3 to be used for the team photo. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The user has joined the game. |
401 | Unauthorized. This method requires authentication and the user must be a game administrator or system super administrator if joining someone other than themselves. |
402 | Payment for additional teams is required. |
403 | The user is banned. |
404 | The game or user is not found. |
406 | Unlock code invalid. |
Related Events
Source | Comment |
---|---|
ss.team.create | Emitted after creating a new team, if required. |
ss.game.join | Emitted after joining the game. |
Leave Game
curl "https://app.socialscavenger.com/v1/games/GAME_ID/leave.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"user_leaving_id": USER_ID}' \
-i
The above command returns an HTTP status code.
This endpoint removes a player from a game.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/leave.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id of the game to leave. | required |
user_leaving_id | nil | The id of the user, if not the caller, to remove from the game. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The user has left the game. |
401 | Unauthorized. This method requires authentication and the user must be a game coordinator, game administrator or system super administrator if removing someone other than themselves. |
404 | The game or user is not found. |
406 | The action is unacceptable as the user is not part of the game. |
Related Events
Source | Comment |
---|---|
ss.game.leave | Emitted after leaving the game. |
Export Game
Authenticating as an administrator, export all teams and challenges with media:
curl "https://app.socialscavenger.com/v1/games/GAME_ID/export.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"email": "EMAIL", "media": true}' \
-i
The above command returns an HTTP status code.
Without authentication, export a single team:
curl "https://app.socialscavenger.com/v1/games/GAME_ID/export.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"email": "EMAIL", "team_id": TEAM_ID, "media": true}' \
-i
The above command returns an HTTP status code.
This endpoint starts a game export operation.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/export.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
nil | Email address to send game export link to. | required | |
task_id | nil | ID for challenge or task you wish to limit export to. | optional |
team_id | nil | ID for team you wish to limit export to. | optional |
game_id | nil | ID for game you wish to export. | required |
media | false | One of true or false. If true, export file will contain all the rich media for the game. | optional |
watermark | false | One of true or false. If true, rich media will be watermarked in the export. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The export has been queued. |
403 | The action is forbidden. Likely that you are requesting an export for multiple teams without being a game administrator or system super administrator. |
404 | The game is not found. |
422 | A valid email address must be provided, otherwise the system cannot process the export. |
Related Events
Source | Comment |
---|---|
ss.game.export | Emitted after the game has been exported. |
Retrieve Slideshow
curl "https://app.socialscavenger.com/v1/games/GAME_ID/slideshow.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"code": "UNLOCKCODE"}' \
-i
The above command returns JSON structured like this:
{
"answers": [
{
"id": 577046,
"created_at": "2021-07-12T23:05:02Z",
"approved_at": null,
"featured_at": "2021-07-12T23:06:14Z",
"rejected_at": null,
"type": 1,
"sub_type": 0,
"early": false,
"late": false,
"latitude": 49.369204716194425,
"longitude": -123.28017513407875,
"points": 0,
"trivia": null,
"comment": "",
"duration": null,
"assets": {
"photos": [
{
"name": "standard",
"url": "https://ss....jpg",
"width": 3024,
"height": 4032
},
{
"name": "background-sticker",
"url": null,
"width": 3024,
"height": 4032
},
{
"name": "background-merged",
"url": null,
"width": 3024,
"height": 4032
}
],
"videos": [
{
"name": "standard",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 3024,
"height": 4032
},
{
"name": "background-merged",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 3024,
"height": 4032
}
],
"audios": [
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
},
"team": {
"id": 66025,
"name": "Team 1"
},
"task": {
"id": 166338,
"name": "The Last One",
"description": "This one is just ...."
},
"user": {
"email": "paul@socialscavenger.com"
},
"media_processing": false
}
]
}
This endpoint retrieves the rich media for a game for use in a slideshow.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/games/GAME_ID/slideshow.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game. | required |
code | nil | If the caller does not pass an authentication token, they may pass an unlock code. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of submissions. |
401 | Unauthorized. |
404 | The game is not found. |
Create Administrator
curl "https://app.socialscavenger.com/v1/games/GAME_ID/administrator.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"player_id": PLAYER_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will create a new administrator for a game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/games/GAME_ID/administrator.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
player_id | nil | The platform's internal user identification number. | required |
Response Codes
Code | Meaning |
---|---|
200 | The player has been made a game administrator. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game or player are not found. |
Related Events
Source | Comment |
---|---|
ss.admin.create | Emitted after the administrator has been created. |
Retrieve Administrators
curl "https://app.socialscavenger.com/v1/games/GAME_ID/administrator.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-i
The above command returns JSON structured like this:
{
"administrators": [
{
"created_at": "2019-03-31T07:33:58Z",
"email": "first.last@gmail.com",
"id": 1,
"name": "First Last",
"user_id": 1
}
],
"game": {
"id": 785
}
}
This endpoint will list the administrators for a game.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/games/GAME_ID/administrator.json
Response Codes
Code | Meaning |
---|---|
200 | A list of administrators. |
401 | Unauthorized. |
403 | You must be a game player, a game coordinator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Delete Administrator
curl "https://app.socialscavenger.com/v1/games/GAME_ID/administrator.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"player_id": PLAYER_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will delete an existing administrator from a game.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/games/GAME_ID/administrator.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
player_id | nil | The platform's internal user identification number. | required |
Response Codes
Code | Meaning |
---|---|
200 | The player has removed as a game administrator. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game or player are not found. |
Related Events
Source | Comment |
---|---|
ss.admin.delete | Emitted after the administrator has been deleted. |
Create Coordinator
curl "https://app.socialscavenger.com/v1/games/GAME_ID/coordinator.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"player_id": PLAYER_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will create a new coordinator for a game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/games/GAME_ID/coordinator.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
player_id | nil | The platform's internal user identification number. | required |
Response Codes
Code | Meaning |
---|---|
200 | The player has been made a game coordinator. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game or player are not found. |
Related Events
Source | Comment |
---|---|
ss.coordinator.create | Emitted after the coordinator has been created. |
Retrieve Coordinators
curl "https://app.socialscavenger.com/v1/games/GAME_ID/coordinator.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-i
The above command returns JSON structured like this:
{
"coordinators": [
{
"created_at": "2019-03-31T07:33:58Z",
"email": "first.last@gmail.com",
"id": 1,
"name": "First Last",
"user_id": 1
}
],
"game": {
"id": 785
}
}
This endpoint will list the coordinators for a game.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/games/GAME_ID/coordinator.json
Response Codes
Code | Meaning |
---|---|
200 | A list of coordinators. |
401 | Unauthorized. |
403 | You must be a game player, a game coordinator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Delete Coordintator
curl "https://app.socialscavenger.com/v1/games/GAME_ID/coordinator.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"player_id": PLAYER_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will delete an existing coordinator from a game.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/games/GAME_ID/coordinator.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
player_id | nil | The platform's internal user identification number. | required |
Response Codes
Code | Meaning |
---|---|
200 | The player has removed as a game coordinator. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game or player are not found. |
Related Events
Source | Comment |
---|---|
ss.coordinator.delete | Emitted after the coordinator has been deleted. |
Create Ban for Player
curl "https://app.socialscavenger.com/v1/games/GAME_ID/ban.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"player_id": PLAYER_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will ban a player from a game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/games/GAME_ID/ban.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
player_id | nil | The platform's internal user identification number. | required |
Response Codes
Code | Meaning |
---|---|
200 | The player has been banned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game or player are not found. |
Related Events
Source | Comment |
---|---|
ss.user.ban | Emitted after the user has been banned. |
Retrieve Banned Players
curl "https://app.socialscavenger.com/v1/games/GAME_ID/ban.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-i
The above command returns JSON structured like this:
{
"bans": [
{
"created_at": "2019-03-31T07:33:58Z",
"email": "first.last@gmail.com",
"id": 1,
"name": "First Last",
"user_id": 1
}
],
"game": {
"id": 785
}
}
This endpoint will list the banned players for a game.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/games/GAME_ID/ban.json
Response Codes
Code | Meaning |
---|---|
200 | A list of banned players. |
401 | Unauthorized. |
403 | You must be a game player, a game coordinator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Delete Ban for Player
curl "https://app.socialscavenger.com/v1/games/GAME_ID/ban.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"player_id": PLAYER_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will remove a ban for a player for a particular game.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/games/GAME_ID/ban.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
player_id | nil | The platform's internal user identification number. | required |
Response Codes
Code | Meaning |
---|---|
200 | The player has unbanned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game or player are not found. |
Related Events
Source | Comment |
---|---|
ss.user.unban | Emitted after the user had their ban revoked. |
Create Communication Blast
curl "https://app.socialscavenger.com/v1/games/GAME_ID/blast.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"subject": "SUBJECT", "message": "MESSAGE", "method": STYLE}' \
-i
The above command returns an HTTP status code.
This endpoint will send a communication blast to all players in a game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/games/GAME_ID/blast.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
subject | nil | The subject for your message. | required |
message | nil | The main body of your message. | required |
style | 1 | One of 0 (push notification), 1 (email), 2 (chat as administrator) or 3 (chat as the system) | optional |
Response Codes
Code | Meaning |
---|---|
200 | The blast has been queued or sent. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.chat.create | Emitted after a chat message is sent. |
Ask for Reviews
curl "https://app.socialscavenger.com/v1/games/GAME_ID/reviews.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will send emails asking game players to leave a review.
HTTP Request
POST https://app.socialscavenger.com/v1/games/GAME_ID/reviews.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id of the game to solicit reviews for. | required |
team_id | nil | The id of the team to solicit reviews for. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The request to solicit reviews has been processed and is in queue. |
401 | Unauthorized. This method requires authentication and the user must be a member of the team or game coordinator, game administrator or system super administrator if asking for reviews from everyone. |
404 | The game or team is not found. |
Related Events
Source | Comment |
---|---|
ss.emails.reviews | Emitted to solicit game reviews. |
Groups
Create Group
curl "https://app.socialscavenger.com/v1/groups.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"label": "LABEL", "game_id": GAME_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will create a group in the game. By default, a new group will contain no teams.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/groups.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game in which the group lives. | required |
label | nil | The group name or label. | optional |
Response Codes
Code | Meaning |
---|---|
201 | A group has been created and added to the game. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.group.create | Emitted after a group is created. |
Retrieve Groups
curl "https://app.socialscavenger.com/v1/groups.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"id": 1,
"groups": [
{
"id": 2,
"label": "Human Resources",
"teams": []
}
]
}
This endpoint will list the groups, and the teams inside each group, for the game.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/groups.json
Response Codes
Code | Meaning |
---|---|
200 | A list of groups for the game are returned. |
401 | Unauthorized. |
404 | The game is not found. |
Update Group
curl "https://app.socialscavenger.com/v1/groups/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "label": "LABEL", "team_id": TEAM_ID}' \
-i
If the system was able to update the group you will get a 200 http status code in the response.
This endpoint updates a group in a game. If you include a label, it will replace the existing label. If you include a team_id, it will ensure that team is part of the group. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/groups/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
id | nil | The id for the group. | required |
label | nil | The group name or label. | optional |
team_id | nil | The id of the team you wish to add to the group. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The group has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game, team or group are not found. |
406 | Not acceptable parameters. |
422 | No update was processed. |
Related Events
Source | Comment |
---|---|
ss.group.update | Emitted after a group is updated. |
Delete Group
You may delete a group completely by deleting all the teams from the group and then omitting the team_id from the call to Delete Team from Group.
Delete Team from Group
curl "https://app.socialscavenger.com/v1/groups/ID.json" \
-X DELETE \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID, "team_id": TEAM_ID}' \
-i
If the system was able to delete the group you will get a 200 http status code in the response.
This endpoint deletes a team from a group, or if the group is empty, the group itself. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/groups/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
id | nil | The id for the group. | required |
team_id | nil | The id for the team to remove from the group. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The group has been deleted. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game or group are not found. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.group.delete | Emitted after a group is deleted. |
ss.group.update | Emitted after a group is updated. |
Judges
A judge is an AI personality that examines player submissions (answers).
Judges are configured at the task (challenge) level.
Judges may impact the leaderboard by creating an adjustment.
Create Judge
curl "https://app.socialscavenger.com/v1/judges.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "task_id": TASK_ID, "name": "NAME", "active": ACTIVE, "prompt": "PROMPT", "mode": MODE}' \
-i
The above command returns an HTTP status code.
This endpoint will add a judge. You must attach an judge to an answer.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/judges.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to attach the judge to. | required |
task_id | nil | The id for the task to which the judge applies. | required |
media_uuid | nil | The uuid of the media uploaded to s3. | optional |
media_extension | nil | The file extension for the media uploaded to s3. | optional |
name | nil | The name given to the judge. | optional |
active | false | Whether or not the judge is active for new submissions. | ignored |
prompt | nil | The instructions for the judge. | optional |
mode | false | If true (1), public communications are enabled and judgements are shared via comments and likes on submissions. If false (0), private communications are shared via private chat only to the team. | optional |
Response Codes
Code | Meaning |
---|---|
201 | An judge has been created and added to the game and task. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
404 | The game or task are not found. |
406 | The game and task has an existing judge. One judge per task allowed. |
Related Events
Source | Comment |
---|---|
ss.judge.create | Emitted after a judge is created. |
Delete Judge
curl "https://app.socialscavenger.com/v1/judges/ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
If the system was able to delete the judge you will get a 200 http status code in the response.
This endpoint deletes a judge as specified by the judge ID
. You must be a game coordinator or administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/judges/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id for the judge. | required |
game_id | nil | The id for the game you wish to attach the judge to. | required |
Response Codes
Code | Meaning |
---|---|
200 | The judge has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.judge.delete | Emitted after a judge is deleted. |
Retrieve Judges
curl "https://app.socialscavenger.com/v1/judges.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"game": {
"id": 1
},
"judges": [
{
"active": false,
"created_at": "2024-10-04T03:10:38Z",
"game_id": 1,
"id": 2,
"media_extension": "png",
"media_url": "https://ss-assets.socialscavenger.com/images/robot.png",
"media_uuid": "robot",
"mode": true,
"name": "Figster",
"prompt": "Try a new prompt.",
"task_id": 283815,
"updated_at": "2024-10-04T03:54:12Z",
"validity": "The instructions are incomplete. Firstly, they don't specify how to determine if a submission is correct or incorrect. Secondly, there's no clear guidance on how to score submissions between 1 and 100 to identify the best one. Thirdly, there's no mention of a point system for awarding or penalizing submissions. Lastly, the instructions provide no guidance on how judges should comment for player entertainment."
}
]
}
This endpoint will list the judges for the game.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/judges.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game the judges are attached to. | required |
Response Codes
Code | Meaning |
---|---|
200 | A list of judges for the game are returned. |
401 | Unauthorized. |
404 | The game is not found. |
Update Judge
curl "https://app.socialscavenger.com/v1/judges/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"name": NAME, "game_id": GAME_ID}' \
-i
If the system was able to update the judge you will get a 200 http status code in the response.
This endpoint will update an existing judge. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/judges/ID.json
Query Parameters
See the list of attributes in the Create Judge section. Note, game_id is required.
Response Codes
Code | Meaning |
---|---|
200 | The judge has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The judge or game is not found. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.judge.update | Emitted after successfully updating the judge. |
Leaderboards
Retrieve Leaderboard
curl "https://app.socialscavenger.com/v1/leaderboards.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}'
The above command returns JSON structured like this:
{
"game": {
"tasks": 12,
"teams": 2
},
"user": {
"id": 14096,
"email": "name@domain.com"
},
"my": {
"id": 69006,
"name": "Team 1",
"completed": 3,
"designations": [],
"points": 30,
"place": 2,
"reel": "",
"assets": {
"photos": []
},
"updated": "2021-08-30T18:27:54Z"
},
"teams": [
{
"id": 70765,
"name": "Team X",
"completed": 9,
"designations": [
{
"assets": {
"photos": [
{
"height": 1024,
"url": "https://ss-assets.socialscavenger.com/images/designation.png",
"width": 1024
}
]
},
"description": "You're ready to teach the others.",
"name": "Teacher",
"trigger": "points"
},
{
"assets": {
"photos": [
{
"height": 1024,
"url": "https://ss-assets.socialscavenger.com/images/designation.png",
"width": 1024
}
]
},
"description": "You know how to get it done.",
"name": "Task Master",
"trigger": "tasks"
}
],
"points": 90,
"place": 1,
"reel": "",
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://....jpg",
"width": 75,
"height": 75
},
{
"name": "standard",
"url": "https://....jpg",
"width": 1024,
"height": 768
}
]
},
"updated": "2021-08-22T03:07:46Z"
}
],
"has_more": false
}
This endpoint retrieves the leaderboard for a particular game as specified by the game id.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/leaderboards.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you want the leaderboard for. | required |
last_position | 0 | The last position seen. If you've loaded 10 groups or teams, the last_position would be 10. | optional |
term | nil | A search term to filter the leaderboard by. Filters by group or team name. | optional |
style | alltime | One of daily, weekly or alltime. | optional |
metric | points | One of points or completed. | optional |
aggregate | teams | One of players, teams or groups. | optional |
per_page | 10 | The number of teams to return per_page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The leaderboard is returned. |
401 | Unauthorized. This method requires authentication. |
404 | The game is not found. |
Rescore Leaderboard
curl "https://app.socialscavenger.com/v1/leaderboards/rescore.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns an http status code.
This endpoint recalculates, or rescores, the leaderboard for the game.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/leaderboards/rescore.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to have the leaderboard recalculated. | required |
Response Codes
Code | Meaning |
---|---|
200 | The leaderboard has been queued to be rescored. |
404 | The game cannot be found. |
Related Events
Source | Comment |
---|---|
ss.game.score | Emitted after the game has been rescored. |
Medias
Retrieve Signature
curl "https://app.socialscavenger.com/v1/medias/sign/FILE_EXTENSION" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
The above command returns JSON structured like this:
{
"signature": "https://ss-production.s3.amazonaws.com/uploads/8ac36800d7cb01397747161fd571a376.mp4?x-amz-acl...",
"uri": "https://s3.amazonaws.com/ss-...161fd571a376.mp4",
"name": "8ac36800d7cb01397747161fd571a376.mp4"
}
This endpoint will provide a signature for use in uploading media directly to s3.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/medias/sign/FILE_EXTENSION
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
file_extension | nil | The file extension for the media you want to upload. Eg. mp4 | required |
Response Codes
Code | Meaning |
---|---|
200 | A signature was returned. |
401 | Unauthorized. |
Retrieve Signatures
curl "https://app.socialscavenger.com/v1/medias/signs/FILE_EXTENSION" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
The above command returns JSON structured like this:
[
{
"signature": "https://ss-staging.s3.amazonaws.com/uploads/de3d2b601b...42d05eb02a2d.jpg?x-amz-acl=pub...",
"uri": "https://s3.amazonaws.com/ss-staging/uploads/de3d2b601b...42d05eb02a2d.jpg",
"name": "de3d2b601b...42d05eb02a2d.jpg"
},
{
"signature": "https://ss-staging.s3.amazonaws.com/uploads/de3d2b601b5e013b...d05eb02a2d-m.jpg?x-amz-acl=pub...",
"uri": "https://s3.amazonaws.com/ss-staging/uploads/de3d2b601b5e013b...d05eb02a2d-m.jpg",
"name": "de3d2b601b5e013b...d05eb02a2d-m.jpg"
},
{
"signature": "https://ss-staging.s3.amazonaws.com/uploads/de3d2b601b5e013bc12042d05eb0...-h.jpg?x-amz-acl=pub...",
"uri": "https://s3.amazonaws.com/ss-staging/uploads/de3d2b601b5e013bc12042d05eb0...-h.jpg",
"name": "de3d2b601b5e013bc12042d05eb0...-h.jpg"
}
]
This endpoint will provide a set of signatures, one for each quality level, for use in uploading media directly to s3.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/medias/signs/FILE_EXTENSION
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
file_extension | nil | The file extension for the medias you want to upload. Eg. mp4 | required |
Response Codes
Code | Meaning |
---|---|
200 | A set of signatures was returned. |
401 | Unauthorized. |
Upload Rich Media to S3
curl -v -T FILE_NAME.FILE_EXTENSION 'SIGNATURE'
The above command returns a HTTP status code.
The upload action is direct to s3, using the signature url as the destination.
Consumed by Player
and Builder
apps.
HTTP Request
PUT SIGNATURE
Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
file_name | nil | The name of the file on your local system. | required |
file_extension | nil | The file extension for the media you want to upload. Eg. mp4 | required |
signature | nil | The url in the signature attribute from the signing call. | required |
Response Codes
Code | Meaning |
---|---|
200 | Upload was successful. |
401 | Unauthorized. |
Upload Image
curl "https://app.socialscavenger.com/v1/proxy/upload.json" \
-X POST \
-H "X-Whitelabel: ss" \
-F "file=@/Users/paulcowles/Desktop/test.png" \
-i
The above command returns a HTTP status code or json like:
{
"link": "https://ss....png"
}
The upload action is a proxy to s3, accepting an image file. Currently, there is a 1MB limit to the image size.
HTTP Request
POST https://app.socialscavenger.com/v1/proxy/upload.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
file | nil | The file on your local system. | required |
Response Codes
Code | Meaning |
---|---|
200 | Upload was successful. |
400 | Bad request, missing file. |
412 | File not an image. |
Retrieve Base64 of Image
curl "https://app.socialscavenger.com/v1/proxy/img" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"u": "URL"}' \
-i
The above command returns the base64 encoding of the image:
data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4QBYRXhpZgAATU0AKgAAAAgAAgESAAMA
AAABAAEAAIdpAAQAAAABAAAAJgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAAB
AAAOUKADAAQAAAABAAAIDgAAAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEB...
This can then be used in HTML as:
<img src='data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4QBYRXhpZgAATU0AKgAAAAgAAgESAAMA
AAABAAEAAIdpAAQAAAABAAAAJgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAAB
AAAOUKADAAQAAAABAAAIDgAAAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEB...'/>
This endpoint will generate and return a stringified version of the task image.
Consumed by Player
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/proxy/img
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
u | nil | The url to the PNG, JPG, or GIF image. | required |
Response Codes
Code | Meaning |
---|---|
200 | The base64 string encoding of the image. |
401 | Unauthorized. |
Generate Image
curl "https://app.socialscavenger.com/v1/proxy/generate.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"prompt": "A cat"}' \
-i
The above command returns a HTTP status code or json like:
{
"uuid": "44f06cb051e3013db8...",
"extension": "png",
"url": "https://....png"
}
The generate action is a proxy to a generative AI, converting text to image or video.
HTTP Request
POST https://app.socialscavenger.com/v1/proxy/generate.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
prompt | nil | Instructions for generation of media by AI. | required |
generate_type | 1 | One of 1 (photo), 2 (video). | optional |
Response Codes
Code | Meaning |
---|---|
200 | Generation was successful. |
400 | Bad request, missing prompt. |
404 | Generation type not yet supported. |
503 | The generation is not available due to a partner service being unavailable. |
Non Player Characters
An NPC is an AI game character. You cannot play them, they have their own minds.
Games have a set of non player characters attached to them.
Non player characters interact with players via chat.
Create Non Player Character
curl "https://app.socialscavenger.com/v1/npcs.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"media_uuid": "MEDIA_UUID", "media_extension": "MEDIA_EXTENSION", "game_id": GAME_ID, "prompt": "PROMPT", "name": "NAME"}' \
-i
The above command returns an HTTP status code.
This endpoint will add a non player character. You must attach a NPC to a game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/npcs.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to attach the NPC to. | required |
media_uuid | nil | The uuid of the media uploaded to s3. | optional |
media_extension | nil | The file extension for the media uploaded to s3. | optional |
name | nil | A name for the NPC. | optional |
prompt | nil | Instructions for the NPC AI brain. | optional |
unlock_by_task_ids | nil | The id numbers, and optionally specific answers, of the tasks that unlock this task. The format is id_1;a_1:a_2,id_2;a_3:a_4 For multiple choice and trivia tasks being referenced, if specific answers are not provided, all answers are accepted for unlocking purposes. | optional |
unlock_by_location_radius | 50 | Distance in meters from the NPC upon which it will respond to a player. | optional |
latitude | nil | The gps latitude of the NPC. | optional |
longitude | nil | The gps longitude of the NPC. | optional |
timer | 0 | 0 means no timer. Any other integer value is the number of seconds the player has to interact with the NPC. | optional |
interactions | 0 | 0 means no limit. Any other integer value is the maximum number of interactions the player can have with the NPC. | optional |
interactions_decrement_points | false | Whether or not to inversely decrement points based on interaction count. | optional |
bio | nil | The bio for the NPC that will be shared with the players. | optional |
voice | nil | The voice to use for the NPC. | optional |
Response Codes
Code | Meaning |
---|---|
201 | An NPC has been created and added to the game. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.npc.create | Emitted after a non player character is created. |
Delete Non Player Character
curl "https://app.socialscavenger.com/v1/npcs/ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
If the system was able to delete the non player character you will get a 200 http status code in the response.
This endpoint deletes a non player character as specified by the NPC ID
. You must be a game coordinator or administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/npcs/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id for the NPC. | required |
game_id | nil | The id for the game you wish to attach the NPC to. | required |
Response Codes
Code | Meaning |
---|---|
200 | The NPC has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.npc.delete | Emitted after a NPC is deleted. |
Introduce a Non Player Character
curl "https://app.socialscavenger.com/v1/introductions.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"team_id": TEAM_ID, "npc_id": NPC_ID, "game_id": GAME_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will introduce a non player character to a team, if not already done. It should be called whenever a geofence is crossed into an NPC's radius of presence.
Consumed by Player
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/introductions.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game. | required |
team_id | nil | The team id of the player/caller. | required |
npc_id | nil | The id for the NPC. | required |
latitude | nil | The latitude of the player/caller. | required |
longitude | nil | The longitude of the player/caller. | required |
Response Codes
Code | Meaning |
---|---|
200 | The NPC has already been introduced previously. |
201 | An NPC introduction has been created. |
401 | Unauthorized. |
404 | The game, team or NPC is not found or latitude and longitude not provided. |
422 | We were unable to process the introduction. |
Related Events
Source | Comment |
---|---|
ss.introduction.create | Emitted after a non player character introduction is created. |
Retrieve Non Player Characters
curl "https://app.socialscavenger.com/v1/npcs.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"game": {
"id": 785
},
"npcs": [
{
"created_at": "2023-06-27T07:41:24Z",
"game_id": 785,
"id": 1,
"media_extension": "png",
"media_url": "https://ss-assets.socialscavenger.com/images/robot.png",
"media_uuid": "robot",
"name": "Non Player Character 733",
"prompt": "You're a NPC in a game. Your name is Non Player Character 733. You know that the code to the safe is 8333. Do not share it unless someone asks you specifically for it.",
"updated_at": "2023-06-27T07:41:24Z"
}
]
}
This endpoint will list the non player characters for the game.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/npcs.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game the non player characters are attached to. | required |
personalizations | nil | One of 0 (raw) or 1 (personalizations applied). | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of non player characters for the game are returned. |
401 | Unauthorized. |
404 | The game is not found. |
Update Non Player Character
curl "https://app.socialscavenger.com/v1/npcs/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"name": "NAME", "game_id": GAME_ID}' \
-i
If the system was able to update the non player character you will get a 200 http status code in the response.
This endpoint will update an existing non player character. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/npcs/ID.json
Query Parameters
See the list of attributes in the Create Non Player Character section. Note, game_id is required.
Response Codes
Code | Meaning |
---|---|
200 | The non player character has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The non player character or game is not found. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.npc.update | Emitted after successfully updating the non player character. |
Nubs
A Nub is a small piece by definition. A set of Nubs is a collection of small pieces.
Games and Tasks can have a set of ordered nubs attached to them.
A Nub can be a photo, video, AI prompt or chunk. A Nub can also be a combination of photo or video and AI prompt or photo or video and chunk or AI prompt and chunk. If the Nub is a photo or video, it is defined by its uuid and file extension. If the Nub has a chunk it is a blob of textual information such as HTML. If the Nub has an AI prompt, after successful generation, it will have either photo or video as media or text as chunk.
Create Nub
curl "https://app.socialscavenger.com/v1/nubs.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"media_uuid": "MEDIA_UUID", "media_extension": "MEDIA_EXTENSION", "game_id": GAME_ID, "task_id": TASK_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will add a nub. You must attach a nub to either a task or game. A nub at minimum must have either a media_uuid and media_extension or a chunk. To attach to a game, submit only game_id. To attach to a task, submit with game_id and task_id.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/nubs.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to attach the nub to. | required |
task_id | nil | The id for the task you wish to attach the nub to. | optional |
media_uuid | nil | The uuid of the media uploaded to s3. | optional |
media_extension | nil | The file extension for the media uploaded to s3. | optional |
chunk | nil | A text blob. | optional |
prompt | nil | Instructions for generation of media or text by AI. | optional |
generate_type | 1 | One of 0 (text), 1 (photo), 2 (video). | optional |
position | 0 | The position in the set of nubs for the game or task. | optional |
Response Codes
Code | Meaning |
---|---|
201 | A nub has been created and added to the game or task. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game or task is not found. |
405 | A value for generate_type is unacceptable. |
406 | The nub must attach to a game or task and have either a media_uuid and media_extension pair or a chunk. |
502 | The nub could not be processed due to the calling user being over the generation limits for prompting AI generation. |
503 | The nub is not available due to a partner service being unavailable. |
Related Events
Source | Comment |
---|---|
ss.nub.create | Emitted after a nub is created. |
ss.game.update | Emitted if nub is attached to a game. |
ss.task.update | Emitted if nub is attached to a task. |
Delete Nub
curl "https://app.socialscavenger.com/v1/nubs/ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
If the system was able to delete the nub you will get a 200 http status code in the response.
This endpoint deletes a nub as specified by the nub ID
. You must be a game administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/nubs/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id of the nub. | required |
Response Codes
Code | Meaning |
---|---|
200 | The nub has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.nub.delete | Emitted after a nub is deleted. |
Retrieve Nubs
curl "https://app.socialscavenger.com/v1/nubs.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"nubs": [
{
"id": 4,
"task_id": null,
"game_id": 785,
"media_uuid": "paul",
"media_extension": "jpg",
"media_url": "https://...mp4",
"chunk": null,
"prompt": null,
"generate_type": 1,
"position": 0,
"created_at": "2022-11-15T22:21:58Z",
"updated_at": "2022-11-15T22:21:58Z"
}
],
"game": {
"id": 785
}
}
This endpoint will list the nubs for the game or task. Personalizations will NOT be applied.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/nubs.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game the nubs are attached to. | required |
task_id | nil | The id for the task the nubs are attached to. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of nubs for the game or task are returned. |
401 | Unauthorized. |
404 | The game or task is not found. |
Update Nub
curl "https://app.socialscavenger.com/v1/nubs/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"chunk": "CHUNK"}' \
-i
If the system was able to update the nub you will get a 200 http status code in the response.
This endpoint will update an existing nub. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/nubs/ID.json
Query Parameters
See the list of attributes in the Create Nub section. Note, game_id is required.
Response Codes
Code | Meaning |
---|---|
200 | The nub has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The nub is not found. |
405 | A value for generate_type is unacceptable. |
422 | The update could not be processed. |
502 | The nub could not be processed due to the calling user being over the generation limits for prompting AI generation. |
503 | The nub is not available due to a partner service being unavailable. |
Related Events
Source | Comment |
---|---|
ss.nub.update | Emitted after successfully updating the nub. |
Filtered Nubs
curl "https://app.socialscavenger.com/v1/nubs/filtered.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"nubs": [
{
"id": 4,
"task_id": null,
"game_id": 785,
"media_uuid": "paul",
"media_extension": "jpg",
"media_url": "https://...mp4",
"chunk": null,
"prompt": null,
"generate_type": 1,
"position": 0,
"created_at": "2022-11-15T22:21:58Z",
"updated_at": "2022-11-15T22:21:58Z"
}
],
"game": {
"id": 785
}
}
This endpoint will list the filtered set of nubs for the game or task. Personalizations will be applied.
Consumed by Player
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/nubs/filtered.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game the nubs are attached to. | required |
task_id | nil | The id for the task the nubs are attached to. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of nubs for the game or task are returned. |
401 | Unauthorized. |
404 | The game or task is not found. |
Personalizations
Create Personalization
curl "https://app.socialscavenger.com/v1/personalizations.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "key": "KEY", "value": "VALUE"}' \
-i
The above command returns JSON structured like this:
{
"id": 1,
"key": "First Name",
"value": "Paul"
}
This endpoint creates a new personalization key/value pair for the game specified. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
For example, if you would like to substitute First Name
for Paul
then create a key/value pair.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/personalizations.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
key | nil | The substitution key. | required |
value | nil | The substitution value. | required |
Response Codes
Code | Meaning |
---|---|
201 | A personalization has been created. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
406 | Not acceptable as either the key and value are both empty or the key is not lowercase letters only. |
Related Events
Source | Comment |
---|---|
ss.personalization.create | Emitted after a personalization is created. |
Retrieve Personalizations
curl "https://app.socialscavenger.com/v1/personalizations.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"game": {
"id": 785
},
"personalizations": [
{
"id": 1,
"key": "First Name",
"value": "Paul"
}
]
}
This endpoint retrieves a list of all personalization key/value pairs for a particular game as specified by the game unlock code or the game id. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/personalizations.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | A list of personalizations for the game are returned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
Update Personalization
curl "https://app.socialscavenger.com/v1/personalizations/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "key": "KEY", "value": "VALUE"}' \
-i
If the system was able to update the personalization you will get a 200 http status code in the response.
This endpoint updates a personalization key/value pair as determined by the personalization id
. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/personalizations/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
id | nil | The id for the personalization key/value pair. | required |
key | nil | The substitution key. | required |
value | nil | The substitution value. | required |
Response Codes
Code | Meaning |
---|---|
200 | The personalization has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game or personalization is not found. |
406 | The personalization id is not acceptable or the key is not lowercase letters only. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.personalization.update | Emitted after a personalization is updated. |
Delete Personalization
curl "https://app.socialscavenger.com/v1/personalizations/ID.json" \
-X DELETE \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
If the system was able to delete the personalization you will get a 200 http status code in the response.
This endpoint deletes a personalization key/value pair as determined by the personalization id
. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/personalizations/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
id | nil | The id for the personalization key/value pair. | required |
Response Codes
Code | Meaning |
---|---|
200 | The personalization has been deleted. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game or personalization is not found. |
406 | The personalization id is not acceptable. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.personalization.delete | Emitted after a personalization is deleted. |
Players
Create Player
curl "https://app.socialscavenger.com/v1/teams/TEAM_ID/player.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "email": "EMAIL"}' \
-i
The above command returns an HTTP status code or JSON structured like this:
{
"id": 1,
"email": "system@soci...avenger.com",
"name": "Anonymous",
"super_admin": false
}
This endpoint will add a player to a team, creating them if they do not yet exist. You must be a member of the team, game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint. If you are a game administrator or system super administrator, it will move an existing player to the team provided.
Consumed by Player
and Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/teams/TEAM_ID/player.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
team_id | nil | The id for the team you wish to add a player. | required |
nil | The email address of the player. | required |
Response Codes
Code | Meaning |
---|---|
200 | Player is already created and on team. |
201 | A player has been created and added to the game and team. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game or team is not found. |
422 | Unable to create a player. |
Related Events
Source | Comment |
---|---|
ss.user.create | Emitted after a player is created. |
Retrieve Players
You can get a list of all the players in a game by paginating through a game's list of teams.
Update Player
See the User documentation for information on updating a player or user record.
Delete Player
curl "https://app.socialscavenger.com/v1/teams/TEAM_ID/player.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "player_id": PLAYER_ID}' \
-i
If the system was able to remove the player from the team you will get a 200 http status code in the response.
This endpoint will remove a player from a team. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint. The player will remain joined to the game.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/teams/TEAM_ID/player.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
team_id | nil | The id for the player's team. | required |
player_id | nil | The id for the player you wish to remove from the team. | required. |
Response Codes
Code | Meaning |
---|---|
200 | The player has been removed from the team. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game, team or player is not found. |
Related Events
Source | Comment |
---|---|
ss.team.update | Emitted after the player is removed from the team. |
Positions
Create a Position Marker
curl "https://app.socialscavenger.com/v1/positions.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "latitude": LATITUDE, "longitude": LONGITUDE}'
The above command returns JSON structured like this:
{
"id": 1,
"user_id": 1,
"game_id": 785,
"team_id": 3,
"latitude": 47.369285,
"longitude": -121.280063,
"created_at": "2023-01-31T20:49:26Z",
"pagination_token": 1675198166
}
This endpoint logs a position marker for the caller in a game.
Consumed by Player
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/positions.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The game id to which the position is being logged. | required |
latitude | nil | The gps latitude of the position. | required |
longitude | nil | The gps longitude of the position. | required |
Response Codes
Code | Meaning |
---|---|
201 | Position logged successfully. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a player in the game, or a game coordinator, game administrator or system super administrator. |
404 | Game, latitude, longitude not found or not provided. |
422 | Position was not able to be created. |
Related Events
Source | Comment |
---|---|
ss.position.create | Emitted after successfully saving the position. |
Retrieve Positions
curl "https://app.socialscavenger.com/v1/positions.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "before": "PAGINATION_TOKEN", "page_size": PAGE_SIZE, "style": "latest"}' \
-i
The above command returns JSON structured like this:
{
"positions": [
{
"id": 1,
"user_id": 1,
"game_id": 785,
"team_id": 3,
"latitude": 47.369285,
"longitude": -121.280063,
"created_at": "2023-01-31T20:49:26Z",
"pagination_token": 1675198166
}
],
"game": {
"id": 1,
"teams": 379,
"players": 514
}
}
This endpoint lists all the recorded positions for teams in a game. It is capable of pagination. In the meta attribute, you will find count (positions count), teams (teams count), and players (player count).
Consumed by Player
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/positions.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
before | nil | The pagination token in the last payload. | optional |
page_size | 10 | The page size you wish to receive in the payload. | optional |
team_id | nil | The id for the team you wish to list positions for. | optional |
game_id | nil | The id for the game you wish to list positions for. | required |
style | all | One of all or latest. All is good for displaying paths, while latest is good for maps. | optional |
Response Codes
Code | Meaning |
---|---|
200 | List of positions returned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a player in the game, or a game coordinator, game administrator or system super administrator. |
404 | A list of positions could not be returned as the game or team was not found. |
Purchases
Purchase Library
curl "https://app.socialscavenger.com/v1/games/GAME_ID/library.json" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"cost": COST, "stripe_id": "STRIPE_ID"}' \
-i
The above command returns an HTTP response code.
This endpoint will perform the transaction to open access to the platform task library.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/library.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to purchase library access for. | required. |
cost | nil | The cost of the purchase in currency as defined by platform (typically usd). | required. |
stripe_id | nil | The id of the stripe payment method. | required. |
Response Codes
Code | Meaning |
---|---|
200 | Purchase was successful. |
400 | Bad request. Cost is 0 or missing stripe details. |
401 | Unauthorized. |
402 | Card declined. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
406 | Auth with Stripe invalid. |
500 | A server error has occurred. Possibly an invalid stripe_id. |
501 | Invalid parameters to Stripe API. |
502 | Rate limited by Stripe. |
503 | Stripe generic error. |
504 | Network to Stripe down. |
Related Events
Source | Comment |
---|---|
ss.purchase.library | Emitted after the library is purchased. |
Purchase Branding
curl "https://app.socialscavenger.com/v1/games/GAME_ID/branding.json" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"cost": COST, "stripe_id": "STRIPE_ID"}' \
-i
The above command returns an HTTP response code.
This endpoint will perform the transaction to open access to custom branding for a game.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/branding.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to purchase library access for. | required. |
cost | nil | The cost of the purchase in currency as defined by platform (typically usd). | required. |
stripe_id | nil | The id of the stripe payment method. | required. |
Response Codes
Code | Meaning |
---|---|
200 | Purchase was successful. |
400 | Bad request. Cost is 0 or missing stripe details. |
401 | Unauthorized. |
402 | Card declined. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
406 | Auth with Stripe invalid. |
500 | A server error has occurred. Possibly an invalid stripe_id. |
501 | Invalid parameters to Stripe API. |
502 | Rate limited by Stripe. |
503 | Stripe generic error. |
504 | Network to Stripe down. |
Related Events
Source | Comment |
---|---|
ss.purchase.branding | Emitted after the branding is purchased. |
Purchase Reels
curl "https://app.socialscavenger.com/v1/games/GAME_ID/reels.json" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"cost": COST, "stripe_id": "STRIPE_ID"}' \
-i
The above command returns an HTTP response code.
This endpoint will perform the transaction to open access to reels for a particular game.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/reels.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to purchase library access for. | required. |
cost | nil | The cost of the purchase in currency as defined by platform (typically usd). | required. |
stripe_id | nil | The id of the stripe payment method. | required. |
Response Codes
Code | Meaning |
---|---|
200 | Purchase was successful. |
400 | Bad request. Cost is 0 or missing stripe details. |
401 | Unauthorized. |
402 | Card declined. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
406 | Auth with Stripe invalid. |
422 | The game cannot be updated. |
500 | A server error has occurred. Possibly an invalid stripe_id. |
501 | Invalid parameters to Stripe API. |
502 | Rate limited by Stripe. |
503 | Stripe generic error. |
504 | Network to Stripe down. |
Related Events
Source | Comment |
---|---|
ss.purchase.reels | Emitted after the reels feature is purchased. |
Purchase Teams
curl "https://app.socialscavenger.com/v1/games/GAME_ID/teams.json" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"cost": COST, "stripe_id": "STRIPE_ID"}' \
-i
The above command returns an HTTP response code.
This endpoint will perform the transaction to open a game to additional teams. By default a game is only accessible by its creator.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/teams.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to purchase library access for. | required. |
cost | nil | The cost of the purchase in currency as defined by platform (typically usd). | required. |
stripe_id | nil | The id of the stripe payment method. | required. |
purchased_players | nil | Number of teams being purchased. | required. |
Response Codes
Code | Meaning |
---|---|
200 | Purchase was successful. |
400 | Bad request. Cost is 0 or missing stripe details. |
401 | Unauthorized. |
402 | Card declined. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
406 | Auth with Stripe invalid. |
500 | A server error has occurred. Possibly an invalid stripe_id. |
501 | Invalid parameters to Stripe API. |
502 | Rate limited by Stripe. |
503 | Stripe generic error. |
504 | Network to Stripe down. |
Related Events
Source | Comment |
---|---|
ss.purchase.teams | Emitted after the teams license is purchased. |
Purchase Donation
curl "https://app.socialscavenger.com/v1/games/GAME_ID/donations.json" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"cost": COST, "stripe_id": "STRIPE_ID"}' \
-i
The above command returns an HTTP response code.
This endpoint will perform the transaction to donate funds to a game's creator.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/donations.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to purchase library access for. | required. |
cost | nil | The cost of the purchase in currency as defined by platform (typically usd). | required. |
stripe_id | nil | The id of the stripe payment method. | required. |
Response Codes
Code | Meaning |
---|---|
200 | Purchase was successful. |
400 | Bad request. Cost is 0, email is blank or malformed, or missing stripe details. |
401 | Unauthorized. |
402 | Card declined. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
406 | Auth with Stripe invalid. |
500 | A server error has occurred. Possibly an invalid stripe_id. |
501 | Invalid parameters to Stripe API. |
502 | Rate limited by Stripe. |
503 | Stripe generic error. |
504 | Network to Stripe down. |
Related Events
Source | Comment |
---|---|
ss.purchase.donation | Emitted after a donation is made. |
Liberate Game
curl "https://app.socialscavenger.com/v1/games/GAME_ID/liberate.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
The above command returns an HTTP response code.
This endpoint will open all paywalled services for a game. The game will be open for up to 10,000 teams, custom branding, generation of reels, and access to the library.
Consumed by Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/games/GAME_ID/liberate.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to purchase library access for. | required. |
packages | teams, branding, library | One or more of branding, teams, reels, library. Comma delimited. | optional. |
count | 10000 | for packages that need a scale, such as teams eg. 100 | optional. |
Response Codes
Code | Meaning |
---|---|
200 | Liberation was successful. |
401 | Unauthorized. |
403 | You must be a system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.purchase.branding | Emitted after the branding is purchased. |
ss.purchase.library | Emitted after the library is purchased. |
ss.purchase.reels | Emitted after the reels feature is purchased. |
ss.purchase.teams | Emitted after the teams license is purchased. |
System
Retrieve QR Code
curl "https://app.socialscavenger.com/v1/services/qr.png?whitelabel=ss&game_id=GAME_ID" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID, "TASK_ID": TASK_ID, "STYLE": "legacy"}' \
-o qr.png
The above command returns a binary PNG QR code.
This endpoint will generate and return a static QR code for use in handing off a team from one phone to another, joining a game, or completing the task.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/services/qr.png
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
task_id | nil | The id for the task. | optional |
game_id | nil | The id for the game. | required |
style | legacy | One of legacy, handoff, join or complete. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A QR code image was returned. |
404 | A necessary pre-requisuite, such as task or game, was not found. |
Email a Social Scavenger Player
curl "https://app.socialscavenger.com/v1/services/email/player.json" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-d '{"name": "NAME", "email": "EMAIL", "subject": "SUBJECT", "txt": "TXT", "html": "HTML"}' \
-i
The above command returns an http status code.
This endpoint sends an email with TXT and/or HTML body to a Social Scavenger player with the NAME and EMAIL provided.
HTTP Request
POST https://app.socialscavenger.com/v1/services/email/player.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
name | nil | Name of recipient. | required |
nil | Email of recipient. | required | |
subject | nil | Subject of email. | required |
txt | nil | Text version of email body. | optional |
html | nil | HTML version of email body. | optional |
Response Codes
Code | Meaning |
---|---|
200 | Email has been sent. |
422 | Unable to process and send email. |
Email Social Scavenger
curl "https://app.socialscavenger.com/v1/services/email/company.json" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-d '{"name": "NAME", "email": "EMAIL", "txt": "TXT", "html": "HTML"}' \
-i
The above command returns an http status code.
This endpoint sends an email with TXT and/or HTML body to Social Scavenger from the NAME and EMAIL provided.
HTTP Request
POST https://app.socialscavenger.com/v1/services/email/company.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
name | nil | Name of sender. | required |
nil | Email of sender. | required | |
txt | nil | Text version of email body. | optional |
html | nil | HTML version of email body. | optional |
utm_source | nil | The inbound referrer. | optional |
utm_medium | nil | The inbound channel. | optional |
utm_campaign | nil | The inbound campaign. | optional |
utm_content | nil | The inbound group or set. | optional |
utm_term | nil | The inbound terms. | optional |
Response Codes
Code | Meaning |
---|---|
200 | Email has been sent. |
422 | Unable to process and send email. |
Eventbrite Webhook
curl "https://app.socialscavenger.com/v1/services/eventbrite/webhook.json" \
-X POST \
-H "Content-Type: application/json" \
-d '{"api_url": "API_URL", "mock": MOCK}' \
-i
The above command returns an http status code.
If mock is true, you can view the mocked Eventbrite data at:
curl "https://app.socialscavenger.com/v1/services/eventbrite/order.json" \
-X GET \
-i
curl "https://app.socialscavenger.com/v1/services/eventbrite/event.json" \
-X GET \
-i
This endpoint creates a new player and emails them their personal unlock code in order to join a particular game. It is designed to respond as a webhook to the Eventbrite platform.
HTTP Request
POST https://app.socialscavenger.com/v1/services/eventbrite/webhook.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
api_url | nil | Eventbrite object whose creation or update triggered the webhook. | required |
mock | false | Execute the webhook in test mode or not. One of true or false. | optional |
Response Codes
Code | Meaning |
---|---|
204 | Successful request. |
400 | Missing api_url parameter, so unable to load order. |
422 | Missing event mapping, unable to process order. |
Related Events
Source | Comment |
---|---|
ss.user.create | Emitted after a player is created. |
Service Status
curl "https://app.socialscavenger.com/v1/services/maintenance.json" \
-X GET \
-H "X-Whitelabel: ss" \
-i
The above command returns an http response code.
This endpoint can be queried for system status.
Consumed by Player
and Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/services/maintenance.json
Response Codes
Code | Meaning |
---|---|
200 | Platform is operational. |
500 | System is down for unknown reasons. |
503 | System is down for maintenance. |
Create Super Administrator
curl "https://app.socialscavenger.com/v1/services/administrator.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"email": "EMAIL"}' \
-i
The above command returns an HTTP status code.
This endpoint will create a new platform super administrator.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/services/administrator.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
nil | The email of the user account to make a super administrator. | required |
Response Codes
Code | Meaning |
---|---|
200 | The user has been made a platform super administrator. |
401 | Unauthorized. |
403 | You must be a platform super administrator. |
404 | The player cannot be found. |
422 | The player update cannot be processed. |
Related Events
Source | Comment |
---|---|
ss.super.create | Emitted after the platform super administrator has been created. |
Delete Super Administrator
curl "https://app.socialscavenger.com/v1/services/administrator.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"email": "EMAIL"}' \
-i
The above command returns an HTTP status code.
This endpoint will delete an existing platform super administrator.
HTTP Request
DELETE https://app.socialscavenger.com/v1/services/administrator.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
nil | The email of the user account to make a super administrator. | required |
Response Codes
Code | Meaning |
---|---|
200 | The user is no longer platform super administrator. |
401 | Unauthorized. |
403 | You must be a platform super administrator. |
404 | The player cannot be found. |
422 | The player update cannot be processed. |
Related Events
Source | Comment |
---|---|
ss.super.delete | Emitted after the platform super administrator has been deleted. |
Retrieve Timezones
curl "https://app.socialscavenger.com/v1/timezones.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-i
The above command returns JSON structured like this:
[
[
"Midway Island (GMT-11:00)",
"Midway Island"
],
[
"Hawaii (GMT-10:00)",
"Hawaii"
]
]
This endpoint will list the timezones supported by the system.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/timezones.json
Response Codes
Code | Meaning |
---|---|
200 | A list of timezones are returned. |
Emulate HTTP Status Response Code
curl "https://app.socialscavenger.com/v1/services/emulate/status_code.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"code": 404}' \
-i
The above command returns an HTTP status code.
This endpoint allows you to simulate HTTP response codes for testing purposes.
HTTP Request
GET https://app.socialscavenger.com/v1/services/emulate/status_code.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | 200 | The HTTP status code you want to receive back. | optional |
Response Codes
Code | Meaning |
---|---|
200 | Default response code |
422 | Code provided but not in platform set |
Tags
Create Tag in Library
curl "https://app.socialscavenger.com/v1/tags.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"user_id": "USER_ID", "user_type": "email", "password": "PASSWORD", "task_id": TASK_ID, "label": "LABEL", "game_id": GAME_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will add a tag to the platform task library. You must attach the tag to a task.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/tags.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
task_id | nil | The id for the task you wish to link with the tag. | required |
game_id | nil | The id for the game in which the task lives. | required |
label | nil | The tag or label. | required |
Response Codes
Code | Meaning |
---|---|
201 | A tag has been created and added to the task. |
400 | Label was missing or empty, forbidden. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The task is not found. |
Related Events
Source | Comment |
---|---|
ss.task.update | Emitted after a task is updated. |
Retrieve Tags
curl "https://app.socialscavenger.com/v1/tags.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"user_id": "USER_ID", "user_type": "email", "password": "PASSWORD"}' \
-i
The above command returns JSON structured like this:
[{
"label": "70s"
}, {
"label": "80s"
}, {
"label": "90s"
}]
This endpoint will list the tags already present in the platform task library.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/tags.json
Response Codes
Code | Meaning |
---|---|
200 | A list of tasks for the tags are returned. |
401 | Unauthorized. |
Tasks
Create Task with AI
curl "https://app.socialscavenger.com/v1/tasks/suggest.json" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON (See Create Task).
This endpoint will create a new task for a particular game as specified by the game unlock code or the game id. It will add a new task by suggesting one, if it has an idea. The new task will have its title, description and image suggested by the AI. The other settings will need to be configured manually.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/tasks/suggest.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
201 | A task has been created. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
501 | The AI suggested something, but in an unexpected way. |
503 | The AI competely failed to suggest a task or challenge. |
Related Events
Source | Comment |
---|---|
ss.task.create | Emitted after a task is created. |
Create Task
curl "https://app.socialscavenger.com/v1/tasks.json" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"id": 171165,
"address": null,
"description": null,
"ends_at": null,
"fullscreen": 0,
"hide_answers": 0,
"hide_locked": 0,
"hints": 0,
"hint_1": null,
"hint_1_points": 1,
"hint_2": null,
"hint_2_points": 1,
"hint_3": null,
"hint_3_points": 1,
"hint_4": null,
"hint_4_points": 1,
"hint_5": null,
"hint_5_points": 1,
"latitude": null,
"longitude": null,
"multiplechoice": null,
"points": 1,
"quantity": 0,
"qr_url": null,
"reel_enabled": 1,
"reel_intro": null,
"reward_title": null,
"reward_description": null,
"starts_at": null,
"task_subtype": 0,
"task_type": 1,
"timer": 0,
"trivia": null,
"trivia_points_1": 1,
"trivia_points_2": 9999,
"trivia_points_3": 9999,
"trivia_points_4": 9999,
"trivia_points_5": 9999,
"trivia_points_unlimited": 9999,
"name": "Untitled",
"unlock_by_location_radius": 0,
"unlock_by_task_id": null,
"unlock_by_task_ids": null,
"unlock_by_task_txt": null,
"video_length": 30,
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 0,
"height": 0
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 0,
"height": 0
},
{
"name": "sticker",
"url": "https://ss....png",
"width": 0,
"height": 0,
"fullscreen": true
},
{
"name": "correct",
"url": null,
"width": 0,
"height": 0
},
{
"name": "incorrect",
"url": null,
"width": 0,
"height": 0
},
{
"name": "reward",
"url": null,
"width": 0,
"height": 0
}
],
"videos": [
{
"name": "correct",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
},
{
"name": "incorrect",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}
]
},
"realities": [{
"id": 300960,
"animation_name": null,
"duration_seconds": null,
"scale": null,
"delay_seconds": null,
"style": null,
"chain": null,
"model_url": null
}, {
"id": 300961,
"animation_name": null,
"duration_seconds": null,
"scale": null,
"delay_seconds": null,
"style": null,
"chain": null,
"model_url": null
}, {
"id": 300962,
"animation_name": null,
"duration_seconds": null,
"scale": null,
"delay_seconds": null,
"style": null,
"chain": null,
"model_url": null
}, {
"id": 300963,
"animation_name": null,
"duration_seconds": null,
"scale": null,
"delay_seconds": null,
"style": null,
"chain": null,
"model_url": null
}, {
"id": 300964,
"animation_name": null,
"duration_seconds": null,
"scale": null,
"delay_seconds": null,
"style": null,
"chain": null,
"model_url": null
}],
"tags": []
}
This endpoint will create a new task for a particular game as specified by the game unlock code or the game id.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/tasks.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
201 | A task has been created. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.task.create | Emitted after a task is created. |
Retrieve Task
curl "https://app.socialscavenger.com/v1/tasks/TASK_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
Returns a json payload:
{
"id": 520,
"created_at": "2011-10-05T21:32:39Z",
"updated_at": "2018-08-25T17:07:37Z",
"name": "North American - Locked",
"address": "None specified.",
"description": "Get a photo of ...",
"ends_at": null,
"hide_answers": false,
"hide_locked": false,
"hints": false,
"hint_1": "",
"hint_1_points": 1,
"hint_2": "",
"hint_2_points": 1,
"hint_3": "",
"hint_3_points": 1,
"hint_4": "",
"hint_4_points": 1,
"hint_5": "",
"hint_5_points": 1,
"latitude": null,
"longitude": null,
"multiplechoice": null,
"points": 1,
"position": 12,
"quantity": 0,
"qr_url": null,
"reel_enabled": 1,
"reel_intro": null,
"reward_title": "",
"reward_description": "",
"starts_at": null,
"task_subtype": 0,
"task_type": 3,
"timer": 0,
"trivia": null,
"trivia_points_1": 1,
"trivia_points_2": 9999,
"trivia_points_3": 9999,
"trivia_points_4": 9999,
"trivia_points_5": 9999,
"trivia_points_unlimited": 9999,
"unlock_by_location_radius": 0,
"unlock_by_task_id": 12391,
"unlock_by_task_ids": 12391,
"unlock_by_task_txt": "Trivia - Multiple Choice",
"video_length": 30,
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss.....jpg",
"width": 0,
"height": 0
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 0,
"height": 0
},
{
"name": "sticker",
"url": "https://ss.....png",
"width": 0,
"height": 0,
"fullscreen": true
},
{
"name": "correct",
"url": null,
"width": 0,
"height": 0
},
{
"name": "incorrect",
"url": null,
"width": 0,
"height": 0
},
{
"name": "reward",
"url": null,
"width": 0,
"height": 0
}
],
"videos": [
{
"name": "correct",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
},
{
"name": "incorrect",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}
]
},
"realities": [],
"tags": []
}
This endpoint will retrieve a task in a particular game as specified by the game unlock code or the game id.
HTTP Request
GET https://app.socialscavenger.com/v1/tasks/TASK_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
task_id | nil | The task or challenge id. | required |
Response Codes
Code | Meaning |
---|---|
200 | The task. |
401 | Unauthorized. |
Retrieve Tasks for Team
curl "https://app.socialscavenger.com/v1/tasks/team.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"game": {
"id": 1,
"teams": 2,
"tasks": 12,
"unlock_requires_network": false
},
"team": {
"id": 69006,
"name": "Team 1",
"completed": 3,
"place": 2,
"points": 30,
"assets": {
"photos": [{
"name": "thumb",
"url": null,
"width": 0,
"height": 0
}]
}
},
"tasks": [{
"id": 169917,
"created_at": "2021-08-08T03:26:23Z",
"updated_at": "2021-08-16T19:54:40Z",
"name": "Fishy Fishy (One after the Other)",
"type": 2,
"subtype": 0,
"description": "Description",
"points": 10,
"html": "https://app....html",
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss-assets.socialscavenger.com/tasks/photos/thumb_169917.jpg",
"width": 75,
"height": 75
}, {
"name": "standard",
"url": "https://ss-assets.socialscavenger.com/tasks/photos/thumb_169917.jpg",
"width": 75,
"height": 75
}, {
"name": "sticker",
"url": null,
"width": 0,
"height": 0,
"fullscreen": false
}, {
"name": "correct",
"url": null,
"width": 0,
"height": 0
}, {
"name": "incorrect",
"url": null,
"width": 0,
"height": 0
}],
"videos": [{
"name": "correct",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}, {
"name": "incorrect",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}],
"ar": []
},
"locks": {
"enabled": false,
"hidden": false,
"task": {
"name": "",
"id": 0
},
"tasks": [
{
"name": "",
"id": 0,
"answers":["x","y","z"]
}
],
"location": {
"radius": 0
}
},
"location": {
"latitude": "",
"longitude": "",
"map": ""
},
"scorable": {
"trivia": {
"answers": "",
"points": [1, null, null, null, null, null],
"remaining": 0
},
"multiplechoice": {
"answers": ""
},
"correct": false
},
"previous_submissions": {
"valid": 1,
"total": 1
},
"hints": {
"enabled": false,
"configuration": [],
"points": []
},
"timer": {
"enabled": false,
"seconds": 0
},
"video": {
"limited": true,
"length": 30
},
"qr": {
"key": ""
},
"reel": "",
"teams_complete": 1,
"complete": false
}]
}
or if the game is stopped, has not yet started, or has otherwise finished, a JSON structured like this:
{
"game": {
"id": 1,
"teams": 2,
"tasks": 0
},
"team": {
"id": 69006,
"name": "Team 1",
"completed": 0,
"place": 0,
"points": 0,
"assets": {
"photos": [{
"name": "thumb",
"url": "https://app....png",
"width": 75,
"height": 75
}]
}
},
"tasks": []
}
This endpoint will retrieve a list of all the tasks for a given team in a game.
Consumed by Player
apps. Response applies Personalization
.
HTTP Request
GET https://app.socialscavenger.com/v1/tasks/team.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list tasks for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | A list of tasks, or any empty list, for the game are returned. |
401 | Unauthorized. |
404 | The game or team is not found or the authenticating player has not joined the game. |
Paginated Tasks
curl "https://app.socialscavenger.com/v1/tasks/game/GAME_ID.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"term": "TERM", "page": PAGE, "per_page": PER_PAGE}' \
-i
The above command returns JSON structured like this:
{
"tasks": [{
"id": 162286
}],
"meta": {
"term": "",
"page": 1,
"pages": 16,
"per_page": 10,
"count": 156
}
}
This endpoint will retreive a list of the player's tasks for the game, filtered by a search term and paginated.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/tasks/game/GAME_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to list tasks for. | required |
term | nil | A search term that must be present in the task name or description. | optional |
page | 1 | Page of results you which to retrieve. | optional |
per_page | 25 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of tasks, or any empty list, for the game are returned. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game is not found. |
Retrieve Tasks for Game
curl "https://app.socialscavenger.com/v1/tasks.json?code=UNLOCKCODE" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
The above command returns JSON structured like this:
{
"id": 7018,
"tasks": [{
"id": 166330,
"name": "Summer is Here!"
}, {
"id": 166331,
"name": "Being Furry is Great"
}]
}
This endpoint retrieves a list of all tasks in a particular game as specified by the game unlock code or the game id.
HTTP Request
GET https://app.socialscavenger.com/v1/tasks.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list tasks for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | A list of tasks for the game are returned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a player in the game, or a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
Update Task
curl "https://app.socialscavenger.com/v1/tasks/ID.json" \
-X PUT \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID, "points": POINTS}' \
-i
If the system was able to update the task you will get a 200 http status code in the response.
This endpoint will update an existing task in a particular game as specified by the game unlock code or the game id.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/tasks/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to update the task for. | requires code or game_id |
game_id | nil | The id for the game you wish to update the task for. | requires code or game_id |
address | nil | The physical address the challenge is linked to, either as a suggestion or a GPS lock. | optional |
description | nil | The preview description of the challenge. May contain HTML and Javascript. | optional |
starts_at | nil | The start date and time (iso8601) for the challenge. | optional |
ends_at | nil | The end date and time (iso8601) for the challenge. | optional |
fullscreen | nil | For a sticker overlay, lock it to fullscreen or not. 0/false or 1/true. | optional |
hide_answers | nil | Sets whether or not answers should show up in the stream or not. 0/false or 1/true. | optional |
hide_locked | nil | Sets whether or not the task should be hidden from the challenge list if locked. 0/false or 1/true. | optional |
hints | nil | Sets whether or not the task has hints enabled. 0/false or 1/true. | optional |
hint_1 | nil | The text displayed for hint 1. | optional |
hint_1_points | nil | The points penalty for using hint 1. | optional |
hint_2 | nil | The text displayed for hint 2. | optional |
hint_2_points | nil | The points penalty for using hint 2. | optional |
hint_3 | nil | The text displayed for hint 3. | optional |
hint_3_points | nil | The points penalty for using hint 3. | optional |
hint_4 | nil | The text displayed for hint 4. | optional |
hint_4_points | nil | The points penalty for using hint 4. | optional |
hint_5 | nil | The text displayed for hint 5. | optional |
hint_5_points | nil | The points penalty for using hint 5. | optional |
latitude | nil | The latitude of the challenge location. | optional |
longitude | nil | The longitude of the challenge location. | optional |
multiplechoice | nil | The set of multiple choice answers, comma delimited. The first in the set is the correct answer. | optional |
points | nil | The default points granted for completing the task. | optional |
position | 0 | The position in the list for the task. | optional |
quantity | nil | Limit the number of teams in the game who can complete it before it is no longer available. Start a race by creating a scarce challenge. | optional |
qr_url | nil | The URL that should be opened once the task QR code has been scanned. | optional |
task_subtype | nil | For video tasks, subtypes can be 0 (video), 1 (animated gif) or 2 (audio track only). For text tasks, subtypes can be 0 (no transformations), or 1 (transform text to image using AI). For photo tasks, subtypes can be 0 (no transformations), or 1 (transform using prompt to AI). | optional |
task_type | nil | The type of challenge, 0 (Text), 1 (Photo), 2 (Video), 3 (Sticker + Photo), 4 (QR Scan), 5 (Trivia), 6 (Multiple Choice), 7 (Augmented Reality + Photo), 8 (Augmented Reality + Video), 9 (Background + Photo), 10 (Background + Video), 11 (Path) | optional |
timer | nil | 0 means no timer. Any other integer value is the number of seconds the player has to submit a response. | optional |
trivia | nil | The set of trivia answers, comma delimited. Every item in the set is a valid correct answer. | optional |
trivia_points_1 | nil | The points granted if correct on first guess. If set to 9999, will use trivia_points_unlimited. | optional |
trivia_points_2 | nil | The points granted if correct on second guess. If set to 9999, will use trivia_points_unlimited. | optional |
trivia_points_3 | nil | The points granted if correct on third guess. If set to 9999, will use trivia_points_unlimited. | optional |
trivia_points_4 | nil | The points granted if correct on fourth guess. If set to 9999, will use trivia_points_unlimited. | optional |
trivia_points_5 | nil | The points granted if correct on fifth guess. If set to 9999, will use trivia_points_unlimited. | optional |
trivia_points_unlimited | nil | The points granted if correct on any guess. If set to 9999, will not allow unlimited guessing. | optional |
unlock_by_location_radius | 0 | Distance in meters from the challenge upon which it will unlock for a player. | optional |
unlock_by_task_id | nil | The id number of the task that must be completed before this task appears as being unlocked. | optional |
unlock_by_task_ids | nil | The id numbers, and optionally specific answers, of the tasks that unlock this task. The format is id_1;a_1:a_2,id_2;a_3:a_4 For multiple choice and trivia tasks being referenced, if specific answers are not provided, all answers are accepted for unlocking purposes. | optional |
video_length | 30 | The duration in seconds allowed for the video attachment. | optional |
reward_title | nil | The title of the reward granted upon completion of the task. | optional |
reward_description | nil | The description of the reward granted upon completion of the task. | optional |
photo_media_uuid | nil | The uuid of the media uploaded to s3 for the task photo. | optional |
photo_media_extension | nil | The file extension for the media uploaded to s3. | optional |
correct_media_uuid | nil | The uuid of the media uploaded to s3 for the task photo to show when answered correctly. | optional |
correct_media_extension | nil | The file extension for the media uploaded to s3. | optional |
incorrect_media_uuid | nil | The uuid of the media uploaded to s3 for the task photo to show when answered incorrectly. | optional |
incorrect_media_extension | nil | The file extension for the media uploaded to s3. | optional |
overlay_media_uuid | nil | The uuid of the media uploaded to s3 for the task sticker. | optional |
overlay_media_extension | nil | The file extension for the media uploaded to s3. | optional |
reward_media_uuid | nil | The uuid of the media uploaded to s3 for the task reward photo. | optional |
reward_media_extension | nil | The file extension for the media uploaded to s3. | optional |
video_media_uuid | nil | The uuid of the media uploaded to s3 for the task video. | optional |
video_media_extension | nil | The file extension for the media uploaded to s3. | optional |
ya_media_uuid | nil | The uuid of the media uploaded to s3 for the task video to show when answered correctly. | optional |
ya_media_extension | nil | The file extension for the media uploaded to s3. | optional |
naw_media_uuid | nil | The uuid of the media uploaded to s3 for the task video to show when answered incorrectly. | optional |
naw_media_extension | nil | The file extension for the media uploaded to s3. | optional |
reel_enabled | nil | If enabled, submissions to this task will be included in reels. 0/false or 1/true. | optional |
reel_intro | nil | If set, this text will be used to introduce the reel. If nil, by default the task title will be used. | optional |
arrival_image_media_uuid | nil | The uuid of the media uploaded to s3 for the task image to show upon arrival. | optional |
arrival_image_media_extension | nil | The file extension for the media uploaded to s3. | optional |
arrival_video_media_uuid | nil | The uuid of the media uploaded to s3 for the task video to show upon arrival. | optional |
arrival_video_media_extension | nil | The file extension for the media uploaded to s3. | optional |
arrival_location_radius | 0 | Distance in meters from the challenge upon which it will initiate the arrival image or video. | optional |
prompt | nil | The text prompt to be provided to the AI for transformations. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The task has been updated. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game or task is not found. |
Related Events
Source | Comment |
---|---|
ss.task.update | Emitted after a task is updated. |
Delete Task
curl "https://app.socialscavenger.com/v1/tasks/ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}'
If the system was able to delete the task you will get a 200 http status code in the response.
This endpoint will delete a task in a particular game. You must be a game administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/tasks/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The task or challenge id. | required |
game_id | nil | The id for the game the task is part of. | required |
Response Codes
Code | Meaning |
---|---|
200 | The task has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The game or task is not found. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.task.delete | Emitted after a task is deleted. |
Retrieve Task Hint
curl "https://app.socialscavenger.com/v1/tasks/TASK_ID/hint/ID.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"id": 18231,
"number": 1,
"message": "Test",
"user": {
"id": 14096
},
"game": {
"id": 5640
},
"task": {
"id": 145076
},
"team": {
"id": 47644
}
}
This endpoint will retrieve, and record use of, a hint for a particular task in a particular game.
Consumed by Player
apps. Response applies Personalization
.
HTTP Request
PATCH https://app.socialscavenger.com/v1/tasks/TASK_ID/hint/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The hint number being used. Starts at 1. | required |
task_id | nil | The task or challenge id for which the hint is being used. | required |
game_id | nil | The game id. | required |
Response Codes
Code | Meaning |
---|---|
200 | The hint was marked as used and delivered. |
401 | Unauthorized. |
404 | The game, task or team could not be found. |
Related Events
Source | Comment |
---|---|
ss.task.hint | Emitted after a task hint is granted. |
Filter Tasks by Term
curl "https://app.socialscavenger.com/v1/tasks/search.json?game_id=GAME_ID&term=TERM" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
or
curl "https://app.socialscavenger.com/v1/tasks/search.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"user_id": "USER_ID", "user_type": "email", "password": "PASSWORD", "game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"game": {
"id": 1,
"teams": 2,
"tasks": 12,
"unlock_requires_network": false
},
"team": {
"id": 69006,
"name": "Team 1",
"completed": 3,
"place": 2,
"points": 30,
"assets": {
"photos": [{
"name": "thumb",
"url": null,
"width": 0,
"height": 0
}]
}
},
"tasks": [{
"id": 169917,
"created_at": "2021-08-08T03:26:23Z",
"updated_at": "2021-08-16T19:54:40Z",
"name": "Fishy Fishy (One after the Other)",
"type": 2,
"subtype": 0,
"description": "Description",
"points": 10,
"html": "https://app....html",
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss-assets.socialscavenger.com/tasks/photos/thumb_169917.jpg",
"width": 75,
"height": 75
}, {
"name": "standard",
"url": "https://ss-assets.socialscavenger.com/tasks/photos/thumb_169917.jpg",
"width": 600,
"height": 600
}, {
"name": "sticker",
"url": null,
"width": 0,
"height": 0,
"fullscreen": false
}, {
"name": "correct",
"url": null,
"width": 0,
"height": 0
}, {
"name": "incorrect",
"url": null,
"width": 0,
"height": 0
}],
"videos": [{
"name": "correct",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}, {
"name": "incorrect",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}],
"ar": []
},
"locks": {
"enabled": false,
"hidden": false,
"task": {
"name": "",
"id": 0
},
"location": {
"radius": 0
}
},
"location": {
"latitude": "",
"longitude": "",
"map": ""
},
"scorable": {
"trivia": {
"answers": "",
"points": [1, null, null, null, null, null],
"remaining": 0
},
"multiplechoice": {
"answers": ""
},
"correct": false
},
"previous_submissions": {
"valid": 1,
"total": 1
},
"hints": {
"enabled": false,
"configuration": [],
"points": []
},
"timer": {
"enabled": false,
"seconds": 0
},
"video": {
"limited": true,
"length": 30
},
"qr": {
"key": ""
},
"reel": "",
"teams_complete": 1,
"complete": false
}]
}
or if the game is stopped, has not yet started, or has otherwise finished, a JSON structured like this:
{
"game": {
"id": 1,
"teams": 2,
"tasks": 0
},
"team": {
"id": 69006,
"name": "Team 1",
"completed": 0,
"place": 0,
"points": 0,
"assets": {
"photos": [{
"name": "thumb",
"url": "https://app....png",
"width": 75,
"height": 75
}]
}
},
"tasks": []
}
This endpoint will retreive a list of the player's tasks for the game, filtered by a search term.
Consumed by Player
apps. Response applies Personalization
.
HTTP Request
GET https://app.socialscavenger.com/v1/tasks/search.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list tasks for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
term | nil | A search term that must be present in the task name or description. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of tasks, or any empty list, for the game are returned. |
401 | Unauthorized. |
404 | The game or team is not found or the authenticating player has not joined the game. |
Paginated Tasks from Library
curl "https://app.socialscavenger.com/v1/tasks/library.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "page": PAGE, "per_page": PER_PAGE, "terms": ["TERM","ANOTHER_TERM"]}' \
-i
The above command returns JSON structured like this:
{
"tasks": [
{
"id": 117567,
"created_at": "2019-09-14T19:57:50Z",
"updated_at": "2019-09-25T17:52:04Z",
"name": "The Other JT",
"address": "",
"description": "He's Canada's version of JT. Just as popular globally? Probably not anymore! Still get a photo of your team, JT and something iconic.",
"ends_at": null,
"fullscreen": false,
"hide_answers": false,
"hide_locked": false,
"hints": false,
"hint_1": "",
"hint_1_points": 1,
"hint_2": "",
"hint_2_points": 1,
"hint_3": "",
"hint_3_points": 1,
"hint_4": "",
"hint_4_points": 1,
"hint_5": "",
"hint_5_points": 1,
"latitude": null,
"longitude": null,
"multiplechoice": null,
"points": 50,
"position": 37,
"quantity": 0,
"qr_url": null,
"reel_enabled": 1,
"reel_intro": null,
"reward_title": null,
"reward_description": null,
"starts_at": null,
"task_subtype": 0,
"task_type": 3,
"timer": 0,
"trivia": null,
"trivia_points_1": 1,
"trivia_points_2": 9999,
"trivia_points_3": 9999,
"trivia_points_4": 9999,
"trivia_points_5": 9999,
"trivia_points_unlimited": 9999,
"unlock_by_location_radius": 0,
"unlock_by_task_id": null,
"unlock_by_task_ids": null,
"unlock_by_task_txt": null,
"video_length": 30,
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss.....jpg",
"width": 0,
"height": 0
},
{
"name": "standard",
"url": "https://ss.....jpg",
"width": 0,
"height": 0
},
{
"name": "sticker",
"url": "https://ss.....png",
"width": 0,
"height": 0,
"fullscreen": true
},
{
"name": "correct",
"url": null,
"width": 0,
"height": 0
},
{
"name": "incorrect",
"url": null,
"width": 0,
"height": 0
},
{
"name": "reward",
"url": null,
"width": 0,
"height": 0
}
],
"videos": [
{
"name": "correct",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
},
{
"name": "incorrect",
"urls": {
"mp4": null,
"webm": null,
"gif": null,
"png": null
},
"width": 0,
"height": 0
}
]
},
"realities": [],
"games": [
{
"id": 5388,
"administrator": true
}
],
"tags": [
{
"label": "photo"
},
{
"label": "easy"
},
{
"label": "sticker"
},
{
"label": "sticker-photo"
},
{
"label": "jt"
},
{
"label": "toronto"
},
{
"label": "canada"
},
{
"label": "ottawa"
},
{
"label": "parliament"
},
{
"label": "fun"
}
]
}
],
"meta": {
"page": 1,
"pages": 1,
"per_page": 2,
"count": 2
}
}
This endpoint will search the platform task library and list the results.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/tasks/library.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list tasks for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
terms | ["default"] | An array of tags. | optional |
page | 1 | Page of results you which to retrieve. | optional |
per_page | 25 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of tasks for the tags are returned. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
406 | Not acceptable. The library is not enabled for the game. |
404 | The game is not found. |
Remove Tag from Task
curl "https://app.socialscavenger.com/v1/tasks/TASK_ID/tags.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"user_id": "USER_ID", "user_type": "email", "password": "PASSWORD", "label": "LABEL", "game_id": GAME_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will remove a tag from a task.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/tasks/TASK_ID/tags.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
task_id | nil | The id for the task you wish to have the tag removed from. | required |
game_id | nil | The id for the game in which the task lives. | required |
label | nil | The tag or label. | required |
Response Codes
Code | Meaning |
---|---|
200 | The tag has been removed from the task. |
400 | Label was missing or empty, forbidden. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The task or tag cannot be found. |
Related Events
Source | Comment |
---|---|
ss.task.update | Emitted after a task is updated. |
Copy Task from Library to Game
curl "https://app.socialscavenger.com/v1/tasks/TASK_ID/copy/GAME_ID.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
The above command returns a HTTP status code.
This endpoint will copy a task from the platform task library to the game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/tasks/TASK_ID/copy/GAME_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
task_id | nil | The id of the task you wish to copy. | required |
game_id | nil | The id for the game you want to add the copied task to. | required |
Response Codes
Code | Meaning |
---|---|
201 | The task has been copied into the game. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The task or game are not found. |
Related Events
Source | Comment |
---|---|
ss.task.create | Emitted after a task is created. |
Retrieve Map for Task
curl "https://app.socialscavenger.com/v1/tasks/TASK_ID/map.png" \
-H "X-Whitelabel: ss"
The above command returns a binary PNG map.
This endpoint will generate and return a static map for the task.
Consumed by Player
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/tasks/TASK_ID/map.png
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
task_id | nil | The id for the task. | required |
Response Codes
Code | Meaning |
---|---|
200 | A map was returned. |
404 | The task was not found or the task does not have a defined latitude/longitude. |
Update Augmented Reality for Task
curl "https://app.socialscavenger.com/v1/tasks/ar/REALITY_ID.json" \
-X PUT \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-d '{"chain": CHAIN_ID, "game_id": GAME_ID}' \
-i
The above command returns a HTTP response status code.
This endpoint will update an AR model for a task.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/tasks/ar/REALITY_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
reality_id | nil | The id number of the augmented reality model you are updating. | required |
game_id | nil | The game id which includes the model. | required |
animation_name | nil | The label of the animation. | optional |
duration_seconds | nil | Duration of the animation in seconds. | optional |
scale | nil | A scale (float) to apply to the model. | optional |
delay_seconds | nil | The delay in seconds to apply before starting the model animation. | optional |
style | nil | One of loop, stop, static, chain-loop or chain-stop. | optional |
chain | nil | A float indicating chain_number.position. | optional |
model_media_uuid | nil | The file name of the binary uploaded to S3. | optional |
model_media_extension | nil | The file extension of the binary uploaded to S3. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The model has been updated. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | The model is not found or not attached to a task in the game. |
Related Events
Source | Comment |
---|---|
ss.task.update | Emitted after a task is updated. |
Teams
Create Team
curl "https://app.socialscavenger.com/v1/teams.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}'
The above command returns JSON structured like this:
{
"team": {
"id": 84623,
"name": "Team Kristi",
"assets": {
"photos": [
{
"name": "thumb",
"url": null,
"width": 0,
"height": 0
},
{
"name": "standard",
"url": null,
"width": 0,
"height": 0
}
]
},
"users": [],
"reel": ""
},
"meta": {
"page": 1,
"per_page": 25
}
}
This endpoint creates a new team in a particular game. You must be a game administrator, coordinator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/teams.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
per_page | 25 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
201 | A team has been created. |
401 | Unauthorized. |
402 | Payment required. The game does not allow additional teams. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.team.create | Emitted after a team is created. |
Retrieve Team with Players
curl "https://app.socialscavenger.com/v1/teams/TEAM_ID/players.json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
The above command returns JSON structured like this:
{
"user": {
"id": 14096,
"email": "paul@socialscavenger.com",
"name": "Anonymous"
},
"team": {
"id": 48130,
"name": "Paul",
"completed": 6,
"points": 503,
"place": 7,
"players": [
{
"user_type": "email",
"game_id": 785,
"team_id": 48130,
"user_id": "paul@socialscavenger.com",
"tasks": 6,
"points": 503,
"name": "Anonymous (Hidden)",
"achievements": [
{
"id": 691,
"kind": "game",
"title": "Test",
"description": "1 challenge played",
"long_description": "",
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 75,
"height": 75
},
{
"name": "standard",
"url": "https://ss....jpg",
"width": 1024,
"height": 768
}
]
}
}
]
}
],
"reel": null,
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss....jpg",
"width": 75,
"height": 75
},
{
"name": "standard",
"url": "https://ss.....jpg",
"width": 432,
"height": 768
}
]
},
"updated": "2021-10-17T23:59:46Z"
}
}
This endpoint retrieves a team, the players on the team, and the rewards granted to each player.
Consumed by Player
apps. Response applies Personalization
.
HTTP Request
GET https://app.socialscavenger.com/v1/teams/TEAM_ID/players.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
team_id | nil | The id for the team you wish to list players for. | required |
style | alltime | One of daily, weekly or alltime. | optional |
metric | points | One of points or completed. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A team is returned. |
401 | Unauthorized. |
404 | The team is not found or the team is not associated with a game. |
Retrieve Teams
curl "https://app.socialscavenger.com/v1/teams.json?code=UNLOCKCODE" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
The above command returns JSON structured like this:
{
"id": 7018,
"teams": [{
"id": 66025,
"name": "Team 1"
}, {
"id": 66110,
"name": "Team 2"
}]
}
This endpoint retrieves a list of all teams in a particular game as specified by the game unlock code or the game id.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/teams.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list teams for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | A list of teams for the game are returned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
Paginated Teams
curl "https://app.socialscavenger.com/v1/teams/organize.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "page": PAGE, "per_page": PER_PAGE}' \
-i
The above command returns JSON structured like this:
{
"page": 1,
"pages": 17,
"per_page": 10,
"count": 164,
"game": {
"id": 785
},
"teams": [
{
"id": 6003,
"name": "Test123",
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://ss-a.....jpg",
"width": 75,
"height": 75
},
{
"name": "standard",
"url": "https://ss-as....jpg",
"width": 576,
"height": 768
}
]
},
"users": [
{
"id": 156,
"email": "name@gmail.com",
"name": "Name",
"game": {
"id": 785,
"administrator": true,
"coordinator": false,
"banned": false,
"code": "XXX"
}
}
],
"reel": "https://ap....mp4"
}
],
"unassigned_users": [
{
"id": 18038,
"email": "bla@bla.com",
"name": "",
"game": {
"id": 785,
"administrator": false,
"coordinator": false,
"banned": false,
"code": "XXX"
}
}
]
}
This endpoint will retreive a paginated list of the teams for the game.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/teams/organize.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list tasks for. | requires code or game_id |
game_id | nil | The id for the game you wish to list tasks for. | requires code or game_id |
page | 1 | Page of results you which to retrieve. | optional |
per_page | 25 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of teams, or any empty list, for the game are returned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
Update Team
curl "https://app.socialscavenger.com/v1/teams/TEAM_ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "name": "NAME"}' \
-i
If the system was able to update the team you will get a 200 http status code in the response.
This endpoint updates an existing team in a particular game. You must be a member of the team, a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Player
and Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/teams/TEAM_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
name | nil | The name of the team. | optional |
photo_media_uuid | nil | The uuid of the media uploaded directly to AWS S3. | optional |
photo_media_extension | nil | The file extension of the media asset uploaded directly to AWS S3. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The team has been updated. |
400 | Bad request, missing parameters to update. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a member of the team, a game coordinator, administrator or system super administrator. |
404 | The game or team is not found. |
Related Events
Source | Comment |
---|---|
ss.team.update | Emitted after a team is updated. |
ss.team.photo | A team photo has been uploaded. |
Delete Team
curl "https://app.socialscavenger.com/v1/teams/TEAM_ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
If the system was able to delete the team you will get a 200 http status code in the response.
This endpoint deletes a team in a particular game. It will remove them from the leaderboard as they are deleted. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint. The player will be team-less, but still joined to the game, so that an administrator may re-assign them to another team from the unassigned players list.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/teams/TEAM_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | The team has been deleted. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game or team is not found. |
Related Events
Source | Comment |
---|---|
ss.team.delete | Emitted after a team is deleted. |
Merge Teams
curl "https://app.socialscavenger.com/v1/teams/merge.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "team_id": TEAM_ID}' \
-i
The above command returns an HTTP status response code.
This endpoint allows you to merge two teams into a single team.
Consumed by Player
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/teams/merge.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
team_id | nil | The id for the team you wish to merge into. | required |
force | false | If true, then the request does not need to be reciprocated by someone on the team you wish to merge into. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A merge request has been initiated but must be reciprocated. |
201 | The calling user has been merged onto the team. |
401 | Unauthorized. This method requires authentication. |
404 | The game is not found. |
422 | Cannot process the merge, either user isn't on a team or destination team cannot be found, or current team and destination team are the same. |
Related Events
Source | Comment |
---|---|
ss.team.delete | Emitted after a team is deleted. |
ss.team.merge | Emitted after teams have been merged. |
ss.team.request | Emitted after a request to merge teams has been made. |
Split Teams
curl "https://app.socialscavenger.com/v1/teams/split.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID, "team_id": TEAM_ID}' \
-i
The above command returns an HTTP status response code.
This endpoint allows you to split a team into multiple teams. Every player on the team will be given their own new team. In this way, you explode the current team into as many teams as there are players.
HTTP Request
POST https://app.socialscavenger.com/v1/teams/split.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game. | requires code or game_id |
game_id | nil | The id for the game. | requires code or game_id |
team_id | nil | The id for the team you wish to split. | required |
Response Codes
Code | Meaning |
---|---|
200 | The team has been split. |
401 | Unauthorized. This method requires authentication. |
404 | The game or team is not found. |
Related Events
Source | Comment |
---|---|
ss.team.create | Emitted after each new team has been created. |
ss.team.delete | Emitted after the original team has been deleted. |
ss.team.unmerge | Emitted after team has been split into teams. |
Filter Teams by Term
curl "https://app.socialscavenger.com/v1/teams/search.json?game_id=GAME_ID&term=TERM" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
or
curl "https://app.socialscavenger.com/v1/teams/search.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"user_id": "USER_ID", "user_type": "email", "password": "PASSWORD", "game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"page": 1,
"pages": 1,
"per_page": 25,
"count": 1,
"game": {
"id": 7018
},
"teams": [
{
"id": 66116,
"name": "Auntie Julia",
"assets": {
"photos": [
{
"name": "thumb",
"url": "https://...jpg",
"width": 75,
"height": 75
},
{
"name": "standard",
"url": "https://...jpg",
"width": 1024,
"height": 768
}
]
},
"users": [
{
"id": 54256,
"email": "r@gmail.com",
"name": "Anonymous",
"super_admin": false,
"game": {
"id": 7018,
"creator": false,
"super_admin": false,
"administrator": false,
"coordinator": false,
"banned": false,
"code": "z"
}
}
],
"reel": ""
}
],
"unassigned_users": [
{
"id": 10754,
"email": "x@gmail.com",
"name": "Anonymous",
"super_admin": false,
"game": {
"id": 7018,
"creator": false,
"super_admin": false,
"administrator": false,
"coordinator": false,
"banned": false,
"code": "y"
}
}
]
}
This endpoint will retreive a list of teams for the game, filtered by a search term.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/teams/search.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list tasks for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
term | nil | A search term that must be present in the team name. | optional |
page | 1 | Page of results you which to retrieve. | optional |
per_page | 25 | Number of results per page. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of teams, or an empty list, for the game are returned. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The game is not found. |
Translations
Create a Translation
curl "https://app.socialscavenger.com/v1/proxy/translate.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"to": "TO", "origin": "ORIGIN", "bundle": "BUNDLE"}' \
-i
The above command returns an HTTP status code.
This endpoint will utilize Google Translate to translate your ORIGIN string into the language specified by TO. The result will be stored and available in future calls to Retrieve Translations.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/proxy/translate.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
origin | nil | The string you wish to translate. | required |
to | nil | A valid ISO-639-1 Language Code for the language you wish to translate the origin to. | required |
from | "en" | A valid ISO-639-1 Language Code for source language. Typically, "en". | optional |
bundle | "test" | A logical bundle for the translations. For example, "ios" or "android" or "builder" or "test". | optional |
Response Codes
Code | Meaning |
---|---|
200 | The translation is returned from storage. |
201 | A new translation has been processed and stored. |
401 | Unauthorized. |
406 | origin or to specified are not acceptable or missing. |
Retrieve Translations
curl "https://app.socialscavenger.com/v1/proxy/translate.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"to": "TO"}' \
-i
The above command returns JSON structured like this:
{
"translations": [
{
"origin": "Hello World.",
"translation": "Bonjour le monde."
},
{
"origin": "The red dog jumped.",
"translation": "Le chien rouge a sauté."
}
],
"meta": {
"from": "en",
"to": "fr",
"bundle": "test"
}
}
This endpoint will list the available whitelabel translations for the from and to language pairing.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/proxy/translate.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
from | "en" | A valid ISO-639-1 Language Code for source language. Typically, "en". | optional |
to | nil | A valid ISO-639-1 Language Code for the display language or language you want strings for. | required |
bundle | "test" | A logical bundle for the translations. For example, "ios" or "android" or "builder" or "test". | optional |
Response Codes
Code | Meaning |
---|---|
200 | A list of translation strings are returned. |
406 | to language specified is not acceptable or missing. |
Users
Create User
curl "https://app.socialscavenger.com/v1/users.json" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-d '{"email":"EMAIL","password":"PASSWORD","password_confirmation":"PASSWORD_CONFIRMATION", "name":"NAME"}'
The above command returns JSON structured like this:
{
"id": 65268,
"email": "Aug4@2021.com",
"name": "Aug 4th"
}
This endpoint creates a new user with the email and password specified.
Consumed by Player
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/users.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
nil | The email address for the user you wish to create. | required | |
password | nil | The password for the user. | required |
password_confirmation | nil | The password confirmation for the user. | required |
name | nil | The name of the user. | optional |
Response Codes
Code | Meaning |
---|---|
201 | User has been created. |
409 | Cannot create user as a conflict exists with that email. |
412 | The preconditions of a matching password and password_confirmation or valid email do not exist. |
422 | The system was unable to create the user. |
Related Events
Source | Comment |
---|---|
ss.user.create | Emitted after a player is created. |
Delete User
curl "https://app.socialscavenger.com/v1/users/ID.json" \
-X DELETE \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
If the system was able to delete the user you will get a 200 http status code in the response.
This endpoint deletes the user account from the platform. The user will be removed from all teams they are a part of. However, the teams themselves will not be deleted, regardless of whether or not they were the only player on the team. Similarly, the user is removed from all games, but the games themselves are not deleted. All of the submissions and chat messages from the user will be deleted. They cannot be recovered, and all points obtained for their submissions will be removed from their teams. After deletion, a new account can be created using the same email address.
HTTP Request
DELETE https://app.socialscavenger.com/v1/users/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id for the user. | required |
Response Codes
Code | Meaning |
---|---|
200 | The user has been deleted. |
401 | Unauthorized. |
406 | The user id is not acceptable or does not match the token. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.answer.unlike | Emitted after a like is deleted. |
ss.answer.delete | Emitted after an answer is deleted. |
ss.badge.delete | Emitted after a badge is deleted. |
ss.chat.delete | Emitted after a chat message is deleted. |
ss.user.delete | Emitted after the user is deleted. |
Retrieve User
curl "https://app.socialscavenger.com/v1/users/PLAYER_ID.json" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
The above command returns JSON structured like this:
{
"id": 14096,
"email": "name@domain.com",
"name": "Anonymous"
}
or if given a game_id for context, like this:
curl "https://app.socialscavenger.com/v1/users/PLAYER_ID.json?game_id=GAME_ID" \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-i
{
"id": 44106,
"email": "user@domain.com",
"name": "Anonymous",
"password_generated": null,
"game": {
"id": 7160,
"creator": false,
"super_admin": true,
"administrator": false,
"coordinator": false,
"banned": false,
"code": "XXX"
}
}
This endpoint returns a single user.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/users/PLAYER_ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
player_id | nil | The platform's internal user identification number or 0 for self/authenticating user. | required |
game_id | nil | The game id you wish to have extended attributes for. | optional |
Response Codes
Code | Meaning |
---|---|
200 | A user record is provided. |
401 | Unauthorized. This method requires authentication. |
Retrieve Users
curl "https://app.socialscavenger.com/v1/users.json?code=UNLOCKCODE&user_id=EMAIL&user_type=email&password=PASSWORD" \
-H "X-Whitelabel: ss"
The above command returns JSON structured like this:
{
"id": 7018,
"users": [{
"id": 10754,
"email": "shaun.cowles@gmail.com",
"name": "Anonymous"
}, {
"id": 14096,
"email": "paul@socialscavenger.com",
"name": "Anonymous"
}]
}
This endpoint retrieves a list of all users/players in a particular game as specified by the game unlock code or the game id.
HTTP Request
GET https://app.socialscavenger.com/v1/users.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to list users for. | requires code or game_id |
game_id | nil | The id for the game you wish to list users for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | Users for the game are returned. |
401 | Unauthorized. |
403 | You must be the game creator, a game administrator, or a system super administrator. |
404 | Game not found. |
Update Push Tokens
curl "https://app.socialscavenger.com/v1/users/tokens.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"firebase":"TOKEN"}'
The above command returns an HTTP response code.
This endpoint updates the push notification token for the player if a player token is provided, otherwise keeps the token as a visitor.
Consumed by Builder
and Player
apps as well as the marketing website.
HTTP Request
PATCH https://app.socialscavenger.com/v1/users/tokens.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
firebase | nil | A firebase token. | optional |
ios | nil | An Apple ecosystem apn token. | optional |
android | nil | An Android ecosystem apid token. | optional |
Response Codes
Code | Meaning |
---|---|
200 | The token was saved to the user record. |
202 | Token accepted but no update occurred. |
400 | No tokens were received, missing parameters. |
401 | Unauthorized. |
Related Events
Source | Comment |
---|---|
ss.user.token | Emitted after a player has a token stored. |
Reset User Password
curl "https://app.socialscavenger.com/v1/users/reset.json" \
-X PATCH \
-H "Content-Type: application/json" \
-H "X-Whitelabel: ss" \
-d '{"email":"EMAIL"}'
The above command returns JSON structured like this:
{
"id": 65269,
"email": "name@gmail.com",
"name": "Anonymous"
}
This endpoint resets a user password, emailing them the new password.
Consumed by Player
and Builder
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/users/reset.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
nil | The email address for the user you wish to reset the password for. | required |
Response Codes
Code | Meaning |
---|---|
200 | The user has had their password reset and emailed to them. |
404 | A user cannot be found with the provided email address. |
422 | The system could not process the reset. |
424 | The system was unable to compose a new password. |
Related Events
Source | Comment |
---|---|
ss.user.reset | Emitted after a player has reset their password. |
Get Indicator Status
curl "https://app.socialscavenger.com/v1/users/indicator.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"count": 49
}
If count it returns is > 0, there are unseen messages waiting for the player making the call. If count is 0, there are no unseen messages.
Consumed by Player
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/users/indicator.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
code | nil | The unlock code for the game you wish to get the indicator status for. | requires code or game_id |
game_id | nil | The id for the game you wish to get the indicator status for. | requires code or game_id |
Response Codes
Code | Meaning |
---|---|
200 | A count of pending unseen messages for the user is returned. |
401 | Unauthorized. |
404 | Game is not found. |
Update Indicator Status
curl "https://app.socialscavenger.com/v1/users/seen.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN"
The above command returns an HTTP status code.
This endpoint is called every time the player enters the chat view to indicate the last time they entered the stream of chat. It is called again after each time new messages are rendered into the visible view.
Consumed by Player
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/users/seen.json
Response Codes
Code | Meaning |
---|---|
200 | The user has been marked as seen. |
401 | Unauthorized. |
Related Events
Source | Comment |
---|---|
ss.user.seen | Emitted after successfully updating the last seen timestamp. |
Update Typing Status
curl "https://app.socialscavenger.com/v1/users/typing.json" \
-X PATCH \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-d '{"user_id": "EMAIL", "user_type": "email", "password": "PASSWORD", "game_id": GAME_ID}'
The above command returns an HTTP status code.
This endpoint is called every time a player starts typing into chat.
Consumed by Player
apps.
HTTP Request
PATCH https://app.socialscavenger.com/v1/users/typing.json
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The game the caller is typing in. | required |
Response Codes
Code | Meaning |
---|---|
200 | Typing event sent. |
401 | Unauthorized. |
404 | The game was not found. |
412 | Requesting user is not part of a team for the game. |
Related Events
Source | Comment |
---|---|
ss.user.typing | Emitted to indicate typing is happening. |
Verify User
This endpoint allows you to verify a player exists on the system. See HTTP API Authentication
Consumed by Player
apps.
Signin User
This endpoints allows you to signin a player using a password or personal unlock code. See HTTP API Authentication
Consumed by Player
and Builder
apps.
Waypoints
A waypoint is a fixed coordinate used to outline and connect the borders of a defined zone. It acts as a marker that, when linked with other waypoints, helps form the shape and boundary of the zone.
Zones have a set of waypoints attached to them. In turn, games have a set of zones.
Create Waypoint
curl "https://app.socialscavenger.com/v1/waypoints.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"zone_id": ZONE_ID, "position": POSITION, "game_id": GAME_ID, "latitude": LATITUDE, "longitude": LONGITUDE}' \
-i
The above command returns an HTTP status code.
This endpoint will add a waypoint. You must attach a waypoint to a zone within a game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/waypoints.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to attach the waypoint to. | required |
zone_id | nil | The id for the zone you wish to attach the waypoint to. | required |
position | 0 | The order for the waypoint within the zone. | optional |
latitude | nil | The gps latitude of the waypoint. | required |
longitude | nil | The gps longitude of the waypoint. | required |
Response Codes
Code | Meaning |
---|---|
201 | An waypoint has been created and added to the game zone. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
404 | The zone or game is not found. |
Related Events
Source | Comment |
---|---|
ss.waypoint.create | Emitted after a waypoint is created. |
Delete Waypoint
curl "https://app.socialscavenger.com/v1/waypoints/ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID, "zone_id": ZONE_ID}' \
-i
If the system was able to delete the waypoint you will get a 200 http status code in the response.
This endpoint deletes a waypoint as specified by the waypoint ID
. You must be a game coordinator or administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/waypoints/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id for the waypoint. | required |
game_id | nil | The id for the game the waypoint is attached to. | required |
zone_id | nil | The id for the zone the waypoint is attached to. | required |
Response Codes
Code | Meaning |
---|---|
200 | The waypoint has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.waypoint.delete | Emitted after a waypoint is deleted. |
Retrieve Waypoints
curl "https://app.socialscavenger.com/v1/waypoints.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID, "zone_id": ZONE_ID}' \
-i
The above command returns JSON structured like this:
{
"zone": {
"created_at": "2025-03-27T00:39:03Z",
"game_id": 785,
"id": 1,
"position": 2,
"updated_at": "2025-03-27T01:01:54Z",
"waypoints": [
{
"created_at": "2025-03-27T00:48:17Z",
"game_id": 785,
"id": 1,
"latitude": 49.1234,
"longitude": -123.5678,
"position": 1,
"updated_at": "2025-03-27T00:48:17Z",
"zone_id": 1
},
{
"created_at": "2025-03-27T00:50:49Z",
"game_id": 785,
"id": 2,
"latitude": 49.1235,
"longitude": -123.5679,
"position": 2,
"updated_at": "2025-03-27T01:01:35Z",
"zone_id": 1
}
]
}
}
This endpoint will list the waypoints for the game.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/waypoints.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game the waypoints are attached to. | required |
zone_id | nil | The id for the zone the waypoints are attached to. | required |
Response Codes
Code | Meaning |
---|---|
200 | A list of waypoints for the game zone are returned. |
401 | Unauthorized. |
404 | The game or zone is not found. |
Update Waypoint
curl "https://app.socialscavenger.com/v1/waypoints/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"zone_id": ZONE_ID, "position": POSITION, "game_id": GAME_ID, "latitude": LATITUDE, "longitude": LONGITUDE}' \
-i
If the system was able to update the waypoint you will get a 200 http status code in the response.
This endpoint will update an existing waypoint. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/waypoints/ID.json
Query Parameters
See the list of attributes in the Waypoint section. Note, game_id and zone_id are required.
Response Codes
Code | Meaning |
---|---|
200 | The waypoint has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The waypoint, zone or game is not found. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.waypoint.update | Emitted after successfully updating the waypoint. |
Zones
In a game, a zone is a section of the map created by connecting multiple points (waypoints) to form a closed shape.
Games have a set of zones attached to them. In turn, zones have a set of waypoints.
Create Zone
curl "https://app.socialscavenger.com/v1/zones.json" \
-X POST \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"position": POSITION, "game_id": GAME_ID}' \
-i
The above command returns an HTTP status code.
This endpoint will add a zone. You must attach a zone to a game.
Consumed by Builder
apps.
HTTP Request
POST https://app.socialscavenger.com/v1/zones.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game you wish to attach the zone to. | required |
position | 0 | The order for the zone within the game. | optional |
Response Codes
Code | Meaning |
---|---|
201 | An zone has been created and added to the game. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.zone.create | Emitted after a zone is created. |
Delete Zone
curl "https://app.socialscavenger.com/v1/zones/ID.json" \
-X DELETE \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
If the system was able to delete the zone you will get a 200 http status code in the response.
This endpoint deletes a zone as specified by the zone ID
. You must be a game coordinator or administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
DELETE https://app.socialscavenger.com/v1/zones/ID.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
id | nil | The id for the zone. | required |
game_id | nil | The id for the game the zone is attached to. | required |
Response Codes
Code | Meaning |
---|---|
200 | The zone has been deleted. |
401 | Unauthorized. |
403 | You must be the game creator, a game coordinator or administrator, or a system super administrator. |
422 | The deletion could not be processed. |
Related Events
Source | Comment |
---|---|
ss.zone.delete | Emitted after a zone is deleted. |
Retrieve Zones
curl "https://app.socialscavenger.com/v1/zones.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"zones": [
{
"created_at": "2025-03-27T00:39:03Z",
"game_id": 785,
"id": 1,
"position": 1,
"updated_at": "2025-03-27T00:39:03Z",
"waypoints": [
{
"created_at": "2025-03-27T00:48:17Z",
"game_id": 785,
"id": 1,
"latitude": 49.4412,
"longitude": -123.2234,
"position": 1,
"updated_at": "2025-03-27T00:48:17Z",
"zone_id": 1
}
]
}
]
}
This endpoint will list the zones for the game.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/zones.json
Query Parameters
Parameter | Default | Description | Deonticity |
---|---|---|---|
game_id | nil | The id for the game the zones are attached to. | required |
Response Codes
Code | Meaning |
---|---|
200 | A list of zones for the game are returned. |
401 | Unauthorized. |
404 | The game is not found. |
Update Zone
curl "https://app.socialscavenger.com/v1/zones/ID.json" \
-X PUT \
-H "X-Whitelabel: ss" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"position": POSITION, "game_id": GAME_ID}' \
-i
If the system was able to update the zone you will get a 200 http status code in the response.
This endpoint will update an existing zone. You must be a game coordinator, administrator, a system super administrator, or the game creator to use this API endpoint.
Consumed by Builder
apps.
HTTP Request
PUT https://app.socialscavenger.com/v1/zones/ID.json
Query Parameters
See the list of attributes in the Zone section. Note, game_id is required.
Response Codes
Code | Meaning |
---|---|
200 | The zone has been updated. |
401 | Unauthorized. |
403 | This method requires authentication and the user must be a game coordinator, game administrator or system super administrator. |
404 | The zone or game is not found. |
422 | The update could not be processed. |
Related Events
Source | Comment |
---|---|
ss.zone.update | Emitted after successfully updating the zone. |
Analytics
Retrieve Teams and Players
curl "https://app.socialscavenger.com/v1/analytics/teams.json" \
-X GET \
-H "X-Whitelabel: ss" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": GAME_ID}' \
-i
The above command returns JSON structured like this:
{
"game": {
"id": 785
},
"analytics": {
"teams": 376,
"players": 512,
"players_per_team": 1.36
}
}
This endpoint will list how many teams and players have joined the game, as well as the average number of players per team for the game.
Consumed by Builder
apps.
HTTP Request
GET https://app.socialscavenger.com/v1/analytics/teams.json
Response Codes
Code | Meaning |
---|---|
200 | A set of calculations for the game are returned. |
401 | Unauthorized. |
404 | The game is not found. |
Related Events
Source | Comment |
---|---|
ss.analytic.teams | Updated calculations for the game. Emitted each time a game submission is received. |
Events
Event Catalog
The Websocket API and Webhooks give you access to the following events in real-time:
A sample ss.admin.create event payload:
{
"app": {
"title": "Social Scavenger"
},
"administrator": {
"user_id": 1,
"game_id": 1
}
}
A sample ss.admin.delete event payload:
{
"app": {
"title": "Social Scavenger"
},
"administrator": {
"id": 1,
"user_id": 1,
"game_id": 1
}
}
Event | Description |
---|---|
ss.adjustment.create | Emitted after an adjustment is created. |
ss.adjustment.delete | Emitted after an adjustment is deleted. |
ss.adjustment.update | Emitted after successfully updating the adjustment. |
ss.admin.create | A new administrator has been added to a game you are a part of. |
ss.admin.delete | An administrator has had their administrative privileges removed from a game you are part of. |
ss.analytic.teams | The game analytic for teams has been updated. |
ss.analytic.interestingness | A submission has been scored for interestingness. |
ss.answer.accept | An answer has been accepted by a moderator, judge, administrator or coordinator. |
ss.answer.create | A new submission or answer has been received in a game you are part of. |
ss.answer.delete | An answer has been removed from a game you are part of. |
ss.answer.feature | An answer has been featured by a moderator, judge, administrator or coordinator. |
ss.answer.flag | An answer has been flagged for review by a moderator, judge, administrator or coordinator. |
ss.answer.like | An answer has been liked by a player. |
ss.answer.reject | An answer has been rejected by a moderator, judge, administrator or coordinator. |
ss.answer.review | An answer has been reviewed by a moderator, judge, administrator or coordinator. |
ss.answer.sheet | A video contact sheet has been created. |
ss.answer.unlike | An answer has been unliked by a player. |
ss.answer.update | An answer has been updated. Will be sent once rich media has been successfully processed. |
ss.badge.create | A player has met the requirements of an achievement and thus been awarded a badge. |
ss.badge.delete | A player has had a badge removed. |
ss.chat.create | A new message has been posted to a game chat channel. |
ss.comment.create | A comment has been created. |
ss.comment.delete | A comment has been deleted. |
ss.comment.like | A comment has been liked. |
ss.comment.unlike | A comment has had a like removed. |
ss.coordinator.create | A new coordinator has been added to a game you are a part of. |
ss.coordinator.delete | A coordinator has been removed from a game you are a part of. |
ss.designation.create | Emitted after a designation is created. |
ss.designation.delete | Emitted after a designations is deleted. |
ss.designation.update | Emitted after successfully updating the designation. |
ss.dropbox.connected | A user has connected their dropbox for synchronization. |
ss.dropbox.upload | A submission has had its media uploaded to a connected dropbox. |
ss.emails.reviews | Emitted to solicit game reviews. |
ss.game.clone | A game has been cloned into a new game. |
ss.game.create | A new game has been created. |
ss.game.delete | A game has been removed from the platform. |
ss.game.export | A game has been exported. |
ss.game.join | A game has been joined by a player. |
ss.game.leave | A player has left a game. |
ss.game.live | A game coordination event has been published. |
ss.game.media | A media asset related to the game (answer, game, task, team) has finished processing. |
ss.game.reel | A game reel has been generated or regenerated. |
ss.game.score | A game has been scored or rescored. The leaderboard has been refreshed. |
ss.game.search | A search for a game has occurred. |
ss.game.update | A game has had its settings updated. |
ss.group.create | Emitted after a group is created. |
ss.group.delete | Emitted after a group is deleted. |
ss.group.update | Emitted after a group is updated. |
ss.introduction.create | Emitted after a non player character introduction is created. |
ss.judge.create | Emitted after a judge is created. |
ss.judge.delete | Emitted after a judge is deleted. |
ss.judge.update | Emitted after successfully updating the judge. |
ss.npc.create | A non player character has been created. |
ss.npc.delete | A non player character has been deleted. |
ss.npc.update | A non player character has been updated. |
ss.nub.create | A nub has been created. |
ss.nub.delete | A nub has been deleted. |
ss.nub.update | A nub has been updated. |
ss.personalization.create | A personalization key/value pair has been created. |
ss.personalization.update | A personalization has been updated. |
ss.personalization.delete | A personalization has been deleted. |
ss.photo.upload | A photo has been uploaded. |
ss.photo.processed | A photo has been processed. |
ss.position.create | A position has been logged. |
ss.purchase.branding | The branding module has been purchased. |
ss.purchase.donation | The donation module has been purchased. |
ss.purchase.library | The library module has been purchased. |
ss.purchase.reels | The reels module has been purchased. |
ss.purchase.teams | The teams license has been purchased. |
ss.reward.create | A new reward or achievement has been created. |
ss.reward.delete | A reward or achievement has been removed. |
ss.reward.update | A reward or achievement has had its settings updated. |
ss.super.create | Emitted after the platform super administrator has been created. |
ss.super.delete | Emitted after the platform super administrator has been deleted. |
ss.task.create | A task or challenge has been created. |
ss.task.delete | A task or challenge has been removed. |
ss.task.hint | A task or challenge hint has been used by a player. |
ss.task.order | A task has had its order updated. |
ss.task.reel | A task reel has been generated or regenerated. |
ss.task.update | A task or challenge has had its definition updated. |
ss.team.create | A new team has been created in a game you are part of. |
ss.team.delete | A team has been deleted in a game you are part of. |
ss.team.merge | A team merge has occurred. Two teams have become one. |
ss.team.photo | A team photo has been uploaded. |
ss.team.reel | A team reel has been generated or regenerated. |
ss.team.request | A team merge request has been initiated. |
ss.team.unmerge | A team has been split up. One has become two. |
ss.team.update | A team has been updated. |
ss.user.ban | A user or player has been banned from a game you are part of. |
ss.user.create | A user or player has been created. |
ss.user.reset | A user has reset their password. |
ss.user.seen | A user has updated their last_seen timestamp. |
ss.user.signin | A user has signed in. |
ss.user.token | A user has uploaded and updated their push notification device token. |
ss.user.typing | A user is typing into a chat channel for a game you are part of. |
ss.user.update | A user or player record has been updated. |
ss.user.verify | A user account has been verified as to its existance. |
ss.user.unban | A user has had their ban revoked. |
ss.video.transcoded | A video has been transcoded. |
ss.video.upload | A video has been uploaded. |
ss.waypoint.create | A waypoint has been created. |
ss.waypoint.delete | A waypoint has been deleted. |
ss.waypoint.update | A waypoint has been updated. |
ss.zone.create | A zone has been created. |
ss.zone.delete | A zone has been deleted. |
ss.zone.update | A zone has been updated. |
Events allow you to build reactive applications that respond to activity on the Social Scavenger platform instantly. Events are a powerful way to integrate with the Social Scavenger platform for maximum speed and performance.
Errors
The Social Scavenger API uses the following response codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- The request is not allowed. |
404 | Not Found -- The specified resource could not be found. |
405 | Method Not Allowed -- You tried to access an API with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't acceptable. |
409 | Conflict -- a conflict is present. |
410 | Gone -- The resource requested has been removed from our servers. |
412 | Precondition Failed -- A necessary condition was not present. |
422 | Unprocessable Entity -- The system could not process the resource. |
424 | Failed Dependency -- A dependancy for the request has failed. |
429 | Too Many Requests -- You're requesting too many times in a short time period! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |