User / Account Identification

For all loyalty-related processes it is important to identify the person the system is interacting with. The central object for this identification is the account you can collect points on. This account can be linked to user-data, transactions, bookings, etc. Every account has an unique identifier, the account_id (e.g. 7d123457-bfa1-4a83-8213-123456789763), which is the technical ID all those connections are made with.

Additionally, every account can have multiple identifiers (i.e. card-codes, external identification-codes, etc.), which allow to make a connection to an account without the need to extract the account-id. We will explore both identifier-related API-calls and account-id-related API-calls in this chapter and analogously in the chapters about earn- and burn-transactions.

Card identification

All connections of transactions, bookings, etc. to accounts can be performed using the account_id (or alternatively the identifier codes). Thus, there has to be a mechanism to identify the account you want to connect to.

This is usually done, by scanning / typing / etc. the predefined identifier code (card number) of the customer. This card code can then be used in the API analogously to the account-id (see in the respective chapters for examples).

Note, that for this process, it is not necessary to get any user-information. It is possible to perform the whole purchase and payment process without requesting additional user-information (like name, birthdate, optins, etc.) as only the account-identification (account_id or identifier-code) is important for the relevant API processes. If there is no need to view user-data on the cash register, you can simplify and speed up the whole process by skipping it altogether.

User Search

If a registered customer forgot to bring his card, there is the option to search for him via search-API. This API is performing an elastic search over various domain objects (including accounts) and responds an array with results. You can perform an elastic search in the following way

curl --location --request POST '{{api_url}}/search' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--data-raw '{{body}}'

The body with search parameters looks like this:

{
  "searchTerm": "Example",
  "type": "ACCOUNT"
}

with

In general, this API may search over various domains, giving results like this

{
    "searchTerm": "Example",
    "nrOfResults": 3,
    "results": {
        "COUPON": [
            {
                "preview": "Title: Title of Coupon,Type: REWARD",
                "refId": "a1e52b7a-5cd4-4580-a0f7-7f602b27ba6e",
                "type": "COUPON"
            },
            {
                "preview": "Title: Title of Coupon,Type: DISCOUNT",
                "refId": "abad53e5-bd86-48df-858c-1bcce3af41fb",
                "type": "COUPON"
            }
        ],
        "ACCOUNT": [
            {
                "preview": "name: Name of Person,email: E-Mail of Person",
                "refId": "2f081e91-1346-4ef6-82b2-fcdecd3c190b",
                "type": "ACCOUNT"
            }
        ]
    }
}

Important Note about Filtering to Domains:

Usually, the ACCOUNT domain search is the weapon of choice here (as we are normally not interested in information about backend settings about e.g. Coupons here). Applying the filtering on ACCOUNT responds the following result (same setup as before, but filtered):

{
"searchTerm": "Example",
"nrOfResults": 1,
"results": {
	"ACCOUNT": 
  [
		{
			"preview": "name: Name of Person,email: E-Mail of Person",
			"refId": "2f081e91-1346-4ef6-82b2-fcdecd3c190b",
			"type": "ACCOUNT"
		}
	]
}
}

After identifying the user, the refId of the correct ACCOUNT-result can be used as accountId for all further processes.

Getting Account Details

If you are interested in more detail about the person standing at the POS, you can use an identifier code or accountid to get more information about the account like its bookings, transactions, current balance, membership information or user-data. All those options are explained in Swagger Documentation (spec: account). We will focus here on personal user-data.

Note, that due to structure of the platform, there are essentially three objects which contain information about the user, his account and membership.

• account:
  • This is the central element of the loyalty system.
  • Every account has its unique accountId. All relevant loyalty-processes can be linked to this id.
  • N identifiers of different id-type may serve as additional external identifiers for an account. Usually, these identifiers are Cardcodes or external numbers (like a online-shop-id).
  • Accounts can be anonymous, if they don’t have user-information connected (see membership).
• user:
  • This is the object which contains personal user-data like name, address, etc.
  • User data may be created independently from an account. Without the connection to an account (see membership) however, there is no way to interact with this data in a loyalty context (e.g. you cannot earn points on a user, only on an account.
• membership:
  • This object connects an account to a user object.
  • The creation of a membership is typically the result of a completed registration.
  • Optins for the program are related to this object.
    Depending on the set of information you are interested in, you may need to get all of them. We will explain a straight-forward way to do this in the following.
    

Getting basic Account Information

As stated out before, the account is the center of the whole loyalty system. The accountId can be used as common connection id for practically all loyalty connections.

You can get the basic account information with the following request:

curl --location --request GET '{{api_url}}/accounts/{{accountId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--header 'id-type: {{idType}}' \

with variables

Note, that it’s possible to get the account-object using the identifier code (e.g. {{idType}}=CARDCODE, {{accountId}}=V1W2X3Y4Z5) or the accountId itself (e.g. {{idType}}=ID, {{accountId}}=7d123457-bfa1-4a83-8213-123456789763). Thus, the request may also be used to extract an accountId from a given Identifier.

The account-object per se is rather slender, only containing an id (accountId), a program reference and a status of the account.

{ "id": "550e8400-e29b-11d4-a716-446655440000", "program": "Pgr-A", "status": "ACTIVE" }

If your program allows deactivation or locking of accounts, you should make sure, that accounts that don’t have the status ACTIVE cannot proceed with the following earn- and burn-processes. Deleted Accounts will not be responded at all.

Getting Membership Details

If you are interested in optins and / or user data of a given account, you need to check if the account has an active membership by requesting

curl --location --request GET '{{api_url}}/accounts/{{accountId}}/memberships' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--header 'id-type: {{idType}}' \
with variables

Note again, that you can use the identifier code directly (e.g. idType =CARDCODE, accountId=V1W2X3Y4Z5) at this point.

The returned object looks like this:

[ \{ "accountId": "550e8400-e29b-11d4-a716-446655440000", "memberRole": "OWNER", "membershipId": "550e8400-e29b-11d4-a716-446655440000", "optins": [ \{ "flag": true, "type": "email" } ], "partnerId": "550e8400-e29b-11d4-a716-446655440000", "userId": "550e8400-e29b-11d4-a716-446655440000" } ]

where

If no membership is returned, the returned array is empty []. Depending on the specific program setup, these users may not be allowed to earn and/or burn their points if there are not registered. This logic has to be adopted here if that’s the case.

Getting User Details

Given the userId of the membership, user data can be received by requesting:

curl --location --request GET '\{\{api_url}}/users/\{\{userId}}' \ --header 'Authorization: \{\{jwt_token}}' \ --header 'interaction-id: \{\{interactionId}}' \ --header 'Content-Type: application/json' \

with

An exemplary response looks like this

{ 
  "birthDate": "1965-03-05", 
  "city": "München", 
  "countryCode": "DE", 
  "customProperties": [ 
    { 
      "name": "string", 
      "value": "string" 
    } 
  ], 
  "emailAddress": "[email protected]", 
  "familyName": "Mustermann", 
  "genderCode": "MALE", 
  "givenName": "Max", 
  "phone": 654324563, 
  "streetHouseNo": "Bahnhofstraße 1", 
  "userId": "550e8400-e29b-11d4-a716-446655440000", 
  "zipCode": 80469 
} 

Note, that the content of this response may differ with the program. There may be multiple customProperties, which are completely program-specific. Furthermore, it is possible that in future versions, the response will be expanded by more fields, so you should make sure to be able to accept more output.