Reward Sciences Documentation

Current Version

By default, all requests receive the v1 version of the API. We encourage you to explicitly request this version via the Accept header.

Accept: application/vnd.rewardsciences.v1+json

Schema

All API access is over HTTPS, and accessed from the https://api.rewardsciences.com.

All data is sent and received as JSON.

All timestamps are returned in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

Root Endpoint

You can issue a GET request to the root endpoint to get all the endpoint categories that the API supports:

curl https://api.rewardsciences.com

Authentication

The OAuth2 standard protocol is used to grant API access to each organization.

Authenticate your requests sending an OAuth2 token on their Authorization header.

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.rewardsciences.com

These tokens can be obtained on the Reward Sciences web app, under ‘Developer Settings/API Tokens’. If your API Tokens get compromised you can always revoke them and obtain new ones.

API Tokens are to be used on server-to-server scenarios only. Do not leak your API Tokens to your end users.

Pagination

Requests that return multiple items will be paginated to 25 items and return the first page by default. You can navigate through pages and override this behavior by using the following parameters:

Parameter Name Description Default Value
limit The number of items you want to be retrieved. 25
offset The number of items you want to skip before starting the retrieval. 0

Examples:

curl 'https://api.rewardsciences.com/reward_categories?limit=100&offset=0'

curl 'https://api.rewardsciences.com/reward_categories?limit=100&offset=100'

Operations

Our API is based on 4 key operations:

  • Identify a User
  • Track an Activity
  • List Rewards
  • Redeedem a reward or bid on a reward auction

Users

Identify a user

This endpoint lets you tie a user with his/her activities. You’ll want to identify a user with any relevant information as soon as they log-in or sign-up.

Endpoint

POST users

Parameters

Name Description
email required The user's email address
first_name The user's first name
last_name The user's last name

Request

Route

POST users

Headers

Accept: application/vnd.rewardsciences.v1+json
Content-Type: application/json
Host: api.rewardsciences.com
Authorization: Bearer e203961b907278a6a4a12d9bc7af5022

Body

{
  "user_id": "029vr8mf6r",
  "email": "james@example.com",
  "first_name": "James",
  "last_name": "Smith"
}

cURL

curl "https://api.rewardsciences.com/users" -d '{"user_id":"029vr8mf6r","email":"james@example.com","first_name":"James","last_name":"Smith"}' -X POST \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer e203961b907278a6a4a12d9bc7af5022"

Response

Simulated Response

Status

201

Headers

Content-Type: application/json; charset=utf-8
ETag: W/"8284dc0594c52be5c4e476513d044b4e"

Body

{
  "id": 1837,
  "email": "james@example.com",
  "first_name": "James",
  "last_name": "Smith",
  "balance": 0
}

Get a user's details

Endpoint

GET users/:id

Request

Route

GET users/1839

Headers

Accept: application/vnd.rewardsciences.v1+json
Content-Type: application/json
Host: api.rewardsciences.com
Authorization: Bearer 08526a1a8a772b553faee025aaccb9ea

Query Parameters

{}=

cURL

curl "https://api.rewardsciences.com/users/1839" -X GET \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 08526a1a8a772b553faee025aaccb9ea"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
ETag: W/"e68c4e2eccb22a550c74d6a44cf1662c"

Body

{
  "id": 1839,
  "email": "james@example.com",
  "first_name": "James",
  "last_name": "Smith",
  "balance": 0
}

Activities

Track an activity

This endpoint lets you track the activities your users perform.

Endpoint

POST activities

Parameters

Name Description
user_id required The id of the user who is performing the activity.
activity_type required The type of activity the user is performing. Example: 'purchased-a-product'
price The price related to the activity, if any. Expressed in USD
record_id The ID for the record associated with the activity in your database.

Request

Route

POST activities

Headers

Accept: application/vnd.rewardsciences.v1+json
Content-Type: application/json
Host: api.rewardsciences.com
Authorization: Bearer 5af03f5f0c9f8b32a67a055b940360ec

Body

{
  "user_id": 1840,
  "activity_type": "purchased-a-product"
}

cURL

curl "https://api.rewardsciences.com/activities" -d '{"user_id":1840,"activity_type":"purchased-a-product"}' -X POST \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 5af03f5f0c9f8b32a67a055b940360ec"

Response

Simulated Response

Status

201

Headers

Content-Type: application/json; charset=utf-8
ETag: W/"bbdffeb68a045953740c8828a2e92e44"

Body

{
  "id": 345,
  "activity_type": "purchased-a-product",
  "price": null,
  "record_id": null,
  "created_at": "2016-09-16T01:44:58.250Z",
  "user": {
    "id": 1840,
    "balance": 80
  }
}

Reward categories

List all reward categories

This endpoint lets you list all the available reward categories.

Endpoint

GET reward_categories

Parameters

Name Description
limit The number of categories you want to be retrieved. Defaults to 25.
offset The number of categories you want to skip before starting the retrieval. Defaults to 0. This parameter will allow you to paginate through the reward collection. For example if there are 50 available categories and you want to get pages of 25 categories each, you'll pass `limit: 25, offset: 0` to get the first page and `limit: 25, offset: 25` to get the second page.

Request

Route

GET reward_categories

Headers

Accept: application/vnd.rewardsciences.v1+json
Content-Type: application/json
Host: api.rewardsciences.com
Authorization: Bearer b809a62dbc8c9e19f5fe98b8a630e5dc

