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.

  1. Log in to your Award Force account
  2. Go to “Settings > General > Integration”
  3. Note your “Account ID” (required for validating your access tokens)
  4. Next to the “API key” field, click “Generate key“
  5. 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:

  • email
  • 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]