Skip to main content

List Activations

GET Endpoint
https://data-api.witcontests.com/activations/list

The GET /activations/list call can be used to list all of your past and future activations on Wit, and supports a number of filtering options to help find the activations you're looking for.

Example​

Getting a list of activations with curl
curl https://data-api.witcontests.com/activations/list \
    -H 'Authorization: Api-Key <API KEY>'
/activations/list JSON example response
{
    "activations": [
        {
            "id": "m2NGrpiOx8B0",
            "type": "giveaway",
            "subtype": "instant_win",
            "publicUrl": "https://web.witcontests.com/example/giveaway/win/draft-220801",
            "title": "2022 Draft Instant Win Game",
            "description": "Play now for your chance to win a jersey and commemorative draft tickets!",
            "slug": "draft-220801",
            "startTime": {
                "iso": "2022-08-01T01:00:00.000Z",
                "ts": 1657155600
            },
            "endTime": {
                "iso": "2022-08-07T23:00:00.000Z",
                "ts": 1657234800
            },
            "sponsorName": "Contoso",
            "sponsorUrl": "https://www.contoso.com/",
            "createdAt": {
                "iso": "2022-07-06T22:01:43.000Z",
                "ts": 1657144903
            },
            "updatedAt": {
                "iso": "2022-07-08T18:40:01.000Z",
                "ts": 1657305601
            }
        }
    ],
    "next": null
}

URL parameter options​

info

All URL parameters are optional.

"state"​

The "state" parameter can be used to filter activations by their current running state. Every activation can be in one of three states:

  • not_started: The activation has not yet begun.
  • running: The activation is currently active.
  • ended: The activation has ended.

You may pass one of these state values in the "state" parameter. For example, if you only want to retrieve future activations that haven't started, set the parameter to state=not_running.

"start_date"​

The "start_date" parameter can be used to retrieve activations that start on a specific date. The date format should be an ISO date string, in YYYY-MM-DD format.

To only retrieve activations that begin on August 1st, 2022, set the parameter to start_date=2022-08-01.

"types"​

The "types" parameter accepts an array of activation types you want to filter by. For example, to only get sweepstakes activations, set the parameter to types[]=sweepstakes.

The possible type values are:

  • giveaway: Giveaway (including instant win games, T-shirt tosses, prize wheels, slot machines, scratch-off games)
  • sweepstakes: Sweepstakes (including standard and vote-to-win sweepstakes)
  • contest: Photo/video contest
  • artwall: Photo/video art wall
  • bracket: Bracket challenge
  • scavenger: Scavenger hunt
  • pickem: Pick'em prediction game
  • trivia: Trivia game
  • map: Fan map

"limit"​

The "limit" parameter determines the maximum number of activations returned in the response list. This can be a number between 1 and 100.

If your filters would result in more activations than your limit allows, you can use ID-based pagination to retrieve the next page of results. See the "next" parameter below for more information.

"next"​

The "next" parameter can be used to paginate through the list of activations.

If your request has more results than your limit allows for, the "next" key in the response object will have an ID string as its value. To get the next page of results, make a new request with the "next" URL parameter added, the value of which should be the "next" ID from the previous response.

For example, if you make a list call request and receive this response:

{
    "activations": [...],
    "next": "nkO8BDi42G4x"
}

Then your following list call should have the parameter next=nkO8BDi42G4x set.

If there are no more results, the value of "next" in the response will be null.

Response schema​

"activations"​

"activations" is a list of Activation objects, the same found in the /activations/:id and /activations/latest calls.

  • id (string): Unique identifier for the activation. This id is case-sensitive.
  • type (string): Type of activation.
    • Possible values:
      • giveaway: Giveaway (including instant win games, T-shirt tosses, prize wheels, slot machines, scratch-off games)
      • sweepstakes: Sweepstakes (including standard and vote-to-win sweepstakes)
      • contest: Photo/video contest
      • artwall: Photo/video art wall
      • bracket: Bracket challenge
      • scavenger: Scavenger hunt
      • pickem: Pick'em prediction game
      • trivia: Trivia game
      • map: Fan map
  • subtype (string): Some activation types have specific subtypes, which can include:
    • For giveaways:
      • instant_win: Instant win game, or virtual T-shirt toss
      • roulette: Prize wheel game
      • slots: Slot machine game
      • scratchoff: Scratch-off game
      • scratch_to_win: Scratch-to-win game
    • For sweepstakes:
      • standard: Standard sweepstakes
      • vote_to_win: Vote-to-win sweepstakes
      • potg: Player-of-the-game Sweepstakes
  • publicUrl (string): The canonical public URL to the activation.
  • title (string): The title of the activation.
  • description (string): The description used for the activation.
  • slug (string): The unique permalink identifier used in the activation's URL.
  • startTime (DateObject): The time that the activation starts at.
  • endTime (DateObject): The time that the activation ends at.
  • sponsorName (string|null): The name of the attached sponsor, if any.
  • sponsorUrl (string|null): The URL of the attached sponsor's website, if any.
  • createdAt (DateObject): The time that the activation was created on Wit.
  • updatedAt (DateObject): The time that the activation settings were last updated.

"next"​

See the documentation for the "next" request parameter.