Loyalty API

Loyalty API allows for building advanced gamification strategies that reward sustained engagement, thus driving retention and boosting app usage.

Loyalty API (part of the Audience API) is a high-throughput public RESTful API designed to support advanced gamification strategies. It helps track and reward specific audience behaviours aligned with key performance indicators tailored to your business needs.

Get loyalty configuration

Returns list of rewards, challenges and missions available to the authenticated user

get

/api/loyalty/config

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/loyalty/config'

200

404

200

{
  "message": "OK",
  "data": {
    "metrics": [
      {
        "id": "text",
        "title": "text",
        "media": "text",
        "defaultValue": 1,
        "minimumValue": 1,
        "maximumValue": 1
      }
    ],
    "inventory": [
      {
        "id": "text",
        "title": "text",
        "items": [
          {
            "id": "text",
            "title": "text",
            "media": "text"
          }
        ]
      }
    ],
    "challenges": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "title": "text",
        "subtitle": "text",
        "notification": {
          "display": "none",
          "title": "text",
          "message": "text"
        },
        "showInProfile": true,
        "showInRail": true,
        "time": {
          "showInUI": true,
          "from": 1,
          "to": 1
        },
        "missions": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "title": "text",
            "type": "text",
            "notification": {
              "display": "none",
              "title": "text",
              "message": "text"
            }
          }
        ],
        "rewards": [
          {
            "type": "metric",
            "metricId": "text",
            "metricQuantity": 1,
            "inventorySetId": "text",
            "inventoryItemId": "text"
          }
        ]
      }
    ]
  }
}

Successful response

Get user's rewards profile

Get user's metrics and inventory, as well as completed missions and challenges. If the profile doesn't exist, empty one will be created.

get

/api/loyalty/profile

Authorizations

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/loyalty/profile' \
  --header 'Authorization: Bearer JWT'

200

201

401

404

200

{
  "message": "OK",
  "data": {
    "metrics": {
      "<metric_id>": 100
    },
    "inventory": {
      "<inventory_set_id>": [
        "<inventory_item_id>"
      ]
    },
    "challenges": {
      "<challenge_id>": {
        "isCompleted": false,
        "missionsCompleted": [
          "<mission_id>"
        ]
      }
    }
  }
}

Rewards profile found

Get notifications

Returns an array of unread notifications for the autheticated user

get

/api/loyalty/notifications

Authorizations

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/loyalty/notifications' \
  --header 'Authorization: Bearer JWT'

200

401

404

200

{
  "message": "OK",
  "data": [
    {
      "id": "text",
      "timestamp": 1,
      "type": "challengeCompleted",
      "display": "toast",
      "title": "text",
      "message": "text",
      "payload": {
        "challengeId": "123e4567-e89b-12d3-a456-426614174000",
        "missionId": "123e4567-e89b-12d3-a456-426614174000",
        "metricChanges": {
          "<metric_id>": {
            "oldValue": 100,
            "newValue": 200
          }
        },
        "inventoryChanges": {
          "received": [
            {
              "setId": "<inventory_set_id",
              "itemId": "<inventory_item_id>"
            }
          ],
          "lost": [
            {
              "setId": "<inventory_set_id",
              "itemId": "<inventory_item_id>"
            }
          ]
        },
        "milestoneChanges": {
          "<milestone_set_id>": {
            "oldValue": "<milestone_id>",
            "newValue": "<milestone_id>"
          }
        }
      }
    }
  ]
}

Successful response, data object contains an array of notifications

Get transaction history

Returns paginated transaction history of all achievements (challenges and missions) and rewards (metrics and inventory) for the authenticated user

get

/api/loyalty/history

Authorizations

Query parameters

frominteger · timestamp

tointeger · timestamp

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/loyalty/history' \
  --header 'Authorization: Bearer JWT'

200

401

404

200

{
  "message": "OK",
  "data": [
    {
      "id": "text",
      "timestamp": 1,
      "type": "challengeCompleted",
      "payload": {
        "challengeId": "123e4567-e89b-12d3-a456-426614174000",
        "missionId": "123e4567-e89b-12d3-a456-426614174000",
        "metricChanges": {
          "<metric_id>": {
            "oldValue": 100,
            "newValue": 200
          }
        },
        "inventoryChanges": {
          "received": [
            {
              "setId": "<inventory_set_id",
              "itemId": "<inventory_item_id>"
            }
          ],
          "lost": [
            {
              "setId": "<inventory_set_id",
              "itemId": "<inventory_item_id>"
            }
          ]
        },
        "milestoneChanges": {
          "<milestone_set_id>": {
            "oldValue": "<milestone_id>",
            "newValue": "<milestone_id>"
          }
        }
      }
    }
  ]
}

Successful response, data object contains an array of transactions arranged by timestamp ascending. Array may be empty.

Get coupon data by id

get

/api/loyalty/coupons/{couponId}

Authorizations

Path parameters

couponIdstringrequired

ID of the coupon

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/loyalty/coupons/{couponId}' \
  --header 'Authorization: Bearer JWT'

200

401

404

200

{
  "message": "OK",
  "data": {
    "id": "text",
    "title": "text",
    "link": "text",
    "coupon_id": "text",
    "coupon_type": "text",
    "coupon_code": "text",
    "showOnNotification": true
  }
}

Successful response

Report an action

Use this method to report a rewardable action

post

/api/loyalty/action

Authorizations

Body

actionstring

Example: <action_name>

dataobject

Example: {"<prop_string>":"arbitrary string up to 1024 characters long","<prop_number>":1000,"<prop_boolean>":true}

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://your.space.domain/api/loyalty/action' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "<action_name>",
    "data": {
      "<prop_string>": "arbitrary string up to 1024 characters long",
      "<prop_number>": 1000,
      "<prop_boolean>": true
    }
  }'

200

401

404

200

No body

Successful response