Gimmie APIs

LATEST VERSION

1.12

OVERVIEW

The Gimmie APIs provide our partners access to the rewards data, events, etc.

Notes:

  • Gimmie uses OAuth to provide authorized access to its APIs.
  • Partner here plays both "Consumer" and "User" in OAuth.
  • OAuth key, secret, tokens will be given via partner portal.
  • APIs should be implemented on partner's server end.
  • Partner needs to handle the user authentication.
  • Partner keeps the user's profile (user name, etc.) on partner's infrastructure and pass Gimmie API with only user id or tokens.
  • Each API call MUST provide a targeting API version number and user ID, otherwise will get a verification error.
  • User will have points shared across different games. If you would like to separate the points and you using same form of id for each game, you will need to add a prefix to the user id when passing to Gimmie API.

COMMON API PARAMETERS

  • The REST API includes a version place marker. Currently there is only one version of the API exists. All API request will be of the format: https://api.gimmieworld.com/1/profile.json
  • reward_id={reward-id} is reward's ID that identify a reward that partner defines in the portal.
  • event_name={event-name} is the unique event name that partner defines in the portal.
  • event_id={event-id} is the ID for the event that partner defines in the portal.
  • claim_id={claim-id} is claim's ID that identify a reward that the user previously redeem.

COMMON JSON RESPONSES

While processing API logic, if an error is encountered, the JSON response will include a false on success and an error:

{
  "response": {"success": false},
  "error": {"code":"400.0","message":"Unknown OAuth signature method"}
}

The Gimmie API can return error for any operation. Here's the list of errors that you may encounter

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 404.1 - Reward not found
  • 404.2 - Event not found
  • 404.3 - Store not found
  • 404.4 - Player not found
  • 409.5.4 - Points balance is insufficient
  • 409.5.5 - Experience points is insufficient
  • 409.5.6 - Limit per player has reached
  • 409.6.7 - Action limit has reached
  • 410.1.3 - No more reward codes to redeem
  • 412.1.1 - Reward is not available yet
  • 412.1.2 - Reward is not available anymore
  • 500 - Server side error

If there is no error, the JSON response will include an empty error and a true on success, plus any requested information:

{ 
  "response": {
    "success": true,
    // … and requested information follows
  },
  "error": {}
}

APIs

CATEGORIES

Obtains categories with available rewards, both categories and rewards are returned in the response.

Each app would have multiple categories. Each category would have multiple rewards.

Partner could use these data to list out the rewards for users.

Syntax

GET /categories.json

Example

/categories.json

Response

{
  "response": {
    "success": true,
    "categories": [ 
      // category #1
      {
        "name": "Electronics",
        "reward_exp_points_range": {
          "min":0,
          "max":3
        },
        "reward_points_range": {
          "min":0,
          "max":3
        },
        "reward_price_range": {
          "min":300,
          "max":500
        },          
        "rewards": [
          {
            "id": "2001",
            "name": "some reward name with long description",
            "short_name": "reward name", //reward's name for shorter display
            "category_name": "Electronics",
            "store_name": "some company name",
            "total_quantity": 100,
            "claimed_quantity": 1,
            "description": "reward description",
            "fine_print": "terms & conditions",
            "experience_points": 10000,
            "limit_per_player": 1,
            "price": "10", //reward's dollar / other reward system points value
            "points": 200 //reward's value according to app's virtual currency
            "discount": "$10 off", //reward's discount percent value
            "start_date": "2012-9-1", //campaign start date
            "end_date": "2012-10-1", //campaign end date
            "image_url": "reward_image.png",
            "valid_until": "2012-11-1T00:00:00Z", //reward expiry date time
            "country_codes": [ // countries that the reward is meant for
              "US", 
              "CN"
            ]                
          },
          //... more content here
        ]
      },
      // category #2
      {
        //... more content here
      }
    ]
  },
  "error": {}
}

Potential Errors

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 500 - Server side error

REWARDS

Obtains specific rewards' detail with reward id, support multiple rewards.

Partner could use these data to list out the specific rewards for users.

Syntax

GET /rewards.json

Parameters

  • reward_id - The numerical id of the desired reward or rewards, use comma to indicate multiple reward ids.

