Our Incentive Code API allows you to manage, store, and issue unique incentive codes to your end users. You can also use the API to view a code’s status, manually redeem a code, and more.

Before we begin, we’d like to define the three different types of entities that you may see while performing API methods.

An incentive code entity is a record of the individual code delivered to the end user.
A code issuance entity is a record of an incentive code issuance. Each time the code is issued, a new issuance entity will be created.
A code redemption entity is a record of an incentive code being redeemed.

Available API Methods

Incentive Code Entity

Elements & Attributes

Data Element	Type	Description
`incentive_pool_id`	Integer	The unique identifier for the incentive pool from which this code is issued. Max 20 characters.
`code`	String	The incentive code
`active`	Boolean	Whether issuance of the incentive code is currently allowed.
`issuances`	Object	An object describing this code's issuances.
`issuances.total`	Integer	The total number of times this code has been issued.
`issuances.unique`	Integer	The number of unique times this code has been issued.
`redemptions`	Object	An object describing this code's redemptions.
`redemptions.total`	Integer	The total number of times this code has been redeemed.
`redemptions.unique`	Integer	The number of unique times this code has been redeemed.
`created_at`	Timestamp	The date this code was created. It should be in the ISO 8601 format - for example: 2017-01-18T17:24Z.
`updated_at`	Timestamp	The date this code was last updated. It should be in the ISO 8601 format - for example: 2017-04-18T17:24Z.
`url`	String	The URL to access this resource.

Example Entity

The following is the JSON representation of an incentive code entity within the APIs.

{
  "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"
}

Code Issuance Entity

Elements & Attributes

Data Element	Type	Description
`id`	Integer	A unique identifier for each incentive pool. This is automatically generated by the Vibes system.
`external_issuee_id`	String	Unique external issuee ID.
`issuee_id`	String	Vibes-generated issuee ID.
`referring_application`	String	Application issuing the code.
`referring_application_ref_id`	String	Application reference ID (campaign ID).
`incentive_code`	Object	An object describing this issuance's incentive code.
`incentive_code.code`	String	Incentive code.
`incentive_code.url`	String	The URL to access the incentive pool resource.
`created_at`	Timestamp	The date this issuance was created. It should be in the ISO 8601 format - for example: 2017-02-13T18:34Z.
`updated_at`	Timestamp	The date this issuance was last updated. It should be in the ISO 8601 format - for example: 2017-04-13T18:34Z.

Entity Example

The following is the JSON representation of a code issuance entity within the APIs.

{
  "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"
}

Code Redemption Entity

Elements & Attributes

Data Element	Type	Description
`id`	Integer	Vibes-generated unique identifier for each redemption.
`external_issuee_id`	String	Unique external ID for the user to whom the code was issued.
`issuee_id`	String	Vibes-generated ID for the user to whom the code was issued.
`referring_application`	String	Application redeeming the code.
`referring_application_ref_id`	String	Application reference ID (campaign ID).
`incentive_code`	Object	An object describing this redemption's incentive code.
`incentive_code.code`	String	Incentive code.
`incentive_code.url`	String	Incentive code's URL.
`incentive_pool`	Object	An object describing the incentive pool this redemption’s code came from.
`incentive_pool.id`	Integer	The unique identifier for the pool.
`incentive_pool.url`	String	Pool's URL.
`created_at`	Timestamp	The date this redemption was created. It should be in the ISO 8601 format - for example: 2017-04-13T18:34Z.
`updated_at`	Timestamp	The date this redemption was last updated. It should be in the ISO 8601 format - for example: 2017-02-13T18:34Z.

Example Entity

The following is the JSON representation of a code redemption entity within the APIs.

{
  "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"
}