Getting started

Base URL

Send every request to https://rewards-api.bettermoney.com.

Paths in these docs are relative to /api/v1/rewards, so GET /programs is GET https://rewards-api.bettermoney.com/api/v1/rewards/programs. Your sandbox and live accounts both use this host.

Sandbox and live accounts

You get two accounts on the same API host, each with its own API keys. The key you send decides which account a request works in, so the base URL stays the same.

Account	What’s in it	Use it to
Sandbox	A sample program with participants, activity and rewards already filled in	Explore the API and build your integration against realistic data
Live	Your own programs and participants. It starts empty.	Run your real program

Data never crosses accounts.

Keep the API host and key in your configuration, so switching accounts is a config change, not a code change:

REWARDS_API_URL=https://rewards-api.bettermoney.com

# Your sandbox or live account key. Keys start with rk_live_. Keep the key on your server and never
# send it to the browser. To only show participants their rewards, use a read-only key (one program).
REWARDS_API_KEY=rk_live_…

# Optional: the program to use. With a read-only key, leave it empty: GET /programs returns the key's one program.
REWARDS_PROGRAM_ID=

To switch accounts, change REWARDS_API_KEY.

Authentication

Send your API key in the x-api-key header of every request.

GET /api/v1/rewards/programs
x-api-key: rk_live_…

TBMC issues and revokes keys. Store a key when you receive it: it can’t be shown again. Keys start with rk_live_.

A read-only key that calls POST, PATCH or DELETE gets 403.
A read-only key that names another program gets 404 Program not found, as does any program, rule or participant that doesn’t belong to your account.
Keep keys on your servers. To show participants their rewards in your product, call the API from your server with a read-only key, and return only the signed-in participant’s records.

Overview

Conventions and errors