Example

/rewards.json?reward_id={reward_id} or /rewards.json?reward_id={reward_id},{reward_id},{reward_id}

Response

{
  "response": {
    "success": true,
    "rewards": [
      {
        "id": "2001",
        "name": "some reward name with long description",
        "short_name": "reward name", //reward's name for shorter display
        "category_name": "Electronics",
        "store_name": "some company name",
        "total_quantity": 100,
        "claimed_quantity": 1,
        "description": "reward description",
        "fine_print": "terms & conditions",
        "experience_points": 10000,
        "limit_per_player": 1,
        "price": "10", //reward's dollor value / other reward system points value
        "points": 200 //reward's value according to app's virtual currency
        "discount": "$10 off", //reward's discount percent value
        "start_date": "2012-9-1", //campaign start date
        "end_date": "2012-10-1", //campaign end date
        "image_url": "reward_image.png",
        "valid_until": "2012-11-1T00:00:00Z", //reward expiry date time
        "country_codes": [ // countries that the reward is meant for
          "US", 
          "CN"
        ]
      },
      {
          //... more content here
      }
    ]
  },
  "error": {}
}

Potential Errors

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 404.1 - Reward not found
  • 500 - Server side error

PROFILE

Obtains the user's profile, which includes the user's reward claims.

Syntax

GET /profile.json

Example

/profile.json

Response

{
  "response": {
    "success": true,
    "user": {
      "user_id": "partner's user ID",
      "awarded_points": 1000,
      "redeemed_points": 300,
      "next_level_points": 5000,
      "points_to_next_level": 4000
    },
    "claims": [ 
      {
        "id": "123",
        "code": "QWETY-1234",
        "reward":{
          "id": "2001",
          "url": "http://www.somewebsite.com",
          "name": "some reward name",
          "short_name": "reward name", //reward's name for shorter display
          "category_name": "Electronics",
          "store_name": "some company name",
          "total_quantity": 100,
          "claimed_quantity": 1,
          "description": "reward description",
          "fine_print": "terms & conditions",
          "experience_points": 10000,
          "limit_per_player": 1,
          "price": "10", //reward's dollor value / other reward system points value
          "points": 200 //reward's value according to app's virtual currency
          "discount": "$10 off", //reward's discount percent value
          "start_date": "2012-9-1", //campaign start date
          "end_date": "2012-10-1", //campaign end date
          "image_url": "reward_image.png",
          "valid_until": "2012-11-1T00:00:00Z", //reward expiry date time
          "country_codes": [ // countries that the reward is meant for
            "US", 
            "CN"
          ],
        }          
      }
    ]
  },
  "error": {}
}

Potential Errors

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 404.4 - Player not found
  • 500 - Server side error

CLAIMS

Obtains specific claims' detail with claim id, support multiple claims.

Partner could use these data to list out the specific claims for users.

Syntax

GET /claims.json

Parameters

  • claim_id - The numerical id of the desired claim or claims, use comma to indicate multiple claim ids.

Example

/claims.json?claim_id={claim_id} or /claims.json?claim_id={claim_id},{claim_id},{claim_id}

Response

{
  "response": {
    "success": true,
    "claims": [ 
      {
        "id": "123",
        "reward":{
          "id": "2001",
          "url": "http://www.somewebsite.com",
          "name": "some reward name",
          "short_name": "reward name", //reward's name for shorter display
          "category_name": "Electronics",
          "store_name": "some company name",
          "total_quantity": 100,
          "claimed_quantity": 1,
          "description": "reward description",
          "fine_print": "terms & conditions",
          "experience_points": 10000,
          "limit_per_player": 1,
          "price": "10", //reward's dollor value / other reward system points value
          "points": 200 //reward's value according to app's virtual currency
          "discount": "$10 off", //reward's discount percent value
          "start_date": "2012-9-1", //campaign start date
          "end_date": "2012-10-1", //campaign end date
          "image_url": "reward_image.png",
          "valid_until": "2012-11-1T00:00:00Z", //reward expiry date time
          "country_codes": [ // countries that the reward is meant for
            "US", 
            "CN"
          ]
        }
      }
    ]
  },
  "error": {}
}

