VinPass API – Scoreboard

This page is part of the VinPass API.

The VinPass Scoreboard entry point allows you to retrieve details on the passes earned and in-play for a player. You will only be able to access the scoreboard for players on your platform.

URL: http://api.vinpass.com/v1/scoreboard
Method: GET

Update: The earned pass count and earned passes were added to this API on 4/17/2011 based on partner feedback. Prior to this change, only the in-play pass count and in-play passes were included. Since only additions were made to the response and the format of the original in-play info did not change, the version of the API was not changed.

Request Parameters

Name Required? Description
user Yes User identifier (from your system) that is used as the user.id field when submitting activities to VinPass.
purge No Boolean value (1/true/yes) that indicates that all VinPass history and passes should be purged for “user”. This parameter is intended to support testing VinPass integration and is therefore only supported on the VinPass API test site.

Response Format

Responses will have the following format where each “earnedPasses” array element represents a pass that has been earned and each “inPlayPasses” array element represents a pass that is in-play (i.e. started but not yet earned). Earned passes are ordered descending by earn date and in-play passes will be sorted with the passes closest to being earned listed first. All responses will be in UTF-8.

Field Name Type Description
earnedPassCount Integer Count of the number of passes earned for this user.
earnedPasses[] Array Array of zero or more passes that have been earned.
earnedPasses[].passId String Unique identifier for this pass.
earnedPasses[].passType Enum Game play type for pass: PROGRESSIVE or CHECK_LIST.
earnedPasses[].lastActivityDate Datetime Timestamp when the last activity occurred for this pass for this user (ISO 8601).
earnedPasses[].earnedDate Datetime Timestamp when the pass was earned (ISO 8601).
earnedPasses[].hasRewards Boolean Indicates if this pass has rewards associated with it.
earnedPasses[].rewards String Description of rewards associated with this pass or null if the pass has no rewards.
earnedPasses[].name String Name for this pass
earnedPasses[].howToEarn String Brief description of how to earn this pass.
earnedPasses[].description String Description for this pass
earnedPasses[].imageUrl URL URL to pass image URL
earnedPasses[].sponsor.name String Name of the sponsor for this pass.
earnedPasses[].sponsor.description String Description of the sponsor for this pass.
earnedPasses[].sponsor.url URL URL for the sponsor.
earnedPasses[].sponsor.logoUrl URL URL for the sponsor logo image.
inPlayPassCount Integer Count of the number of passes in-play for this user.
inPlayPasses[] Array Array of zero or more passes that are in-play (i.e. started but not yet earned)
inPlayPasses[].passId String Unique identifier for this pass.
inPlayPasses[].passType Enum Game play type for pass: PROGRESSIVE or CHECK_LIST.
inPlayPasses[].lastActivityDate Datetime Timestamp when the last activity occurred for this pass for this user (ISO 8601).
inPlayPasses[].hasRewards Boolean Indicates if this pass has rewards associated with it.
inPlayPasses[].progressCurrent Integer Current count of activities counted against this pass.
inPlayPasses[].progressToGo Integer Count of remaining activities needed to earn this pass.
inPlayPasses[].name String Name for this pass
inPlayPasses[].howToEarn String Brief description of how to earn this pass.
inPlayPasses[].description String Description for this pass
inPlayPasses[].imageUrl URL URL to pass image URL
inPlayPasses[].sponsor.name String Name of the sponsor for this pass.
inPlayPasses[].sponsor.description String Description of the sponsor for this pass.
inPlayPasses[].sponsor.url URL URL for the sponsor.
inPlayPasses[].sponsor.logoUrl URL URL for the sponsor logo image.

Examples

The following examples show responses for players in various states of play.

Example 1 – Player With No Earned or In-Play Passes

{
  "earnedPassCount": 0,
  "inPlayPassCount": 0,
  "earnedPasses": [],
  "inPlayPasses": []
}

Example 2 – Player With an Earned Pass and 2 In-Play Passes

  {
    "earnedPassCount": 1,
    "inPlayPassCount": 2,
    "earnedPasses": [
      {
        "passId": "121212",
        "passType": "CHECK_LIST",
        "earnedDate": "2010-12-22T08:52:32Z",
        "lastActivityDate": "2010-12-22T08:52:32Z",
        "rewards": "Congratulations! You have earned a 20% discount on your next purchase. Use promotion code 'VP20202' at checkout at store.somewinery.com",
        "name": "Sorella Ridge Explorer",
        "howToEarn": "Taste all of our current vintage wines...",
        "description": "Sorella Ridge is a boutique winery focusing on ....",
        "imageUrl" : "http://assets.vinpass.com/passes/121212-earned.jpg",
        "sponsor": {
          "name": "Sorella Ridge Winery",
          "description": "yada yada yada..."
        }
      }
    ],
    "inPlayPasses": [
      {
        "passId": "4444-1111",
        "passType": "CHECK_LIST",
        "lastActivityDate": "2010-12-22T08:52:32Z",
        "hasRewards": true,
        "progressCurrent": 9,
        "progressToGo": 2,
        "name": "Bank On It",
        "howToEarn": "Taste a wine from each of the regions from the left and right banks of Bordeaux",
        "description": "Bordeaux is the world's most....",
        "imageUrl" : "http://assets.vinpass.com/passes/4444-1111-inplay.jpg",
        "sponsor": {
          "name": "Fictitious Bordeaux Society",
          "description": "Collection of Bordeaux experts..."
        }
      },
      {
        "passId": "1234-9885",
        "passType": "PROGRESSIVE",
        "lastActivityDate": "2011-01-05T11:05:47Z",
        "hasRewards": false,
        "progressCurrent": 1,
        "progressToGo": 4,
        "name": "Sorella Ridge Explorer",
        "howToEarn": "Taste any 5 of our wines to become an Explorer",
        "description": "Sorella Ridge wines offer ....",
        "imageUrl" : "http://assets.vinpass.com/passes/1234-9885-inplay.jpg",
        "sponsor": {
          "name": "Sorella Ridge Winery",
          "description": "A small family run winery located..."
        }
      }
    ]
  }

Also see the Main VinPass API page, Activities page, and Passes page.

Comments are closed.