NAV

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 EMAIL and 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.
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.
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.
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 EMAIL, PASSWORD, PERSONAL_UNLOCK_CODE, TOKEN and SCOPE 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:

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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&#39;m hiding where you&#39;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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
email 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
email 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.
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.
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.
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.
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.
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.
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.
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.
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.
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
email 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
email 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.
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
email 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.
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
email 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
email 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.
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.
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.
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
email 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.