RewardSTACK™ API Documentation

Incentive and Reward Management Platform API Documentation: RewardSTACK™

Welcome to our RewardSTACK ‘s API documentation! RewardSTACK™, our reward and incentive platform, offers a comprehensive incentive and reward management system to help businesses motivate and reward employees, customers, and partners. The system is designed to be flexible and customizable, manages incentive and reward programs tailored to their specific needs and goals. Our API documentation provides developers with all the necessary information to integrate our platform’s incentive and reward management system with their own systems and applications. By using our API, developers can create a seamless and integrated experience for their end-users, ensuring maximum engagement and motivation. We are committed to providing our clients with a reliable and user-friendly API, and we hope our API documentation will help developers easily integrate our platform into their applications.

RewardSTACK API Documentation Overview

This Quickstart guide will walk you through the most common use case, a points based reward program for RewardSTACK™.

1. Generate a JSON Web Token for authentication.
2. Create a participant.
3. Issue points to the participant.
4. Sign the participant into the marketplace.

For a full specification of RewardSTACK™ API please see the Full RewardSTACK™ API Documentation.

Prerequisites

Contact Sales to register for a RewardSTACK™ Account. An All Digital Rewards implementation specialist will generate an account for you and fast track your organization and program setup. You will be invited to setup an email address and password to authenticate against the API. You will also be provided with two additional pieces of information.

Organization ID – This is the unique identifier for the organization your user is associated with.

Program ID – This is the unique identifier for the initial program we will assign participants to.

Request a JSON Web Token

JSON Web tokens are time restricted authentication claims used to authorize all of your requests to the API. In order to request a JWT from RewardSTACK™ you will make a request to the /token endpoint using basic authentication with your RewardSTACK™ account details.

curl --location 'https://admin.alldigitalrewards.com/token' \
--header 'Authorization: Basic dGVzdEBleGFtcGxlLmNvbTpleGFtcGxl'

{
    "token": "YOUR-JWT-TOKEN",
    "expires": 1681235094
}

Once the token response is received, save the value of the token property and the expires unix timestamp. This token will be valid for 2 hours from the time it was created. Since token generation is computationally expensive, only request a new token when your current token nears expiration.

Create a Participant

Participants in RewardSTACK™ represent the human you will be providing points or rewards to. The minimum requirements for creating a participant are a globally unique identifier and an email address. It is advisable to also include a first and last name if possible to enhance the quality of communication to your participant so we will use that in our example below. Please see the participant model for a full description of all available properties.

When generating this request we will make use of the following variables:

• Program ID: PROGRAMID
• Participant ID: 74fc916f-e945-4c09-a85b-38f6a53bba74
• JWT: YOUR-JWT-TOKEN

curl --location 'https://admin.alldigitalrewards.com/token' \
curl --location 'https://admin.alldigitalrewards.com/api/program/PROGRAMID/participant' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-JWT-TOKEN' \
--data-raw '{
  "unique_id": "74fc916f-e945-4c09-a85b-38f6a53bba74",
  "firstname": "Josh",
  "lastname": "Houghtelin",
  "email_address": "noreply@alldigitalrewards.com",
}'

{
    "email_address": "noreply@alldigitalrewards.com",
    "unique_id": "74fc916f-e945-4c09-a85b-38f6a53bba74",
    "credit": null,
    "firstname": "Josh",
    "lastname": "Houghtelin",
    "phone": null,
    "birthdate": null,
    "status": "ACTIVE",
    "deactivated_at": null,
    "language": "en_US",
    "active": 1,
    "created_at": "2023-04-11 16:17:47",
    "updated_at": null,
    "password_updated_at": null,
    "address": null,
    "program": "PROGRAMID",
    "organization": "ORGANIZATIONID",
    "meta": []
}

Once the token response is received, save the value of the token property and the expires unix timestamp. This token will be valid for 2 hours from the time it was created. Since token generation is computationally expensive, only request a new token when your current token nears expiration.

Create a Participant

Participants in RewardSTACK™ represent the human you will be providing points or rewards to. The minimum requirements for creating a participant are a globally unique identifier and an email address. It is advisable to also include a first and last name if possible to enhance the quality of communication to your participant so we will use that in our example below. Please see the participant model for a full description of all available properties.

