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.

A typical pagination query#

?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

A typical paginated reward API response#

{
  {
  "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:

action
date

Rewards

Rewards can be filtered by the following fields:

type
points
stores (list)
starts_at
ends_at
status - It possible to filter based upon active, completed and scheduled

Challenges

Challenges can also be filtered by the following fields:

ends_at
points
tags
title

Custom attributes#

Entities can be be filtered by custom attributes. These attributes must be configured using the custom entities module in the Antavo, located Modules ‣ Custom entities. 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

Available operators#
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.

Available operators#
Operator	Options
sort	starts_at, ends_at, name, points
order	asc (default), desc

https://api.environment.antavo.com/customers/ob1/events?order=asc