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/1454

Headers

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

Query Parameters

{}=

cURL

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

Response

Simulated Response

Status

200

Headers

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

Body

{
  "id": 1454,
  "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 43fb750a30ffe2294fc23a996e75c3b9

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 43fb750a30ffe2294fc23a996e75c3b9"

Response

Simulated Response

Status

201

Headers

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

Body

{
  "id": 1455,
  "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 bbc1239af3aa99054b02472fb2e9162d

Body

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

cURL

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

Response

Simulated Response

Status

201

Headers

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

Body

{
  "id": 338,
  "activity_type": "purchased-a-product",
  "price": null,
  "record_id": null,
  "custom_fields": null,
  "created_at": "2019-02-19T13:28:01.953Z",
  "user": {
    "id": 1458,
    "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 c485405c8a6cefee3b07e193054fcdd1

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 c485405c8a6cefee3b07e193054fcdd1"

Response

Simulated Response

Status

200

Headers

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

Body

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

Rewards

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

Headers

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

Body

{
  "user_id": 1461
}

cURL

curl "https://api.rewardsciences.com/rewards/565/redemptions" -d '{"user_id":1461}' -X POST \
	-H "Accept: application/vnd.rewardsciences.v1+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 81d2bf50fdca57b74c204269b01759a0"

Response

Simulated Response

Status

201

Headers

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

Body

{
  "amount": 200,
  "user": {
    "id": 1461,
    "balance": 110
  },
  "reward": {
    "id": 565,
    "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 f5091c74144b7c562e2ff2dab03eb8de

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 f5091c74144b7c562e2ff2dab03eb8de"

Response

Simulated Response

Status

200

Headers

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

Body

{
  "data": [
    {
      "id": 570,
      "title": "Experience Pristine Tasmania",
      "image": null,
      "count": 1,
      "overview": "Quos in officia sint sequi. Quia voluptas sunt atque at. Eum cum voluptatem est enim repellendus blanditiis. Et suscipit minus.",
      "points": "200.0",
      "tags": [

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

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

Headers

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

Body

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

cURL

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

Response

Simulated Response

Status

201

Headers

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

Body

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

Get a reward's details

Get the details for a specific reward.

Endpoint

GET rewards/:id

Request

Route

GET rewards/580

Headers

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

Query Parameters

{}=

cURL

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

Response

Simulated Response

Status

200

Headers

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

Body

{
  "id": 580,
  "title": "Experience Pristine Tasmania",
  "image": null,
  "count": 1,
  "overview": "Praesentium voluptate similique enim ex. Velit est quae odit non voluptatem porro tenetur. Quidem molestiae aut est.",
  "points": "200.0",
  "tags": [

  ]
}