Start Session for User Account

POST 
/client/users/:identifier/sessions

Request

This request is used to begin a session with a customer account. A session is required for any API interaction outside of enrollment.

Additional Headers

X-Identifier-Type
Differentiates what type of identifier the path variable identifier is
Possible Values

• ACCOUNT_ID

• LOYALTY_ID

• EXTERNAL_ID

• EMAIL

• PARTNER_LINK_ID

• PHONE_NUMBER

• EXTERNAL_AGENT_ID

The default value for x-identifier-type (in the Headers) is ACCOUNT_ID. The default option is defined by a configuration in the configuration file (ConfigType='START_SESSION_CUX_IDENTIFIER'). 'LOYALTY_ID' and 'ACCOUNT_ID' are allowed for most clients, and those as well as 'EXTERNAL_ID' for a few clients.

Redemptions cannot be made using PHONE_NUMBER as the X-Identifier-Type, so if it is used, then attributes for redeemable balances are returned in the response as "0" values.

If EXTERNAL_AGENT_ID is used, it can be used with the externalAgentSessionId attribute in the request to provide the unique identifier.

Path Variables

Identifier
The identifier that points to the account for which the session is being opened.

Body

Attribute	Definition	Format	Notes
correlationId	Unique identifier for the session	String	Recommended format is GUID.
channel	Channel in which an offer was created	Enum, commonly-used values: "APP", "STORE", "POS", "PARTNER" or "WEBSITE"	Depending on client implementation, the default is "APP" or "STORE". Note that the client may supply their own custom value, but it cannot be null or blank.
externalAgentSessionId	Unique identifier provided by the client.	String	Optional, GUID, can be used if enabled through configuration; also used with EXTERNAL_AGENT_ID x-identifier-type.

Response

For hierarchy information, view the sample Response code.

