Endpoint Reference

 

API Rate Limits

Check your plan details for the specific rate limit. Rate limits are applied globally for an account and linked to the API keys provided for each application in the Appreciation Engine Dashboard. An application may have multiple partner keys, and each key contributes to the overall API rate.

eg. Developer A and Developer B in two different locations make calls using the same application API keys. The requests will both contribute to API use under the application limits.

eg. Developer A and Developer B in two different locations make calls using different partner keys for the application. The requests will both contribute to API use under the application limits.

Rate Limits can be enforced as soft or hard caps.

Soft caps do allow burst traffic that may exceed the allocated rate limit but will impact overall service performance if these limits are exceeded often. Hard caps will stop API traffic once the allocated limit is exceeded but ensure more stable overall performance. Soft caps are only available to Enterprise customers.

API Usage Tips

The tips below are there to help you optimize code and reduce the possibility of exceeding account limits for API usage:

  • Do not make burst of calls, spread out the calls throughout the day.
  • Do smart fetching of data (important data, non duplicated data, etc).
  • Specify upper and lower ranges on the values you are querying against. (eg. lastUpdated or id values)
  • Avoid large offsets when paging, especially when retrieving large data sets
  • Adjust ranges to keep offset reasonable.
  • Rather than paging to 10K+ pages based on a starting date, adjust the start date forward in time as you make additional calls.
  • Most endpoints enforce a maximum offset value of 100K
  • Default date range if none specified is 1 week. The maximum date range - even if a bigger range is specified - is 6 months.
  • Use the 'fields' parameter to limit fields returns for each member, and thus the size of data returned.
  • Some endpoints provide a 'paging' attribute in their response, using these is far more efficient than using offset and limit.
  • Datetimes returned in API calls are in UTC
  • Maximum age of available data is determined by the license Data Retention Policy. Maximum default for activity data is 3 years. Maximum default for visitor data is 2 years.

Caching

Store API responses in your application or on your site if you expect a lot of use. For example, don’t try to call the API on every page load of your website landing page. Instead, call the API at regular intervals and load the response into a local cache. When users hit your website load the cached version of the results.

Prioritize active users

If your site keeps track of many users (for example, fetching their current status or statistics), consider only requesting data for users who have recently signed into your site.

Error Handling

If there is an error in the API request made then an error response code is returned. Developers should try to check and catch any non-expected responses and handle appropriately.

Error Response Structure:

{
	"error": {
		"code": 48,
		"message": "invalid member"
	}
}

NOTE: In some cases, the API server may be unavailable and unable to handle a response. In these cases you may receive HTML pages for 502, 504 or 500 pages. Therefore developers should also check for valid JSON responses.

© Copyright Appreciation Engine Inc 2021, all rights reserved. See our Terms & Conditions, Privacy Policy, Cookie Policy and Privacy Promise.

We are grateful to the lək̓ʷəŋən People of the Esquimalt and Songhees Nations on whose traditional territories Appreciation Engine is based. We also wish to give thanks to the W̱SÁNEĆ, Hul’q’umi’num’, and Snuneymuwx Peoples of the Coast Salish First Nations, and the Ngāti Toa, Muaūpoko, and Ngāti Raukawa ki te Tonga of the Māori iwi, on whose traditional territories the team members of AE work and live.