When generating this request we will make use of the following variables:

• Program ID: PROGRAMID
• Participant ID: 74fc916f-e945-4c09-a85b-38f6a53bba74
• JWT: YOUR-JWT-TOKEN

curl --location 'https://admin.alldigitalrewards.com/api/program/PROGRAMID/participant' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-JWT-TOKEN' \
--data-raw '{
  "unique_id": "74fc916f-e945-4c09-a85b-38f6a53bba74",
  "firstname": "Josh",
  "lastname": "Houghtelin",
  "email_address": "noreply@alldigitalrewards.com",
}'

{
    "email_address": "noreply@alldigitalrewards.com",
    "unique_id": "74fc916f-e945-4c09-a85b-38f6a53bba74",
    "credit": null,
    "firstname": "Josh",
    "lastname": "Houghtelin",
    "phone": null,
    "birthdate": null,
    "status": "ACTIVE",
    "deactivated_at": null,
    "language": "en_US",
    "active": 1,
    "created_at": "2023-04-11 16:17:47",
    "updated_at": null,
    "password_updated_at": null,
    "address": null,
    "program": "PROGRAMID",
    "organization": "ORGANIZATIONID",
    "meta": []
}

Once the participant has been successfully created, save the unique participant ID for future reference as this will be used in all calls to read, modify or audit the participant’s activity.

Issue Points to the Participant

In order for a participant to redeem for rewards from a marketplace they will need points to spend. Points are effectively the marketplace currency. A participant may still sign into a marketplace without points to browse the products and view their transaction history. In the following example we will issue 100 points to the participant we have just created using the point adjustment endpoint.

When generating this request we will make use of the following variables:

• Program ID: PROGRAMID
• Participant ID: 74fc916f-e945-4c09-a85b-38f6a53bba74
• JWT: YOUR-JWT-TOKEN

The Program ID and Participant ID are in the URL.

The adjustment type can be one of credit or debit. Since we are issuing points we are using the adjustment type credit.

curl --location 'https://admin.alldigitalrewards.com/api/program/PROGRAMID/participant/74fc916f-e945-4c09-a85b-38f6a53bba74/adjustment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-JWT-TOKEN' \
--data '{
  "type": "credit",
  "amount": "100"
}'

{
    "amount": "100.00000",
    "type": "credit",
    "transaction_id": null,
    "transaction_item_id": null,
    "reference": null,
    "description": null,
    "completed_at": null,
    "activity": null,
    "id": 19866,
    "created_at": "2023-04-11 16:33:15",
    "updated_at": "2023-04-11 16:33:15",
    "user": {...}
}

For a full description of the Adjustment response, please see the PointRead model.

Sign the Participant into the marketplace

A participant may now sign into the marketplace to spend the points that were issued to them. To do so we are going to utilize the Participant SSO endpoint.

When generating this request we will make use of the same variables in the previous step:

• Program ID: PROGRAMID
• Participant ID: 74fc916f-e945-4c09-a85b-38f6a53bba74
• JWT: YOUR-JWT-TOKEN

Similar to the adjustment endpoint, the Program ID and Participant ID are placed in the URL and the JWT token is used in the Authorization: Bearer header. There is no content body in this request.

curl --location --request POST 'https://admin.adrqa.info/api/program/PROGRAMID/participant/74fc916f-e945-4c09-a85b-38f6a53bba74/sso' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-JWT-TOKEN'

{
    "token": "PARTICIPANT-SSO-TOKEN-STRING",
    "participant": "74fc916f-e945-4c09-a85b-38f6a53bba74",
    "domain": "marketplace.adrdemo.com",
    "exchange": "https://main.marketplace.adrdemo.com/?authenticate=PARTICIPANT-SSO-TOKEN-STRING&participant=74fc916f-e945-4c09-a85b-38f6a53bba74&lang=en_US&country=US"
}

When the response is received, open a browser or redirect the participant in their current browser to the full string found in the exchange property of the response. This begins the authorization process in the marketplace that will validate the token and generate a session.  

Have questions or want more info?