Compass API reference
Compass provides a REST API that lets you create, read, update, and delete data in
This document describes our authentication model, API endpoints, and error handling
Compass uses a parameter based authentication model to authenticate requests to the
Every Compass API call should include the api key in the parameters. The Compass
API expects these values to be keyed as api_key.
Getting Your API Key
Your Compass api_key is available on the Settings page. To navigate to the Settings
page, log into your Compass account, click on the settings on the bottom left navigation,
and select API Management.
Here is an example cURL request to the Events API showing the params needed to
authenticate the request.
.curl --location --request POST
--header 'Content-Type: application/json'
The API endpoints documented below describe how to create, read, update, and delete
data in Compass.
User API endpoints
Registration of your company account on Compass automatically creates one super
admin user on the platform. You can get information about user profiles or enrich
compass user profiles with our API. You can also create user profiles from your
Get User Profiles API
The Get User Profiles API lets you download user profiles from Compass. There are
two ways to get user profiles. The first way is to download user profiles that have a
specific attribute. For example, you can download a list of users that have an admin role
or they belong to a specific location. The second way to download user profiles is by
requesting the specific users needed.
Upload User Profiles API
The Upload User Profiles API enables you to create or update user profiles in Compass.
For example, you can use this API to update a user profile to include information, such
as user role, type, location, department, Adding more information to user profiles in
Compass enables you to create richer reports and run targeted campaigns.
Event API endpoints
Events represent the actions or the performance information of the users generated on
your platform that will be used by Compass to compute the incentives and rewards. .
Examples are standard events like sales transactions, deliveries, invoices, policy data
and custom events you define as behaviors, such as transings, attendance etc
Here are the API endpoints available to interact with the event object:
Get Event List API
The Get Events List API lets you get all the event types created on Compass. You can
use this to get a reference to the specific event that you want to access or upload.
Get Event Template API
The Get Event Template API enables you to access the structure of the specific event.
You can use the response of the API to create the payload for a separate upload events
API mentioned below.
Upload Events API
The Upload Events API enables you to upload events from external systems to
Compass. You can use this API to add new events on the systems such as sales
transactions. Add events in real-time into Compass to update your incentive games and
calculate up to date incentives and rewards
Master API endpoints
Compass allows the use of certain standard master reference tables such as product
master, calendar master and also custom masters. The information in the reference
masters can be used to enrich your events information with additional attribution and
create richer games.
Here are the API endpoints available to interact with the master object:
Get Master List API
The Get Master List API lets you get all the Master tables created on Compass. You
can use this to get a reference to the specific Master table that you want to access or
Get Master Template API
The Get Event Template API enables you to access the structure of the specific master.
You can use the response of the API to create the payload for a separate upload master
API mentioned below.
Upload Masters API
The Upload Masters API enables you to upload records from external systems to the
specific master table Compass. You can use this API to add new records on the
systems such as new product introductions. Keep your master data up to date in
Compass in order to ensure that the incentive and reward calculation is based on the
latest version of the masters
Game API endpoints:
Games are the gamified version of the incentive programs, schemes or contests.
Games contain a set of validation rules, participation list and reward rules that run on
the event and master information and in turn generate performance and incentive
payment records for the participants.
Get Game List API
This provides a list of games on the user account. USe this aPI to get reference to a
specii game that you want to work with
Get Game Details API
Use the API along with a game reference generated from the list API to get all details of
Get Game Report API
Use this API to access the overall progress performance of the Game. you can also call
in performance of a specific user by providing user refers in the request
Trigger Game Run API
It is possible to start , stop or trigger a Game run using this API.
Apart from the API endpoints given above Compass also provides API endpoints for the
● Account management
● Reward redemption and points information
The end points information for these scopes is available in detail in a separate API
reference documentation , which is available on request.