--- updatedAt: 2025-02-13T21:53:26.000Z agentTools: projectIndex: https://developer-platform.vibes.com/llms.txt --- # Incentive Code API 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** * [Create a code issuance](https://developer-platform.vibes.com/reference/post_create-a-code-issuance) * [Get incentive code](https://developer-platform.vibes.com/reference/get_incentive-code) * [Get issuances for a code](https://developer-platform.vibes.com/reference/get_issuances-for-a-code) * [Redeem an incentive code](https://developer-platform.vibes.com/reference/post_redeem-an-incentive-code) * [Get redemptions for a code](https://developer-platform.vibes.com/reference/get_redemptions-for-a-code) # 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. ```json { "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. ```json { "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. ```json { "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" } ```