Fan API (Preview)

Public API for backend and client access to Fan Data within Monterosa / Interaction Cloud

Fan API is the interface to fan data in the Monterosa platform. It acts as a layer above internal services that provide profiles, gamification and rewards amongst other functions. An authenticated backend can make a call on behalf of any user permitted within scope. For example within a rewards context you may need a video platform triggering a video view, or an ecommerce platform to log a physical purchase that increments a Rewards metric.

A public client making a direct request can only make a call to its own user ID, for example requesting its user profile data to render in an app. It is intended that the Monterosa SDK will adopt support for this method for additional convenience and abstraction.

This is an early stage API that is being developed rapidly to encompass more services over time, enabling a single touchpoint. For example, the full internal Audience Profile and other audience data.

This API is for preview and cannot yet be used in production.

Authentication

OAuth token endpoint

This endpoint allows the client to exchange authorization code or crenentials for a Monterosa Access Token that is required to access protected endpoints of the Fan API

POSThttps://api-dev.monterosa.cloud/spaces/{spaceId}/auth/token

Path parameters

spaceId*string (uuid)

ID of the space

Body

one of

Response

Body

access_token*string (jwt)

token_type*enum

Bearer

expires_in*integer

Request

const response = await fetch('https://api-dev.monterosa.cloud/spaces/{spaceId}/auth/token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: JSON.stringify({
      "grant_type": "client_credentials",
      "client_id": "text",
      "client_secret": "text"
    }),
});
const data = await response.json();

Response

{
  "access_token": "text",
  "token_type": "Bearer"
}

Profile

Get user's profile

Get profile of the user. If the profile doesn't exist, it will be created.

GEThttps://api-dev.monterosa.cloud/spaces/{spaceId}/profile

Authorization

Path parameters

spaceId*string (uuid)

ID of the space

Response

User was found, data property of the response object contains user data

Body

messageenum

dataUserProfile (object)

Request

const response = await fetch('https://api-dev.monterosa.cloud/spaces/{spaceId}/profile', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "message": "OK",
  "data": {
    "name": {
      "display": "text",
      "isAutogenerated": false
    },
    "avatar": {
      "media": {
        "s": "text",
        "m": "text",
        "l": "text"
      }
    },
    "data": {
      "<prop_string>": "arbitrary string up to 1024 characters long",
      "<prop_number>": 1000,
      "<prop_boolean>": true
    }
  }
}

Update user's profile

Update profile of the user. If the profile doesn't exist, it will be created.

PUThttps://api-dev.monterosa.cloud/spaces/{spaceId}/profile

Authorization

Path parameters

spaceId*string (uuid)

ID of the space

Body

metricsobject

avatarobject

propsArbitraryDataObject (object)

Response

User was found and updated

Body

messageenum

Request

const response = await fetch('https://api-dev.monterosa.cloud/spaces/{spaceId}/profile', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "message": "OK"
}

Rewards

Get rewards configuration

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

GEThttps://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/config

Path parameters

spaceId*string (uuid)

ID of the space

Response

Successful response

Body

messageenum

dataobject

Request

const response = await fetch('https://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/config', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "message": "OK",
  "data": {
    "metrics": [
      {
        "id": "text",
        "title": "text",
        "media": "text"
      }
    ],
    "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": false,
        "showInRail": false,
        "time": {
          "showInUI": false
        },
        "missions": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "title": "text",
            "type": "text",
            "notification": {
              "display": "none",
              "title": "text",
              "message": "text"
            }
          }
        ],
        "rewards": [
          {
            "type": "metric",
            "metricId": "text",
            "inventorySetId": "text",
            "inventoryItemId": "text"
          }
        ]
      }
    ]
  }
}

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.

GEThttps://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/profile

Authorization

Path parameters

spaceId*string (uuid)

ID of the space

Response

Rewards profile found

Body

messageenum

dataUserRewardsProfile (object)

Request

const response = await fetch('https://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/profile', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

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

Get notifications

Returns an array of unread notifications for the autheticated user

GEThttps://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/notifications

Authorization

Path parameters

spaceId*string (uuid)

ID of the space

Response

Successful response, data object contains an array of notifications

Body

messageenum

dataarray of object

Request

const response = await fetch('https://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/notifications', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "message": "OK",
  "data": [
    {
      "id": "text",
      "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

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

GEThttps://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/history

Authorization

Path parameters

spaceId*string (uuid)

ID of the space

Query parameters

Response

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

Body

messageenum

dataarray of object

Request

const response = await fetch('https://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/history', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "message": "OK",
  "data": [
    {
      "id": "text",
      "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>"
          }
        }
      }
    }
  ]
}

Report an action

Use this method to report a rewardable action

POSThttps://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/action

Authorization

Path parameters

spaceId*string (uuid)

ID of the space

Body

actionstring

dataArbitraryDataObject (object)

Response

Successful response

Request

const response = await fetch('https://api-dev.monterosa.cloud/spaces/{spaceId}/rewards/action', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

PreviousGeo-Verify NextContent Creation