Pagination, Filtering & Ordering#
Antavo can hold, process and return large volumes of customer-related loyalty information. Antavo provides the following methods in order to ensure high-quality API performance.
Pagination#
Large data requests can be broken up into smaller pages. Pagination-enabled endpoints have two new parameters:
- limit:
The number of entries which will be returned in one response e.g., limit = 100
- offset:
This number sets the starting position for entries to be returned in one response
Therefore the following query will results in a response having a limit of 20 entries but query will start with number 20. This effectively returns entries numbered 20 – 40.
?offset=20&limit=20
A typical response for a reward query contains:
- next:
The automatically generated link for accessing the next series of entries
- prev:
The automatically generated link for accessing the previous series of entries
- data:
All data for the specified pagination range
{
{
"next": "\/customers\/test02\/activities\/rewards?offset=1&limit=1",
"data": [
{
"type": "coupon",
"_actions": {
"complete": {
"method": "POST",
"url": "\/customers\/test02\/activities\/rewards\/5e78c52e5553aa0e00000008\/claim"
}
},
"id": "5e78c52e5553aa0e00000008",
"status": "active",
"title": "Test2",
"description": "abcdefgh",
"image": {
"small": "https:\/\/antavo.s3.eu-west-1.amazonaws.com\/brands\/30202\/media\/1615282657-3qGdB.png",
"medium": "https:\/\/antavo.s3.eu-west-1.amazonaws.com\/brands\/30202\/media\/1615282657-HVHC1.png",
"large": "https:\/\/antavo.s3.eu-west-1.amazonaws.com\/brands\/30202\/media\/1615282654-CMLJa.png"
},
"points": 1
}
]
}
Current endpoints which support pagination:
Filtering#
Generic filtering, using queries, is being rolled out throughout for all applicable APIs. Invalid data entry e.g., ?date=kitty will not result in an error, only an empty query. Datetime fields should be in a machine-readable format according to an ISO standard. Invalid field values will result in a 400 error, a Bad Request.
Built-in attributes#
Events
Event-based endpoints, where enabled, can use the following fields:
actiondate
Rewards
Rewards can be filtered by the following fields:
typepointsstores(list)starts_atends_atstatus- It possible to filter based uponactive,completedandscheduled
Challenges
Challenges can also be filtered by the following fields:
ends_atpointstagstitle
Custom attributes#
Entities can be be filtered by custom attributes. These attributes must be configured using the custom entities module in the Antavo, located . Here, existing factory entities can be extended or new entities created. The correspond list of attributes can be found by editing the target entity or following the following example link, with appropriate substitutions.
https://loyalty.environment.antavo.com/brand_id/extensions/custom-entities/entity%2Fentity/attributes
Filtering by an attribute can be added to a selected fields by adding the filterable and api tag in the tag section
The field can be used for filtering by adding the following query
entity_attribute=query_value
Example
A system has a reward entity configured with the priority attribute above and there is only w
https://api.rc.antavo.com/customers/001/activities/rewards?cf_priority=false
returns
{
"data": [
{
"type": "download",
"_actions": {
"complete": {
"method": "POST",
"url": "\/customers\/001\/activities\/rewards\/637794598bacbc280e4952e4\/claim"
}
},
"id": "637794598bacbc280e4952e4",
"status": "active",
"title": "Low priority reward",
"description": "a generic reward",
"image": {
"small": "https:\/\/antavo.s3.eu-west-1.amazonaws.com\/brands\/1567\/media\/1668780684-Gboja.png",
"medium": "https:\/\/antavo.s3.eu-west-1.amazonaws.com\/brands\/1567\/media\/1668780683-TjuvC.png",
"large": "https:\/\/antavo.s3.eu-west-1.amazonaws.com\/brands\/1567\/media\/1668780683-ASyuP.png"
},
"points": 0,
"cf_priority": false
}
],
"time": 0.105
}
https://api.rc.antavo.com/customers/001/activities/rewards?cf_priority=true
returns
{
"data": [
{
"type": "custom",
"_actions": {
"complete": {
"method": "POST",
"url": "\/customers\/001\/activities\/rewards\/62ed16209bc94910047efa9f\/claim"
}
},
"transferable": true,
"transfer_limit": 1,
"transfer_points": 0,
"id": "62ed16209bc94910047efa9f",
"status": "active",
"title": "Test - Custom Reward",
"description": "A nice custom reward",
"image": {
"small": "https:\/\/antavo.s3.eu-west-1.amazonaws.com\/brands\/1567\/media\/1659704864-ubDGg.jpeg",
"medium": "https:\/\/antavo.s3.eu-west-1.amazonaws.com\/brands\/1567\/media\/1659704863-J3kCr.jpeg",
"large": "https:\/\/antavo.s3.eu-west-1.amazonaws.com\/brands\/1567\/media\/1659704863-mKYSB.jpeg"
},
"points": 0,
"cf_priority": true
}
],
"time": 0.09
}
Query operators#
Filtering can be extended by adding query parameters in the following format.
fieldname.operator=value
Operator |
Explanation |
|---|---|
eq |
equals (default operator) |
ne |
not equals |
lt |
less than |
lte |
less than or equal |
gt |
greater than |
gte |
greater than or equal |
in |
in – accepts a comma separated list of values |
nin |
not in – accepts a comma separated list of values |
eq is the default operator and will be used if an operator is omitted.
If there is a collision between applicable field and a special query param, explicitly writing the eq operator will resolve the conflict.
e.g., limit, which is used for pagination should become limit.eq .
Filters can be combined achieve ranges, e.g.: ?price.gte=10&price.lte=20
Warning
Filtering should be used with great care and caution! A fields being marked filterable does not mean that that the field has been optimized for filtering. Every filtered operation should be thoroughly tested.
Ordering#
API responses can be ordered. The available ordering options may vary between endpoints.
Operator |
Options |
|---|---|
sort |
starts_at, ends_at, name, points |
order |
asc (default), desc |
https://api.environment.antavo.com/customers/ob1/events?order=asc