Award Force developer API
Integrate your awards website and business applications with Award Force.
Endpoints and methods available for 3rd party developers to work with are documented on this page.
The Award Force API uses OAuth 2 authentication, and returns JSON formatted responses by default. Let us know if you need XML formatted responses as they can be made available.
Authentication
Integrating with the API requires that you have an API key that can then be used to authenticate your requests.
1. Setting up your API key
These steps needs to be done by a user with “Awards manager” account privileges.
- Log in to your Award Force account
- Go to “Settings > General > Integration”
- Note your “Account ID” (required for validating your access tokens)
- Next to the “API key” field, click “Generate key“
- You will see the API key field populated with your new key. Copy this key and keep it somewhere safe. You will not be able to see it again (however, you can generate a new key at any time – the old key will stop working)
2. Requesting an access token
All API requests are made against:
https://api.awardsplatform.com
Before you can request any data from the API, you must first request an access token.
Make a GET request to https://api.awardsplatform.com/access-token/ with the following headers:
Accept: application/vnd.Award Force.v1.0+json Authorization: Basic YOURAPIKEY
If successful, you should see the following response data in your code:
ACCESSTOKEN
This is a simple string that is needed for the next step and will look something like: 35128adf640ef2eb0a3d9e27594a0b08
Now we can start making requests to various API endpoints. In order to do that, the API URLs will change, but the following headers will be required on every request that you make:
Accept: application/vnd.Award Force.v1.0+json Authorization: Basic YOURACCESSTOKEN X-Account-Id: YOURACCOUNTID
Remember that the access token is the string that was returned when you first authenticated and the account ID was the value under “Settings > General > Integration”.
Endpoints
Categories
For a list of categories, make a GET request to:
https://api.awardsplatform.com/category/
Supported parameters:
- per_page: Set the total number of records returned. Maximum 100.
- page: Which page to start results from. Default 1.
Entries
For a list of entries, make a GET request to:
https://api.awardsplatform.com/entry/
By default, this will return a list of 10 entries that you can then work with in your code.
Supported parameters:
- per_page: Set the total number of records returned. Maximum 100.
- page: Which page to start results from. Default 1.
- category: Query for a specific entry category by providing the category ID (more on categories later)
So to request page 3 of a list with 20 records per page, your request would be:
https://api.awardsplatform.com/entry/?page=3&per_page=20
Entry
To retrieve the full content of an entry, make a GET request to:
https://api.awardsplatform.com/entry/[SLUG]
The slug for an entry is an 8 character alphanumeric string uniquely identifying the entry and is one of the values returned in a request for a list of entries.
Orders
For a list of orders, make a GET request to:
https://api.awardsplatform.com/order/
By default, this will return a list of 10 orders that you can then work with in your code.
Supported parameters:
- per_page: set the total number of orders returned. Maximum 100.
- page: which page to start results from. Default 1.
- season: season slug to filter by.
If you know the slug or local ID of an order, you can get that order’s full details by making a GET request to:
https://api.awardsplatform.com/order/[SLUG|ID]
Order items
For a list of order items, make a GET request to:
https://api.awardsplatform.com/order-item/
By default, this will return a list of 10 order items that you can then work with in your code.
Supported parameters:
- per_page: set the total number of orders returned. Maximum 100.
- page: which page to start results from. Default 1.
If you know the slug or local ID of an order, you can get items for that order by making a GET request to:
https://api.awardsplatform.com/order-item/[SLUG|ID]
Users
To create a new user, make a POST request to:
https://api.awardsplatform.com/user/
This will return the slug that uniquely identifies the user in Award Force.
Required parameters:
- firstName
- lastName
If a user with the given email already exists, this action will not create a new record but will simply return the slug of the existing user.
User auth token
To request an authorisation token on behalf of a registered user (which can be used once to log that user in), make a GET request to:
https://api.awardsplatform.com/user/[SLUG]/auth-token
This will return an alphanumeric token that can be used by redirecting the user to:
https://[ACCOUNT_DOMAIN]/login?token=[TOKEN]