Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Last Updated:

Lastupdatedate

Livesearch
placeholderSearch the Vibes Developer Wiki
typepage



Overview

The Incentives Manager is a module in the Vibes Mobile Engagement Platform that allows the issuance and redemption of incentive codes.

When issuing a code, you must provide the pool that you want the code to come from. However, if you want to see the status of a code, or redeem a code, you only need to provide the company and code, and we'll figure out which pool the code is on. This enables your redemption system to not worry about pools, and only check the validity of codes regardless of what pool they came from.


Panel
borderColor#2B9CD7

Topics in this Section

Page Tree
root@self
startDepth2




Incentive Pool Entity

The following is the JSON representation of an Incentive Pool entity within the APIs.

Code Block
{
  "id": 42,
  "name": "Store Coupons",
  "issuance_allowed": true,
  "redemption_allowed": true,
  "incentive_codes": {
    "total": 500,
    "issued": 143,
    "remaining": 357,
    "low_threshold": 100,
    "max_characters": 50
  },
  "distribution": {
    "method": "unique"
  },
  "notification_email_address": "your.name@vibes.com",
  "created_at":"2017-01-01T12:00Z",
  "updated_at":"2017-04-07T12:00Z",
  "url":"/companies/:company_id/incentives/pools/:pool_id"
}

Elements

Data Element

Type

Max Char Length

Description

id

Integer

20

Vibes unique identifier for each Incentive Pool.

name

String


The name of the Incentive Pool.

issuance_allowedBoolean
Whether issuance of codes is allowed.
redemption_allowedBoolean
Whether redemption of codes is allowed.

incentive_codes

Object


An object describing this pool's Incentive Codes.
incentive_codes.totalInteger
Total number of Incentive Codes in the pool.

incentive_codes.remaining

Integer


Remaining number of available Incentive Codes in the pool.

incentive_codes.low_threshold

Integer


The number of remaining Incentive Codes where a notification is sent.

incentive_codes.max_charactersInteger
The maximum number of characters allowed in an Incentive Code in this pool.
distributionObject
An object describing this pool's distribution type.
distribution.methodString10The method of distribution (unique|multi).
notification_email_addressString
The email address for all notifications.
created_atTimestamp20The date this pool was created. It should be in the ISO 8601 format - for example: 2017-01-01T12:00Z.
updated_atTimestamp20The date this pool was last updated. It should be in the ISO 8601 format - for example: 2017-04-07T12:00Z.
urlString50The URL to access this resource.

Incentive Code Entity

The following is the JSON representation of an Incentive Code entity within the APIs.

Code Block
{
  "code": "coupon01",
  "active": true,
  "issuances": {
    "total": 2,
    "unique": 1
  },
  "redemptions": {
    "total": 1,
    "unique": 1
  },
  "incentive_pool": {
    "id": 42,
    "url": "/companies/:id/incentives/pools/:pool_id"
  },
  "created_at: "2017-01-18T17:24Z",
  "updated_at: "2017-04-18T17:24Z",
  "url": "/companies/:company_id/incentives/codes/:code"
}

Elements

Data ElementTypeMax Char LengthDescription

incentive_pool_id

Integer

20

Vibes unique identifier for each Incentive Pool.

code

String


The incentive code

activeBoolean
Whether issuance of the incentive code is currently allowed.
issuancesObject
An object describing this code's issuances.
issuances.totalInteger
The total number of times this code has been issued.
issuances.uniqueInteger
The number of unique times this code has been issued.
redemptionsObject
An object describing this code's redemptions.
redemptions.totalInteger
The total number of times this code has been redeemed.
redemptions.uniqueInteger
The number of unique times this code has been redeemed.
created_atTimestamp
The date this code was created. It should be in the ISO 8601 format - for example: 2017-01-18T17:24Z.
updated_atTimestamp
The date this code was last updated. It should be in the ISO 8601 format - for example: 2017-04-18T17:24Z.
urlString
The URL to access this resource.

Incentive Code Issuance Entity

The following is the JSON representation of an Incentive Code entity within the APIs.

Code Block
{
  "id": 8,
  "external_issuee_id": "user@mycompany.com",
  "issuee_id": "0eef8961-7568-485b-9b13-fc7dbd1cf712",
  "referring_application": "system",
  "referring_application_ref_id": "1234",
  "incentive_code": {
    "code": "aabb-ccdd",
    "url": "/companies/:company_id/incentives/codes/:code"
  },
  "incentive_pool": {
    "id": 1,
    "url": "/companies/:company_id/incentives/pools/:pool_id"
  },
  "updated_at": "2017-04-13T18:34Z",
  "created_at": "2017-02-13T18:34Z"
}

Elements

Data ElementTypeDescription

id

Integer

Vibes unique identifier for each issuance.

external_issuee_idStringUnique external issuee ID.
issuee_idStringVibes generated issuee ID.
referring_applicationStringApplication issuing the code.
referring_application_ref_idStringApplication reference ID (campaign ID).

incentive_code

Object

An object describing this Issuance's Incentive Code.
incentive_code.codeStringIncentive Code.

incentive_code.url

String

Incentive Code's URL.

incentive_pool

Object

An object describing this Issuance's Pool.

incentive_pool.idIntegerThe unique identifier for the pool.
incentive_pool.urlStringThe URL to access the Incentive Pool resource.
created_atTimestampThe date this Issuance was created. It should be in the ISO 8601 format - for example: 2017-02-13T18:34Z.
updated_atTimestampThe date this Issuance was last updated. It should be in the ISO 8601 format - for example: 2017-04-13T18:34Z.

Incentive Code Redemption Entity

The following is the JSON representation of an Incentive Code Redemption entity within the APIs.

Code Block
{
  "id": 8,
  "external_issuee_id": "user@mycompany.com",
  "issuee_id": "0eef8961-7568-485b-9b13-fc7dbd1cf712",
  "referring_application": "system",
  "referring_application_ref_id": "1234",
  "incentive_code": {
    "code": "aabb-ccdd",
    "url": "/companies/:company_id/incentives/codes/:code"
  },
  "incentive_pool": {
    "id": 1,
    "url": "/companies/:company_id/incentives/pools/1"
  },
  "updated_at": "2017-04-13T18:34Z",
  "created_at": "2017-02-13T18:34Z"
}

Elements

Data ElementTypeDescription

id

Integer

Vibes unique identifier for each redemption.

external_issuee_idStringUnique external issuee ID.
issuee_idStringVibes-generated issuee ID.

referring_application

String

Application redeeming the code.

referring_application_ref_idStringApplication reference ID (campaign ID).

incentive_code

Object

An object describing this Redemption's Incentive Code.
incentive_code.codeStringIncentive Code.

incentive_code.url

String

Incentive Code's URL.

incentive_pool

Object

An object describing this Redemption's pool.

incentive_pool.idIntegerThe unique identifier for the pool.
incentive_pool.urlStringPool's URL.
created_atTimestampThe date this Redemption was created. It should be in the ISO 8601 format - for example: 2017-04-13T18:34Z.
updated_atTimestampThe date this Redemption was last updated. It should be in the ISO 8601 format - for example: 2017-02-13T18:34Z.