Answer a survey

POST /v1/player/surveys/answer · for player session

Use it when the player finishes a survey from List surveys. CEEJAY checks every answer by the rules Discord and the Member Hub use: a required question needs an answer, a number must be a number, an email address and a link must be one, a pick must be one of the question's options, and a score must be on its scale. The answers are saved to the member's response, and on the first completion CEEJAY grants the survey's rewards: its XP, its roles and its reward list. CEEJAY does not send the member a direct message. The request needs the game loop. For the three conditions (game loop enabled for the game, member consent, server membership) and the error each returns, see What has to be true first.

Body parameters

Returns

A second answer to a survey that lets members edit their answers updates them and grants nothing. A survey that does not returns survey_unavailable with the reason already_answered. The request is safe to repeat and takes no key.

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/player/surveys/answer \
  -H "Authorization: Bearer $CEEJAY_PLAYER_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "surveyId": 41,
    "answers": {
      "k_00000000000000a1": "4",
      "k_00000000000000a3": "More maps, please"
    }
  }'

The TypeScript example uses connect.hub.answerSurvey from the Connect client in the TypeScript SDK. The player must be connected first: the client manages and refreshes the player session. It returns the data of the response below.

{
  "success": true,
  "data": {
    "surveyId": 41,
    "updated": false,
    "rewards": { "xp": 50, "roles": 0, "names": ["20 coins"] }
  }
}

A wrong answer

An answer its question doesn't take (an empty required question, text that is not a number, a pick that is not one of the options, a score off the scale) returns 400 with field: "answers", the question's key in question, and a message that names the question and the rule, such as How would you rate the build?: pick one of the options. Show it beside that question and let the player try again. Nothing is saved until every answer is right.

Limits

20 writes a minute for one player session, shared by every request of the game loop that changes something. Every request made with a player session also counts toward 140 a minute. See Rate limits. Over a limit the response is 429 with the code rate_limited, retryAfter and a Retry-After header.

Errors

Every error body also includes requestId. Match on code; message text can change.

The errors every request of a game shares (the key, the state of the game, the origin, 405, 429, 500) are on the Errors page, and the errors specific to the game loop are under Codes of the game loop.