Skip to main content

Get Activation by ID

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

The GET /activations/:id call returns basic information about a particular activation by its ID. It also lists participant entry data for the activation.

Example​

Getting an activation with curl
curl https://data-api.witcontests.com/activations/nkO8BDi42G4x \
    -H 'Authorization: Api-Key <API KEY>'
/activations/:id JSON example response
{
    "activation": {
        "id": "nkO8BDi42G4x",
        "type": "giveaway",
        "subtype": "slots",
        "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-04-29T21:00:00.000Z",
            "ts": 1651266000
        },
        "endTime": {
            "iso": "2022-04-30T00:30:00.000Z",
            "ts": 1651278600
        },
        "sponsorName": "Contoso",
        "sponsorUrl": "https://www.contoso.com/",
        "createdAt": {
            "iso": "2022-03-24T02:17:35.000Z",
            "ts": 1648088255
        },
        "updatedAt": {
            "iso": "2022-07-08T18:40:01.000Z",
            "ts": 1657305601
        }
    },
    "entries": [
        {
            "id": "5aaddb9b5b3346cbba253718d22b59dd",
            "email": "janedoe@example.com",
            "firstName": "Jane",
            "lastName": "Doe",
            "emailOptIn": false,
            "isWinner": true,
            "isConfirmed": true,
            "isFulfilled": false,
            "prize": {
                "title": "Autographed Jersey",
                "subtitle": "Team Name"
            },
            "address": null,
            "extras": [],
            "enteredAt": {
                "iso": "2022-04-29T21:37:49.000Z",
                "ts": 1651268269
            }
        },
        ...
    ],
    "next": null
}

URL path parameters​

":id"​

:id is the ID of the activation you want to retrieve. Use the /activations/list call to determine the ID of the activation you're looking for.

For example, to get the activation with ID "nkO8BDi42G4x", the endpoint would be:

https://data-api.witcontests.com/activations/nkO8BDi42G4x

URL parameter options​

info

All URL parameters are optional.

"is_completed"​

Filter entries to only return players who have completed the activation. Not all activation types support this option.

Set is_completed=1 to get completed entries.

For scavenger hunts, these are players who have correctly answered every question, or for photo scavenger hunts, players who have uploaded a photo for each question.

For trivia games and pick'em games, these are players who have simply answered every question, correctly or not.

"is_winner"​

Filter entries to only return winners. Not all activation types have winners.

Set is_winner=1 to get winning entries.

For giveaways and photo/video contests, these are entries which have won a prize.

For trivia games and pick'em games, these are players who have correctly answered every question.

For scavenger hunts, these are players who have been manually selected to win a prize in the brands console.

"bracket_round"​

Only applies to bracket challenges. Filter entries by which round of the bracket they were submitted in.

For example, if you want to get votes submitted only in round 2, set bracket_round=2.

"bracket_seed"​

Only applies to bracket challenges. You can use the seed number of a bracket contestant to filter by entries that voted for that contestant.

For example, if you want to get votes submitted for the contestant with seed #9, set bracket_seed=9.

"start_date"​

The "start_date" parameter can be used to retrieve entries that entered on and after a specific date. The date format should be an ISO date string, in YYYY-MM-DD format (optional time format: YYYY-MM-DDTHH:mm:ss).

To only retrieve entries that entered on and after August 1st, 2022, set the parameter to start_date=2022-08-01.

"limit"​

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

If your filters would result in more entries 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 entries.

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:

{
    "activation": [...],
    "entries": [...],
    "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​

"activation"​

  • 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.

"entries"​

"entries" is an array of Entry objects, as defined below:

Fields common to all activations:​

  • id (string): Unique identifier for this entry.
  • email (string): The entrant's email address.
  • firstName (string): The entrant's first name, as given.
  • lastName (string): The entrant's last name, as given.
  • emailOptIn (boolean): True if the entrant opted-in to receive marketing emails.
  • extras (array<Extra>): Answers to extra form questions and checkboxes specified on this activation.
  • enteredAt (DateObject): The time that the entrant submitted the entry form at.

Fields specific to artwall activations:​

  • category (string|null): The name of the category chosen by the entrant for their submission.
  • media (Media|null): The photo or video uploaded by the entrant.

Fields specific to bracket challenges:​

  • vote (BracketVote): Information about the contestant that the entrant voted for.

Fields specific to photo/video contests:​

  • rank (number): The final ranking of the entry. Only available after voting has completed.
  • isWinner (boolean): True if the entrant is a winner.
  • isFulfilled (boolean): True if the entrant's prize has been marked as fulfilled.
  • prize (Prize|null): Describes the prize won by the entrant, if any.
  • media (Media|null): The photo or video uploaded by the entrant.

Fields specific to giveaway activations:​

  • isWinner (boolean): True if the entrant is a winner.
  • isConfirmed (boolean): True for entrants who have won a prize and confirmed their contact information.
  • isFulfilled (boolean): True if the entrant's prize has been marked as fulfilled.
  • address (Address|null): The entrant's mailing address. Available only in certain cases.
  • prize (Prize|null): Describes the prize won by the entrant, if any.

Fields specific to scavenger hunt activations:​

  • isWinner (boolean): True if the entrant is a winner.
  • seat (ScavengerSeat|null): The entrant's seat location, if requested for the activation.
  • totalCorrect (number): Total number of questions answered correctly.
  • completionTimeSec (number) Time in seconds taken to complete the activation.

Fields specific to sweepstakes activations:​

  • choices (array<Choice>): Vote choices selected by the entrant. Available for vote-to-win sweepstakes.

Fields specific to trivia games​

  • isWinner (boolean): True if the entrant is a winner.
  • totalCorrect (number): Total number of questions answered correctly.
  • completionTimeSec (number) Time in seconds taken to complete the activation.

Fields specific to pick'em games​

  • isWinner (boolean): True if the entrant is a winner.
  • totalCorrect (number): Total number of questions answered correctly.

Fields specific to fan maps​

  • choice (string): Entrant's choice when entering the fan map.

"next"​

See the documentation for the "next" request parameter.