Reward Sciences Documentation

Current Version

The current API version is v2.

Consumers should explicitly specify the API version they wish to interact using the following HTTP accept header in all API requests:

Accept: application/vnd.rewardsciences.v2+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'

Tracking User Activities

Track a simple activity

idp: The identity provider can anything that represents the provider uniquely for your merchant.

Examples: email, CRM, internal-system, facebook, X or whatever you prefer.

Identity providers are case insensitive and leading/trailing spaces are ignored.
identity: The identity field specifies a unique identifier for the user withing the context of the specified provider. Values are also arbitrary, they could represent a unique email address, a user ID within an external platform or anything that can uniquely identify a user within it.
activity_type: Activity type represents a unique, case-insensitive, activity the user can perform. For example: ‘bought-coffee’, ‘redeemed-code’, ‘attended-event’, etc.

Endpoint

POST /activities

Parameters

Name	Description	Type
idp required	Name of the identity provider	string
identity required	Unique user identify within the identity provider	string
activity_type required	Activity identifier	string
fields	Custom fields	object

Request

Route

POST /activities

Headers

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

Body

{
  "idp": "facebook",
  "identity": "12345",
  "activity_type": "buys-coffee"
}

cURL

curl "https://api.rewardsciences.com//activities" -d '{"idp":"facebook","identity":"12345","activity_type":"buys-coffee"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Accept: application/vnd.rewardsciences.v2+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 1234"

Response

Simulated Response

Status

Headers

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

Body

{
  "id": 1090,
  "user_id": 9072
}

Track a simple activity with extra data

You can pass optional custom fields to associate with the tracked activity as metadata

Endpoint

POST /activities

Parameters

Name	Description	Type
idp required	Name of the identity provider	string
identity required	Unique user identify within the identity provider	string
activity_type required	Activity identifier	string
fields	Custom fields	object

Request

Route

POST /activities

Headers

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

Body

{
  "idp": "facebook",
  "identity": "12345",
  "activity_type": "buys-coffee",
  "fields": {
    "price": 1234,
    "currency": "usd"
  }
}

cURL

curl "https://api.rewardsciences.com//activities" -d '{"idp":"facebook","identity":"12345","activity_type":"buys-coffee","fields":{"price":1234,"currency":"usd"}}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Accept: application/vnd.rewardsciences.v2+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 1234"

Response

Simulated Response

Status

Headers

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

Body

{
  "id": 1091,
  "user_id": 9074
}

Managing users using external identities

Fetch user info using external identity

Endpoint

GET /idps/:idp/:identity/user

Request

Route

GET /idps/facebook/1234/user

Headers

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

Query Parameters

{}=

cURL

curl -g "https://api.rewardsciences.com//idps/facebook/1234/user" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Accept: application/vnd.rewardsciences.v2+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 1234"

Response

Simulated Response

Status

Headers

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

Body

{
  "user_id": 9076
}

Create a user using an external identity

Endpoint

POST /idps/:idp/:identity/user

Request

Route

POST /idps/facebook/1234/user

Headers

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

Body

{
}

cURL

curl "https://api.rewardsciences.com//idps/facebook/1234/user" -d '{}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Accept: application/vnd.rewardsciences.v2+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 1234"

Response

Simulated Response

Status

Headers

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

Body

{
  "user_id": 9078
}

Assigning external identities to a user

Assign a new external identity to a user

Endpoint

POST /users/:id/identities

Request

Route

POST /users/9080/identities

Headers

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

Body

{
  "idp": "facebook",
  "identity": "1234"
}

cURL

curl "https://api.rewardsciences.com//users/9080/identities" -d '{"idp":"facebook","identity":"1234"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Accept: application/vnd.rewardsciences.v2+json" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer 1234"

Response

Simulated Response

Status

Headers

Content-Type: application/json