Attribute	Definition	Format	Note
accountId	GUID uniquely identifying the account	String
loyaltyId	Loyalty Card Number for the session	String (Client specific)	If loyaltyId was not provided in the request, then this is the primary card number on the account
externalId	Primary identifier of the account holder in the client system	String	Optional, but can be configured to be a required field. Note that this identifier is not returned for accounts where the userStatus is "CLOSED", "CANCELLED", or "DECEASED".
membershipType	Type of membership	Enum: Defaults: "R" or "E"	R = Regular, E = Employee. Note that through ConfigType='MEMBERSHIP_TYPES" in the configuration file, the letters used for these defaults can be changed.
userStatus	Status of the loyalty account	Enum: "ACTIVE", "UNREGISTERED", "EXPIRED", "DECEASED", "CLOSED", or "CANCELLED"	Note that for a "ghost card" or unregistered card, the userStatus is "UNREGISTERED".
cardStatus	Status of the loyalty card	Enum: "ACTIVE", "INVALID", "SUSPENDED", "LOST_OR_STOLEN", "DAMAGED", "FRAUD_ABUSE", "CANCELLED", "EXPIRED", or "NON_LOYALTY"	Always the status of the loyaltyId passed in. Note that for a card with an "UNREGISTERED" userStatus, this value is "NON-LOYALTY".
cardType	Indicator for the type of card associated to the account	Enum: "DIGITAL" or "PHYSICAL"
isSuspended	Indicates whether the account has a status of Suspended	Boolean: true or false
isExpired	Indicates whether the account has a status of Expired	Boolean: true or false	Expiry due to long period of inactivity
isValid	Valid session	Boolean	Legacy attribute. Value is always "true"
pointsBalance	Customer's current points balance	Number
dollarBalance	Customer's current dollar balance	Number
availablePointsBalance	Customer's available points balance	Number	This is their balance less holds on their account.
availableDollarBalance	User's available dollar balance	Number	This is their balance less holds on their account.
userMinRedeemPoints	Minimum redemption (Points).	Number	The minimum number of points this user is able to redeem this session. If they are unable to redeem due to insufficient funds or other business rule violations, this value will be 0.
userMinRedeemDollars	Minimum redemption (Dollars)	Number	The minimum redemption this user is able to perform expressed this session in dollar amount. If they are unable to redeem due to insufficient funds or other business rule violations, this value will be 0.
userMaxRedeemPoints	Maximum redemption (Points). This is the number used to display the Redeemable Balance in the Console.	Number	The maximum number of points this user is able to redeem this session. If they are unable to redeem due to insufficient funds or other business rule violations, this value will be 0.
userMaxRedeemDollars	Maximum redemption (Dollars). This is the number used to display the Redeemable Value in the Console.	Number	The maximum redemption this user is able to perform expressed this session in dollar amount. If they are unable to redeem due to insufficient funds or other business rule violations, this value will be 0.
redeemablePointBalance	The balance that can currently be redeemed in points.	Number	This balance may be set to 0 if there is an outstanding fraud prevention advice on redemption for this account.
redempableDollarBalance	The balance that can be currently redeemed in dollars.	Number	This balance may be set to 0 if there is an outstanding fraud prevention advice on redemption for this account.
redemptionsToDate	Cumulative total of redemptions	Number	How many points the member has redeemed in the current YTD, including adjustments. The REDEEM_YEAR configuration must be turned on or this attribute will not appear.
sessionCorrelationId	CorrelationId for the session.	String	This will always match the correlationId passed in the request.
userProfile	Customer personal information	Object
dateOfBirth	Customer date of birth	String	"YYYY-MM-DD"
gender	Customer Personal Information	Enum: "M", "F", "Other", "PreferNotToSay"	Required attribute. M = 'MALE', F = 'FEMALE', Other = 'Other', PreferNotToSay = 'PreferNotToSay'.
firstName	Customer Personal Information	String	Optional attribute. Not returned if empty.
lastName	Customer Personal Information	String	Optional attribute. Not returned if empty.
businessName	Customer business name	String	Optional. Can be used in B2B loyalty programs
postalCode/zipCode	Postal or Zip code of customer	String	Optional. Note that in LOCALIZATION config, if addressType is set to "US" then field name will be "zipCode" and if addressType is set to "CA" then the field name will be "postalCode". Format: "H0H 0H0" / "HOHOH" / "HOHOH-HOHO".
email	Email of user	String	Required attribute. In standard email format.
partners	Map of partner names or identifiers and the account holder’s link status for each listed partner and partner card details only for Non-Financial Partners.	Object	The name or identifier is an object containing the "status" and optional "links" attribute. The attributes below down to "bin" are contained in this object.
{partnerName}	Usually an acronym for the partner name.	Object
status	Whether the partner is linked or unlinked to the member account.	Enum: "LINKED" or "UNLINKED"	Only linked status (LINKED/UNLINKED) are returned for financial partners and unlinked partners. In addition to status, the list of linkIds and associated last4 and bin are returned for linked non-financial partners (bin may not always be included).
links	If the status is "LINKED", may provide details about the link.	Array containing one or more objects, each containing the following three attributes	Returned for linked non-financial partners only.
linkId	The unique identifier of the link.	String	Optional
last4	The last four digits of the linked card or account as an identifier.	String	Optional
bin	The Bank Identification Number.	String	Optional
membershipTiers	Contains detailed information about an accounts loyalty program tier information	Object	Optional. Array of loyalty programs. See the membershipTiers attribute table below.
household	Contains information about a household or related group of members who may use combined rewards	Object	Contains the unique ID of the household, whether the current member is the "PRIMARY" member, and data about household balances and redeemable amounts
id	Unique identifier for the household of members.	String
role	The role within the household of the current member.	Enum: "PRIMARY" or "SECONDARY"
balance	Contains information about the household account balance in dollars and points.	Object	Contains attributes with data about points and dollars balances, minimum and maximum redemption
totalPointsBalance	The total number of points attributed to the household account.	Number
totalDollarBalance	The total number of dollars attributed to the household account.	Number
totalAvailablePointBalance	The total number of points currently available to the household account.	Number
totalAvailableDollarBalance	The total number of dollars currently available to the household account.	Number
totalRedeemablePointBalance	The total number of points that can currently be redeemed by this household account.	Number
totalRedeemableDollarBalance	The total number of dollars that can currently be redeemed by this household account.	Number
minRedeemPoints	The minimum number of points that can be redeemed by this household account.	Number
maxRedeemPoints	The maximum number of points that can be redeemed by this household account.	Number
minRedeemDollars	The minimum number of dollars that can be redeemed by this household account.	Number
maxRedeemDollars	The maximum number of dollars that can be redeemed by this household account.	Number

membershipTiers

For hierarchy information, view the sample Response code.

