DocsCreator GuideIntegration Guide

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

get

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

Responses
200
Successful response
application/json
get
GET /api/loyalty/config HTTP/1.1
Host: your.space.domain
Accept: */*

{
  "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"
          }
        ]
      }
    ]
  }
}

Get user's rewards profile

get

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

Authorizations
Responses
200
Rewards profile found
application/json
get
GET /api/loyalty/profile HTTP/1.1
Host: your.space.domain
Authorization: Bearer JWT
Accept: */*

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

Get notifications

get

Returns an array of unread notifications for the autheticated user

Authorizations
Responses
200
Successful response, `data` object contains an array of notifications
application/json
get
GET /api/loyalty/notifications HTTP/1.1
Host: your.space.domain
Authorization: Bearer JWT
Accept: */*

{
  "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>"
          }
        }
      }
    }
  ]
}

Get transaction history

get

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

Authorizations
Query parameters
frominteger · timestampOptional
tointeger · timestampOptional
Responses
200
Successful response, `data` object contains an array of transactions arranged by timestamp ascending. Array may be empty.
application/json
get
GET /api/loyalty/history HTTP/1.1
Host: your.space.domain
Authorization: Bearer JWT
Accept: */*

{
  "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>"
          }
        }
      }
    }
  ]
}

Get coupon data by id

get
Authorizations
Path parameters
couponIdstringRequired

ID of the coupon

Responses
200
Successful response
application/json
get
GET /api/loyalty/coupons/{couponId} HTTP/1.1
Host: your.space.domain
Authorization: Bearer JWT
Accept: */*

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

Report an action

post

Use this method to report a rewardable action

Authorizations
Body
actionstringOptionalExample: <action_name>
Responses
200
Successful response
post
POST /api/loyalty/action HTTP/1.1
Host: your.space.domain
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "action": "<action_name>",
  "data": {
    "<prop_string>": "arbitrary string up to 1024 characters long",
    "<prop_number>": 1000,
    "<prop_boolean>": true
  }
}
No content

Last updated

Was this helpful?