Potential Errors

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 404.1 - Reward not found
  • 500 - Server side error

EVENTS

Obtains events and actions.

Events represent what happens in partner's app. Actions represent the result of triggering these events, for example, award game points, etc.

Partners could use the events as goals, letting users know what to do and what to achieve.

Syntax

GET /events.json

Parameters

  • event_id - The numerical id of the desired event or events, use comma to indicate multiple event ids.

Example

/events.json or /events.json?event_id={event_id} or /events.json?event_id={event_id},{event_id},{event_id}

Response

{
  "response": {
    "success": true,
    "events": [
      {
        "id": "1234",
        "name": "event name",
        "description": "this is an event for level up",
        "actions": [
          {
              "action_type": "award_points",
              "message": "congrats",
            "points": 10, //award 100 points for level up
            "limit": 10 //number of times this action could be triggered
            }
        ]
      },
      {
        //... more events here
      }
    ]
  },
  "error": {}
}

Potential Errors

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 404.2 - Event not found
  • 500 - Server side error

TRIGGER

Triggers and records an event either by name or ID, which may result in some actions within Gimmie (such as awarding points, etc.) and obtains any further actions to perform on the calling side (such as showing messages, etc.).

Partners could call this when a event is triggered by a user. Use further actions here to have better track of users behavior and interaction on the fly.

Syntax

GET /trigger.json

Parameters

  • event_name (optional) - The name of the event to trigger and record
  • event_id (optional) - The numerical id of the desired event to trigger and record
  • source_uid (optional) - A source numerical/string id that can be use to allow trigger event multiple time. e.g. to trigger an event for different article

Example

/trigger.json?event_id={event_id}&source_uid={source_uid} or /trigger.json?event_name={event_name}&source_uid={source_uid}

Response

{
  "response": {
    "success": true,
    "user": {
      "user_id": "partner's user ID",
      "awarded_points": 1000, //points total awarded to the user
      "redeemed_points": 300, //user's points used on rewards, this solution is to provide easier track of user's behavior
      "next_level_points": 5000, // minimum awarded_points to reach next level (or null)
      "points_to_next_level": 4000 // points remaining before reaching next level (or null)
    },
    "actions": [
      {
          "action_type": "award_points",
          "message": "congrats",
        "points": 10, //award 100 points for level up
        "limit": 10,  //number of times this action could be triggered
        "success":true //indicate if points is awarded
      }
    ],
    // when there are no featured rewards available, the entire "categories" property is omitted
    // rewards listed here excludes those that are beyond the player's level or balance points
    "categories": [
      {
        "name": "Featured",
        "reward_exp_points_range": {
          "min": 101,
          "max": 101
        },
        "reward_points_range": {
          "min": 51,
          "max": 51
        },
        "reward_price_range": {
          "min": "0.0",
          "max": "0.0"
        },
        "rewards": [
          {
            "id": "4106",
            "name": "50% off sports shoe",
            ...
          }
        ]
      }
    ]
  },
  "error": {}
}

Potential Errors

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 404.2 - Event not found
  • 409.6.7 - Action limit has reached
  • 500 - Server side error

REDEEM

Redeems the user's available points to claim a reward identified by the given reward ID.

Syntax

GET /redeem.json

Parameters

  • reward_id - The numerical id of the desired reward

Example

/redeem.json?reward_id={reward_id}

Response

{
  "response": {
    "success": true,
    "user": {
      "user_id": "partner's user ID",
      "awarded_points": 1000,
      "redeemed_points": 300,
      "next_level_points": 5000,
      "points_to_next_level": 4000
    },
    "claim": 
    {
      "id": "123",
      "reward":{
        "id": "2001",
        "url": "http://www.somewebsite.com",
        "name": "some reward name",
        "short_name": "reward name", //reward's name for shorter display
        "category_name": "Electronics",
        "store_name": "some company name",
        "total_quantity": 100,
        "description": "reward description",
        "fine_print": "terms & conditions",
        "experience_points": 10000,
        "limit_per_player": 1,
        "price": "10", //reward's dollor value / other reward system points value
        "points": 200 //reward's value according to app's virtual currency
        "discount": "$10 off", //reward's discount percent value
        "start_date": "2012-9-1", //campaign start date
        "end_date": "2012-10-1", //campaign end date
        "image_url": "reward_image.png",
        "valid_until": "2012-11-1T00:00:00Z", //reward expiry date time
        "country_codes": [ // countries that the reward is meant for
          "US", 
          "CN"
        ]
      }        
    }
  },
  "error": {}
}