Attribute	Definition	Format	Note
{{programName}}	Name of the loyalty tier program	Object	The attribute name is assigned ID when creating the program. (eg. "GenericProgramName" would be the attribute).
programCode	Identifier of the loyalty tier program	String	Customized at time of program creation
tierCode	Tier code of the accounts current tier	String
tierName	Name or short description of the tier.	String
tierRank	Numerical representation of the current tier rank	Number	Tier numbering starts at 0
tierContext	Identifies whether tier data applies to individual tier or household tier.	Enum: "INDIVIDUAL" or "HOUSEHOLD"	Only used when Household tier is enabled
nextPeriodTierRank	Identifies the tier rank based on current contributions and the tier status rolled over from the last period (if enabled).	Number	Tier-related rank aligned to Code and Name below
nextPeriodTierCode	Identifies the tier rank based on current contributions and the tier status rolled over from the last period (if enabled).	String	For example, "UNRANKED" or "GOLD"
nextPeriodTierName	Identifies the tier rank or provides an explanatory message based on current contributions and the tier status rolled over from the last period (if enabled).	String	For instance, "Not yet qualified", "BRONZE", "SILVER", "GOLD", "TIER 1", "TIER 2", etc.
achievedDate	Captures the date/time at which the current tier status was achieved or, if the status was rolled over at the beginning of the period, the beginning date of this period.	String	Subject to rollover configuration and subsequent adjustments, contributions, or redemptions. In the case of a household, a member joining or leaving the household may also change achievedDate if the new household balance causes a change in the household tier.
nextTier	Map containing information for the accounts next tier	Object	Contains id, rank, and tierName
id	System ID for next tier	String	Created when program is created
rank	Numerical representation of the next tier	Number
tierName	Client-defined tier name	String
contributions	Details about an account tier contribution amounts	Object	Contains the spend object
spend	Map of current tier and account spend information	Object	Contains total, next, and unused; use this or "next"
unit	Map of current tier and account units purchased information	Object	Contains total, next, and unused; use this or "spend"
next	Amount of spend required to reach the next tier	String
total	Total amount of spend within the tier program period	String
unused	Amount of spend towards the current tier	String
businessUnits	List of all businessUnits participating in the program	String Array	The name of the businessUnit is in the array.
dateRange	Defines range of the tier period	Object	Contains effective and expiry dates
effective	Beginning of the tier period	String in ISO 8601 format
expiry	End of the tier period	String in ISO 8601 format
qualifyingBehaviourTypeLabel	Identifies the right behaviour to qualify.	String	For instance, "contributions" is set to "unit", then this attribute can identify the type of unit such as "Fuel"
qualifyingCartSelectorDesc	Identifies the cart selector description corresponding to the label.	String	For example, if the above attribute is "Fuel", then this might be "Fuel Qualifying Product Description"
tierContext	Identifies whether tier data applies to individual tier or household tier.	Enum: "INDIVIDUAL" or "HOUSEHOLD"	Only used when Household tier is enabled
nextPeriodTierRank	Identifies the tier rank based on current contributions and the tier status rolled over from the last period (if enabled).	Number	Tier-related rank aligned to Code and Name below
nextPeriodTierCode	Identifies the tier rank based on current contributions and the tier status rolled over from the last period (if enabled).	String	For example, "UNRANKED" or "GOLD"
nextPeriodTierName	Identifies the tier rank or provides an explanatory message based on current contributions and the tier status rolled over from the last period (if enabled).	String	For instance, "Not yet qualified", "BRONZE", "SILVER", "GOLD", "TIER 1", "TIER 2", etc.
achievedDate	Captures the date/time at which the current tier status was achieved or, if the status was rolled over at the beginning of the period, the beginning date of this period.	String	Subject to rollover configuration and subsequent adjustments, contributions, or redemptions. In the case of a household, a member joining or leaving the household may also change achievedDate if the new household balance causes a change in the household tier.

Error Responses

statusCode	errorMessage	errorCode	Definition
400 Bad Request	Session must point to an existing account	INVALID_REQUEST	Heading parameter x-identifier-type is ACCOUNT_ID and the informed identifier (account_id) is invalid
400 Bad Request	Unknown loyalty identifier type provided.	INVALID_REQUEST	The value for x-identifier-type is not one of the options: LOYALTY_ID, ACCOUNT_ID, EXTERNAL_ID, PARTNER_LINK_ID, or PHONE_NUMBER
400 Bad Request	Start session with phone number as an identifier is not supported.	INVALID_REQUEST	Phone number has not been added in the exclusive lock configuration for use.
400 Bad Request	Invalid Correlation ID	INVALID_REQUEST	Body parameter correlationId not provided
400 Bad Request	Session must point to an existing account	INVALID_REQUEST	Session is not referencing an existing account
400 Bad Request	Invalid External ID	INVALID_REQUEST	External ID is not valid or automatic creation of non-loyalty account is not enabled.
400 Bad Request	Invalid Partner Link ID	INVALID_REQUEST	Heading parameter x-identifier-type is PARTNER_LINK_ID and the informed identifier (partner_link_id) was not found.
400 Bad Request	Invalid Phone Number Format	INVALID_PHONE_NUMBER_FORMAT	Valid phone number formats include, as examples: (718) 123-4567, (718) 1234567, (718)1234567, 7181234567, 718-123-4567, 718-1234567, and +1 (718) 123-4567.
400 Bad Request	Unable to reserve points for {accountID}. Please contact Customer Service to get more information.	FAILED_REDEMPTION	Not able to redeem due to outstanding fraud prevention advice on account.
404 Not Found	Could not start a session associated with the given LoyaltyID	INVALID_LOYALTY_ID	Heading parameter x-identifier-type is LOYALTY_ID and the informed identifier (loyalty_id) was not found (either account or card)
404 Not Found	Could not start a session associated with the given Phone Number.	INVALID_REQUEST	Heading parameter x-identifier-type is PHONE_NUMBER and the informed identifier was not found (either account or card).
500 Unexpected Error Occurred	Response could not be provided for unknown reason	UNKNOWN	Report to your administrator with the GUID number in the error message.