Query Parameters

{}=

cURL

curl "https://api.rewardsciences.com/reward_categories" -X GET \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer b809a62dbc8c9e19f5fe98b8a630e5dc"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
ETag: W/"7f0816497b866f5cefed72e444948ae1"

Body

{
  "data": [
    {
      "id": 229,
      "name": "Experience",
      "description": null,
      "image": ""
    }
  ],
  "meta": {
    "count": 1,
    "limit": 25,
    "offset": 0
  }
}

Rewards

List all rewards

List all the available rewards.

Endpoint

GET rewards

Parameters

Name Description
category_id The id of the category to filter rewards by. Defaults to null.
limit The number of rewards you want to be retrieved. Defaults to 25.
offset The number of rewards you want to skip before starting the retrieval. Defaults to 0. This parameter will allow you to paginate through the reward collection. For example if there are 50 available rewards and you want to get pages of 25 rewards each, you'll pass `limit: 25, offset: 0` to get the first page and `limit: 25, offset: 25` to get the second page.

Request

Route

GET rewards

Headers

Accept: application/vnd.rewardsciences.v1+json
Content-Type: application/json
Host: api.rewardsciences.com
Authorization: Bearer f427c14bae4a894eeec4ba2fcda098ed

Query Parameters

{}=

cURL

curl "https://api.rewardsciences.com/rewards" -X GET \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer f427c14bae4a894eeec4ba2fcda098ed"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
ETag: W/"36fba5c67c1868c1ec755e7316690d45"

Body

{
  "data": [
    {
      "id": 1129,
      "title": "Experience Pristine Tasmania",
      "image": "",
      "count": 1,
      "overview": "At a quae nulla quas accusantium. Tempora voluptatum nihil velit omnis aut. Saepe reprehenderit inventore itaque laborum vitae quos.",
      "detail": "Sunt sunt tenetur. Quia doloremque voluptas amet asperiores. Sequi nemo voluptatem vel iure consequatur beatae sed. Aspernatur eaque veritatis. Ut consequuntur eos.",
      "points": "300.0"
    }
  ],
  "meta": {
    "count": 1,
    "limit": 25,
    "offset": 0
  }
}

Get a reward's details

Get the details for a specific reward.

Endpoint

GET rewards/:id

Request

Route

GET rewards/1133

Headers

Accept: application/vnd.rewardsciences.v1+json
Content-Type: application/json
Host: api.rewardsciences.com
Authorization: Bearer 9b4c551046bdffbfff7f2d4db952de23

Query Parameters

{}=

cURL

curl "https://api.rewardsciences.com/rewards/1133" -X GET \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 9b4c551046bdffbfff7f2d4db952de23"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
ETag: W/"147d93f55a3da6bb0b0f1e91dc8ebd09"

Body

{
  "id": 1133,
  "title": "Experience Pristine Tasmania",
  "image": "",
  "count": 1,
  "overview": "Dolores omnis autem. Maxime illum placeat possimus ad magnam. Quia dolorem nostrum.",
  "detail": "Blanditiis est hic. Labore rerum unde sit omnis cumque sed. Quia dolor repellat voluptatem quos.",
  "points": "300.0"
}

Redeem a reward

Redeem a reward.

Endpoint

POST rewards/:id/redemptions

Parameters

Name Description
user_id required The id of the user who is redeeming the reward.

Request

Route

POST rewards/1134/redemptions

Headers

Accept: application/vnd.rewardsciences.v1+json
Content-Type: application/json
Host: api.rewardsciences.com
Authorization: Bearer 185ba770224b0eb299690f9e83ba7f9e

Body

{
  "user_id": 1845
}

cURL

curl "https://api.rewardsciences.com/rewards/1134/redemptions" -d '{"user_id":1845}' -X POST \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 185ba770224b0eb299690f9e83ba7f9e"

Response

Simulated Response

Status

201

Headers

Content-Type: application/json; charset=utf-8
ETag: W/"9126635ea05f179a769cd2d5f5ff0c03"

Body

{
  "amount": 300,
  "user": {
    "id": 1845,
    "balance": 10
  },
  "reward": {
    "id": 1134,
    "title": "Experience Pristine Tasmania"
  }
}

Bid on an auction

Endpoint

POST rewards/:id/bids

Parameters

Name Description
user_id required The id of the user who is bidding on the reward auction.
amount required The amount can be either "max", when max bidding, or an integer, specifying how many points the user wants to bid on the auction.

Request

Route

POST rewards/1137/bids

Headers

Accept: application/vnd.rewardsciences.v1+json
Content-Type: application/json
Host: api.rewardsciences.com
Authorization: Bearer 57848bdf9faf207c2412a29474faee7e

Body

{
  "user_id": 1848,
  "amount": 100
}

cURL

curl "https://api.rewardsciences.com/rewards/1137/bids" -d '{"user_id":1848,"amount":100}' -X POST \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 57848bdf9faf207c2412a29474faee7e"

Response

Simulated Response

Status

201

Headers

Content-Type: application/json; charset=utf-8
ETag: W/"b64aca05542d8a0f65ed27522f0c63ec"

Body

{
  "amount": 100,
  "user": {
    "id": 1848,
    "balance": 10
  },
  "reward": {
    "id": 1137,
    "title": "Experience Pristine Tasmania"
  }
}