Potential Errors

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 404.1 - Reward not found
  • 409.5.4 - Points balance is insufficient
  • 409.5.5 - Experience points is insufficient
  • 409.5.6 - Limit per player has reached
  • 410.1.3 - No more reward codes to redeem
  • 412.1.1 - Reward is not available yet
  • 412.1.2 - Reward is not available anymore
  • 500 - Server side error

GIFT

Gift the user with the reward ignoring points required identified by the given reward ID.

Syntax

GET /gift.json

Parameters

  • reward_id - The numerical id of the desired reward

Example

/gift.json?reward_id={reward_id}

Response

{
  "response": {
    "success": true,
    "user": {
      "user_id": "partner's user ID",
      "awarded_points": 1000,
      "redeemed_points": 0,
      "next_level_points": 5000,
      "points_to_next_level": 4000
    },
    "claim": 
    {
      "id": "123",
      "reward":{
        "id": "2001",
        "url": "http://www.somewebsite.com",
        "name": "some reward name",
        "short_name": "reward name", //reward's name for shorter display
        "category_name": "Electronics",
        "store_name": "some company name",
        "total_quantity": 100,
        "description": "reward description",
        "fine_print": "terms & conditions",
        "experience_points": 10000,
        "limit_per_player": 1,
        "price": "10", //reward's dollor value / other reward system points value
        "points": 200 //reward's value according to app's virtual currency
        "discount": "$10 off", //reward's discount percent value
        "start_date": "2012-9-1", //campaign start date
        "end_date": "2012-10-1", //campaign end date
        "image_url": "reward_image.png",
        "valid_until": "2012-11-1T00:00:00Z", //reward expiry date time
        "country_codes": [ // countries that the reward is meant for
          "US", 
          "CN"
        ]
      }        
    }
  },
  "error": {}
}

Potential Errors

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 404.1 - Reward not found
  • 409.5.5 - Experience points is insufficient
  • 409.5.6 - Limit per player has reached
  • 410.1.3 - No more reward codes to redeem
  • 412.1.1 - Reward is not available yet
  • 412.1.2 - Reward is not available anymore
  • 500 - Server side error

PLAYER ACTIONS

Obtains list the latest 20 events triggered by the user.

Syntax

GET /recent_actions.json

Example

/recent_actions.json
Response

{
  "response": {
    "success": true,
    "recent_actions": [
      {
        "id": "689",
        "created_at": "1354776458", // a unix timestamp in UTC
        "event": {
          "id": "383",
          "name": "event1",
          "description": "desc"
        },
        "action": {
          "action_type": "Award Points",
          "message": "action message 1",
          "points": 1,
          "limit": null,
          "success": true
        }
      }
    ]
  }
}

Potential Errors

  • 400.0 - Unknown OAuth signature method
  • 401.0 - Invalid OAuth signature
  • 404.4 - Player not found
  • 500 - Server side error

CHANGE LOGS

version 1.12

  • add note about user id points shared

version 1.11

  • remove stores.json api

version 1.10

  • add gift.json api
  • add valid_until field to rewards

version 1.9

  • add event_id parameter for filtering in events api

version 1.8

  • add categories property to list Featured rewards in trigger api response

version 1.8

  • add minor update to escape underscore _ api
  • remove email field from displaying

version 1.7

  • add recent_actions.json api

version 1.6

  • add categories.json api
  • add category_name and store_name to rewards

version 1.5

  • remove code field from displaying
  • add limit_per_player to rewards

version 1.4

  • added error definitions

version 1.3

  • added reward_exp_points_range, reward_points_range & reward_price_range to stores.json

version 1.2

  • remove user_id as user id is pass for oAuth
  • source_uid is added as optional param for trigger.json
  • added status in the action response