Request

Responses

200

200 - Using Loyalty ID

Response Headers

Date
Example: Wed, 07 Aug 2024 07:22:40 GMT
Content-Length
Example: 783
Connection
Example: keep-alive
x-amzn-RequestId
Example: fc30acc6-7da9-4c93-9e02-c3abf22005a1
Referrer-Policy
Example: no-referrer
X-XSS-Protection
Example: 1;mode=block
Access-Control-Allow-Origin
Example: *
MCK-APPID
Example: ES-CB-V1
MCK-MSGID
Example: mck-c274b010-10b2-44fa-b104-3b56f5298f70
Expect-CT
Example: max-age=86400
Strict-Transport-Security
Example: max-age=31536000; includeSubDomains; preload
Feature-Policy
Example: vibrate 'none'; geolocation 'none'
X-Frame-Options
Example: sameorigin
Content-Security-Policy
Example: connect-src 'none';object-src https://*.cloudfront.net;script-src https://*.cloudfront.net
MCK-MSGTIMESTAMP
Example: August 7th 2024, 7:22:39
x-amz-apigw-id
Example: cIIN8FfloAMEQBw=
cache-control
Example: no-cache, no-store, must-revalidate
MCK_CORRELATIONID
Example: CORRELATION_ID_NOT_PROVIDED_IN_REQUEST
X-Content-Type-Options
Example: nosniff
X-Amzn-Trace-Id
Example: Root=1-66b320bf-080d9d7f3b858fee2e1ac98e;Parent=481020856d9b4f30;Sampled=0;lineage=bcf9a1b6:0

400

400 - Session Must Point to an Existing Account

Response Headers

Date
Example: Fri, 11 Jun 2021 01:52:49 GMT
Content-Length
Example: 108
Connection
Example: keep-alive
x-amzn-RequestId
Example: 5a2bf737-2978-4ea1-8a09-023cd4876287
Referrer-Policy
Example: no-referrer
X-XSS-Protection
Example: 1;mode=block
Access-Control-Allow-Origin
Example: *
Expect-CT
Example: max-age=86400
Strict-Transport-Security
Example: max-age=31536000
Feature-Policy
Example: vibrate 'none'; geolocation 'none'
X-Frame-Options
Example: sameorigin
Content-Security-Policy
Example: connect-src 'none';object-src https://*.cloudfront.net;script-src https://*.cloudfront.net
x-amz-apigw-id
Example: AvM9sFT4IAMF6rw=
cache-control
Example: no-cache, no-store, must-revalidate
X-Content-Type-Options
Example: nosniff
X-Amzn-Trace-Id
Example: Root=1-60c2c1f1-4ea10bc30313577a4c283a38;Sampled=0

404

404 - Invalid Phone Number

Response Headers

Date
Example: Fri, 11 Jun 2021 01:51:28 GMT
Content-Length
Example: 131
Connection
Example: keep-alive
x-amzn-RequestId
Example: 3a8573db-64a4-4366-a1cd-b901970a640a
Referrer-Policy
Example: no-referrer
X-XSS-Protection
Example: 1;mode=block
Access-Control-Allow-Origin
Example: *
Expect-CT
Example: max-age=86400
Strict-Transport-Security
Example: max-age=31536000
Feature-Policy
Example: vibrate 'none'; geolocation 'none'
X-Frame-Options
Example: sameorigin
Content-Security-Policy
Example: connect-src 'none';object-src https://*.cloudfront.net;script-src https://*.cloudfront.net
x-amz-apigw-id
Example: AvMxGGyroAMFScQ=
cache-control
Example: no-cache, no-store, must-revalidate
X-Content-Type-Options
Example: nosniff
X-Amzn-Trace-Id
Example: Root=1-60c2c1a0-39dc0daa6122d05715e9ffe2;Sampled=0

500

500 - Unexpected Error Occurred