The points API

All points changes over the API are now done through the v2/point-accounts endpoints. These endpoints can be used to see point definitions, access active and pending points, get the points awarded by individual transactions as well as add point-generating transactions from other systems outside of Engage.

Some terms and parameters are useful to know before going into detail:

Point definitions: The "type" of points. Currently one point definition exists but the system allows for different kinds of points to be tracked in parallel, each with their own point definition value. Parameter is definitionId.

Point accounts: Points of different types are separated by their point definition value. This allows contacts to have many independent point totals and histories (accounts) each uniquely defined by a contact ID plus a definition ID. Parameter is accountId.

Point transactions: A transaction or update to a transaction containing a change to a contact's points.

Active points: The points a contact currently "has" that can be used to create vouchers.

Pending points: Points with a validFrom date in the future, that will not become active until then.

The offset and count parameters: Optional parameters that can be used to pagination the results.

The filter parameter: Can be "All", "Active", "Pending" or left blank. Used to return just active points, pending points or both.

To get all of a contact's point accounts, use this endpoint:

GET api/v2/point-accounts

The contactId is sent as a parameter in the query string. This returns all point accounts like this:

{
  "links": [],
  "count": 2,
  "offset": 0,
  "items": [
    {
      "balance": 110,
      "balanceExpires": "2023-08-14T13:03:52.0510384+02:00",
      "contactId": "efaaefb8-e07a-46d5-89fa-1423e87b0798123111",
      "definitionId": 1,
      "id": 9,
      "pendingPoints": 0,
      "links": [
        {
          "id": 1,
          "href": "https://yoururl/api/v2/point-accounts/definitions/1",
          "method": "GET",
          "rel": "definition"
        },
        {
          "href": "https://yoururl/api/v2/point-accounts/transactions?accountId=9",
          "method": "GET",
          "rel": "transactions"
        }
      ]
    },
    {
      "balance": 110,
      "balanceExpires": "2023-08-14T13:03:52.0510384+02:00",
      "contactId": "efaaefb8-e07a-46d5-89fa-1423e87b0798123111",
      "definitionId": 2,
      "id": 9,
      "pendingPoints": 0,
      "links": [
        {
          "id": 1,
          "href": "https://yoururl/api/v2/point-accounts/definitions/1",
          "method": "GET",
          "rel": "definition"
        },
        {
          "href": "https://yoururl/api/v2/point-accounts/transactions?accountId=9",
          "method": "GET",
          "rel": "transactions"
        }
      ]
    }
  ],
  "totalCount": 2
}

If you know the unique ID of the point account, you can get the information directly by using the ID in the path. For example:

GET api/v2/point-accounts/fa1de1de-427d-4a63-8f43-513fc8b5e97b

This returns the following:

{
  "balance": 110,
  "balanceExpires": "2023-08-14T13:03:51.9719335+02:00",
  "contactId": "af687249-b52a-4926-8591-ccf881b59e9e",
  "definitionId": 1,
  "id": 1234567899,
  "pendingPoints": 0,
  "links": [
    {
      "id": 1,
      "href": "https://yoururl/api/v2/point-accounts/definitions/1",
      "method": "GET",
      "rel": "definition"
    },
    {
      "href": "https://yoururl/api/v2/point-accounts/transactions?accountId=9",
      "method": "GET",
      "rel": "transactions"
    }
  ]
}

The links section contains optional information with some useful API calls you can use.

To get all the available point definitions:

GET api/v2/point-accounts/definitions

The response will look like this:

[
  {
    "description": "Some description",
    "id": 1,
    "name": "Default",
    "links": []
  }
]

The optional parameters offset and count can again be used to paginate the results.

You can also get one specific point definition if you already know its ID, like this:

GET api/v2/point-accounts/definitions/1

  {
    "description": "Some description",
    "id": 1,
    "name": "Default",
    "links": []
  }

The transaction endpoint is used for fetching (and posting) the individual transactions that have generated points, along with the points generated and other transaction information.

[
  {
    "contactId": "111111fa6-103b-459b-8d01-b6c000e8e26a",
    "amount": 12,
    "definitionId": 1,
    "timeStamp": "2023-06-01T08:40:51.658Z",
    "source": "Purchase",
    "description": "Gilded gauntlets",
    "validFrom": "2023-06-16T08:40:51.658Z",
    "validTo": "2024-06-16T08:40:51.658Z"
  }
]

{
  "accountId": 1,
  "amount": 800,
  "createdOn": "2022-11-16T13:17:54+00:00",
  "description": "Some text",
  "id": 1,
  "modifiedOn": "2022-12-16T00:05:21+00:00",
  "source": "Adjustment",
  "transactionDate": "2022-11-16T14:17:54+01:00",
  "type": "Adjustment",
  "validFrom": "2016-11-16T14:17:54+01:00",
  "validTo": "2017-11-16T23:59:59+01:00",
  "retailTransactionLineItemId": "d5ad8be8-6785-4922-95fe-b12500d3ff91"
  "links": [
    ...
  ]
}

One example of using the new points API is the case when Engage is acting as the point follower. There is a separate article that goes into detail about how point follower works.