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

Get a user's details

Endpoint

GET users/:id

Request

Route

GET users/1626

Headers

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

Query Parameters

{}=

cURL

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

Response

Simulated Response

Status

200

Headers

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

Body

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

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 82880225bf7c41593c128ee86ab918d4

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 82880225bf7c41593c128ee86ab918d4"

Response

Simulated Response

Status

201

Headers

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

Body

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

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 a75d182806ebb3f75193884e41bbba4b

Body

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

cURL

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

Response

Simulated Response

Status

201

Headers

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

Body

{
  "id": 377,
  "activity_type": "purchased-a-product",
  "price": null,
  "record_id": null,
  "custom_fields": null,
  "created_at": "2019-06-17T19:31:31.216Z",
  "user": {
    "id": 1621,
    "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 4341905683c30206f82bd105222e1f0b

Query Parameters

{}=

cURL

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

Response

Simulated Response

Status

200

Headers

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

Body

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

Rewards

Get a reward's details

Get the details for a specific reward.

Endpoint

GET rewards/:id

Request

Route

GET rewards/572

Headers

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

Query Parameters

{}=

cURL

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

Response

Simulated Response

Status

200

Headers

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

Body

{
  "id": 572,
  "title": "Experience Pristine Tasmania",
  "image": null,
  "count": 1,
  "overview": "Corrupti exercitationem non. Et officiis aut. Illo sapiente ut.",
  "points": "200.0",
  "tags": [

  ]
}

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/576/bids

Headers

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

Body

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

cURL

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

Response

Simulated Response

Status

201

Headers

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

Body

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

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 b8a581f15655b5edb9c1671512595a46

Query Parameters

{}=

cURL

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

Response

Simulated Response

Status

200

Headers

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

Body

{
  "data": [
    {
      "id": 563,
      "title": "Experience Pristine Tasmania",
      "image": null,
      "count": 1,
      "overview": "Enim ad aliquid. Sit aut sed. Exercitationem magni est.",
      "points": "200.0",
      "tags": [

      ]
    }
  ],
  "meta": {
    "count": 1,
    "limit": null,
    "offset": null
  }
}

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/570/redemptions

Headers

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

Body

{
  "user_id": 1615
}

cURL

curl "https://api.rewardsciences.com/rewards/570/redemptions" -d '{"user_id":1615}' -X POST \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 872cae757bac9bde1c04db158d253fc1"

Response

Simulated Response

Status

201

Headers

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

Body

{
  "amount": 200,
  "user": {
    "id": 1615,
    "balance": 110
  },
  "reward": {
    "id": 570,
    "title": "Experience Pristine Tasmania"
  }
}