The Lookup API is useful for in situations where you don't have the customerId. Instead, you can retrieve customer details using other identifiers such as phone numbers or email addresses. The API provides more detailed information, including details about loyalty programs like slab numbers.

This API can fetch the following information -

profile information – first name, last name, registered date, registered at TILL
recent profile updated – details of the recent update in profile information
registered identifiers, communication channels
loyalty information – loyalty status, registered date, purchases, etc.
Multiple Loyalty Program Details: Program wise details if the org has multiple loyalty programs support
Card level details
Alternate currency details with associated program ID and its name.

To fetch customer details from a specific account of a source (source with multiple accounts), you need to provide the respective account id.

Using Multiple Identifiers

When dual eligibility is enabled in your organisation, the API allows you to send multiple identifiers while fetching details, and the system automatically identifies which one is the primary identifier and retrieves the details accordingly. This removes the need for you to know or specify only the primary identifier, which is beneficial in a dual eligibility-enabled scenario, as the feature allows you to register multiple users with the same secondary identifiers.
When you submit multiple identifiers in a lookup request:

The service checks that dual eligibility is active.
It parses all submitted identifiers, for example email,mobile,externalId
It determines which identifier is configured as the primary key.
If one of the provided values matches the primary key, the API uses it for the lookup.
The API returns the single customer profile associated with the primary identifier.

You can enter multiple identifiers as comma-separated values using the identifierName and identifierValue query parameters. Ensure the order of the identifierName matches the identifierValue.

Note: If you provide only one identifier that is not the primary identifier, the system will return an error, 8015 - Customer not found for given identifiers.

Endpoint Example

<https://eu.api.capillarytech.com/v2/customers/lookup/customerDetails?source=INSTORE&&identifierName=email,mobile,externalID&[email protected],915795008395,MPQSP100>

Here,

[email protected] is the email
915795008395 is the mobile number
MPQSP100 is the external ID

📘
Note:
Use V1 Get Customer Details API to retrieve:
-Customer's loyalty tier change history.
-Details of the store where the customer was registered. -Details of the POS (Point of Sale) machine of the store where the customer was registered. -National Do Not Call Registry (NDNC) status of the customer’s registered mobile number. -Services (SMS/email) that the customer has opted in or out of. -Criteria set for membership or tier retention. -Coupon history in a specified order. -Coupon details in ascending or descending order. -Recently used coupon information. -Desired set of coupons in the issuing order. -Details of active coupons.

API endpoint example

<https://eu.api.capillarytech.com/v2/customers/lookup/customerDetails>

Prerequisites

Authentication - Basic or OAuth authentication details
Access group resource - NA

Resource information


URI	/v2/customers/lookup/customerDetails
HTTP method	GET
Pagination supported?	No
Rate limit	NA
Batch support	NA

Request query parameters

Field Name	Data Type	Description	Mandatory
`source`	Enum	Source on which the customer identifier is available. Example: `INSTORE`, `MARTJACK`, `WECHAT`, `ALL`, `MAPP_SDK`	Yes
`accountId`	String	Account ID for sources with multiple accounts.	Mandatory for all the sources except `Instore`.
`embed`	Array of Strings	Details to be included in the response. Values: `points`, `subscriptions`, `mlp`, `promotionalPoints`, `expirySchedules`, `expiredPoints`, `segments`, `userGroup`, `customerImage`, `cardLoyaltyDetails`, `fleetParentDetails`, `ignoreCardDetails`, `customerStatus`, `alternateCurrencies`. Note: Embed parameter `gapDetails` is deprecated.	No
`identifierName`	Enum	Identifier type used to get the customer details. Supported values: `cardnumber`, `mobile`, `email`, `externalId`, `wechat`	Yes
`identifierValue`	String	Value of the specified identifier.	Yes
`includedFraudDetails`	Boolean	Pass `true` to fetch fraud details of the customer if available.	No
`includedUserGroup2LoyaltyDetails`	Boolean	Pass `true` to include group loyalty details in the response.	No
`userGroup2Id`	Long	Unique ID of the user group to fetch customer details of that specific group.	No
`includedAllUserGroup2`	Boolean	Pass `true` to fetch customer details across all the groups of the customer.	No
`gapToUpgrade`	Integer	Prerequisite: Set `embed=MLP` to retrieve the details. This retrieves the additional purchases, points, visits, or tracker value required for a customer to upgrade to the next tier. It calculates this based on a specified number of days from the current date. Supported values: `0`: For current day `1`: For next day `30`: For 30 days ahead Negative values are not supported.	No
`gapToRenew`	Integer	Prerequisite: Set `embed=mlp` to retrieve the details. Retrieves the renewal value (purchases, points, visits, or tracker) required after a specified number of days. Supported values: `0`: For current day `1`: For next day `30`: For 30 days ahead Note: Not shown if the customer is in the base slab.	No

Response parameters

Parameter	Data Type	Description
id	integer	Unique identifier for the customer
profiles	array	Profiles associated with the customer
loyaltyInfo	object	Information related to the customer's loyalty program
- loyaltyType	string	Type of loyalty program
- attributionV2	object	Details about loyalty program attribution
-- createDate	string	Date and time when the loyalty program attribution was created
-- createdBy	object	Details of the user who created the loyalty program attribution
-- modifiedBy	object	Details of the user who modified the loyalty program attribution
-- modifiedDate	string	Date and time when the loyalty program attribution was modified
-- createdFromSource	string	Source from which the loyalty program attribution was created
- lifetimePurchases	float	Total lifetime purchases made by the customer
segments	object	Segments associated with the customer
associatedWith	string	Identifier of the entity associated with the customer
extendedFields	object	Additional fields associated with the customer
loyaltyProgramDetails	array	Details of the loyalty program associated with the customer
- redeemed	float	Total points redeemed by the customer
- expired	float	Total points expired for the customer
- returned	float	Total points returned to the customer
- adjusted	float	Total points adjusted for the customer
- lifetimePoints	float	Total lifetime points earned by the customer
- loyaltyPoints	float	Total loyalty points earned by the customer
- cumulativePurchases	float	Cumulative purchases made by the customer
- loyaltyId	integer	Unique identifier for the loyalty program
- currentSlab	string	Current tier or slab in the loyalty program
- nextSlab	string	Next tier or slab in the loyalty program
- nextSlabSerialNumber	integer	Serial number of the next tier or slab
- nextSlabDescription	string	Description of the next tier or slab
- slabSNo	integer	Serial number of the current tier or slab
- slabExpiryDate	string	Expiry date of the current tier or slab
- programId	integer	Unique identifier for the loyalty program
- delayedPoints	float	Points that are delayed for the customer
- delayedReturnedPoints	float	Returned points that are delayed for the customer
- delayedExpiredPoints	float	Expired points that are delayed for the customer
- totalAvailablePoints	float	Total available points for the customer. available points are the points earned through promotions and base points
- totalReturnedPoints	float	Total points that have been returned from the customer
- linkedPartnerPrograms	array	Partner programs that are linked to the customer
- programTitle	string	Title of the loyalty program
- programDescription	string	Description of the loyalty program
- programPointsToCurrencyRatio	float	Ratio of loyalty points to currency for the program
groupLoyaltyProgramDetails	array	Details of group loyalty programs associated with the customer
- groupProgramId	integer	Unique identifier for the group loyalty program
- title	string	Title of the group loyalty program
- description	string	Description of the group loyalty program
- programsList	array	List of programs associated with the group loyalty program
-- id	integer	Unique identifier for the program
-- name	string	Name of the program
-- description	string	Description of the program
- lifetimePoints	float	Total lifetime points earned for the group loyalty program
- loyaltyPoints	float	Total loyalty points earned for the group loyalty program
- promisedPoints	float	Total promised points for the group loyalty program
- pointsToCurrencyRatio	float	Ratio of points to currency for the group loyalty program
cardDetails	array	Details of the card associated with the customer
- cardId	integer	Unique identifier for the card
- issuedDate	string	Date and time when the card was issued
- createdDate	string	Date when the card was created
- expiryDays	integer	Number of days until the card expires
- seriesName	string	Name of the card series
- customerId	integer	Unique identifier for the customer
- maxActiveCards	integer	Maximum number of active cards allowed for the customer
- customFields	object	Custom fields associated with the card
- type	string	Type of the card
- cardNumber	string	Unique number assigned to the card
- seriesId	integer	Unique identifier for the card series
- seriesCode	string	Code of the card series
- orgId	integer	Unique identifier for the organization
- entityId	integer	Unique identifier for the entity associated with the card
- statusInfo	object	Information about the status of the card
-- reason	string	Reason for the card status
-- createdBy	integer	Unique identifier of the user who created the card
-- actions	array	Actions associated with the card status
-- autoUpdateTime	string	Date and time of the last automatic update to the card status
-- createdOn	string	Date and time when the card status was created
-- entityId	integer	Unique identifier of the entity associated with the card status
-- id	integer	Unique identifier for the card status
-- isActive	boolean	Indicates whether the card status is active
-- labelId	integer	Unique identifier for the label associated with the card status
-- label	string	Label associated with the card status
-- status	string	Current status of the card
- transactionNotAllowed	boolean	Indicates whether transaction are allowed with the card
- expiryDate	string	Date and time when the card expires
- activeAndDigital	boolean	Indicates whether the card is active and digital
alternateCurrencyDetails	array	Includes the details on alternate currency awarded
-programId	integer	Unique identifier of the loyalty program in which the customer is associated with
-programName	string	Name of the loyalty program
-alternateCurrencyData	object	Object containing alternate currency details
--name	string	Name of the alternate currency
--earned	float	Number of alternate currencies available for redemption
--lifetimeEarned	float	Number of alternate currencies earned by the customer in their lifetime, including redeemed and returned alternate currencies
--redeemed	float	Number of alternate currencies redeemed by the customer
--expired	float	Number of expired redeemable alternative currencies
--returned	float	Number of redeemable alternative currencies returned by the customer
--delayedEarned	integer	Number of available alternate currencies in the promised state
--delayedLifetimeEarned	integer	Number of alternate currencies earned by the customer in their lifetime, including redeemed, returned, and redeemable alternate currencies
--delayedReturned	integer	Number of promised alternative currencies returned by the customer
--delayedExpired	integer	Number of expired promised alternative currencies
--totalAvailable	float	Number of available alternate currencies, including redeemable and promised alternate currencies
--totalRedeemed	float	Number of alternate currencies redeemed by the customer
--totalReturned	float	Number of redeemable and promised alternative currencies returned by the customer
--totalExpired	float	Number of expired redeemable and promised alternative currencies
warnings	array	Warnings associated with the response
- status	boolean	Indicates the status of the warning
- code	integer	Code associated with the warning
- message	string	Message describing the warning
upgradeStrategies	array	Provides the set of rules or conditions that defines how a customer progresses to a higher tier in a loyalty program.
-upgrade_based_on	string	Parameter using which the upgrade condition is determined. Example: `CUMULATIVE_PURCHASES`; `TRACKER_VALUE_BASED`, `CURRENT_POINTS`
-upgradeThreshold	double	Threshold value required for an upgrade. Example: `50.0` `CUMULATIVE_PURCHASES`.
-customerUpgradeEntityValues	integer	Current values related to the customer’s upgrade.
--currentValue	double	Current value attained by the customer. Example: `0.0` `CUMULATIVE_PURCHASES`.
--gapToUpgrade	double	Additional value required for the upgrade. Example: `50.0` `CUMULATIVE_PURCHASES` (threshold value - current value)
--valueValidUpto	string	Date untill which the value is valid, in YYYY-MM-DD format. Example: `2025-05-06`.
gapToRenewSummary	array	Set of rules or conditions required for tier renewal for the customer in a loyalty program. Note: If the customer is in the base slab, this block will not be displayed.
-tierExpiryDate	string	Expiry date of the current tier, in YYYY-MM-DD format. Example: 2024-12-31.
-renewConfirmed	boolean	Indicates if the tier renewal is confirmed. Values: `true` or `false`.
-renewStrategies	array	Array containing details of the rules or conditions for tier renewal.
--renewBasedOn	string	Specifies the renewal strategy. Example: `VISITS`, `PURCHASE`, `POINTS`, or `TRACKER`.
--renewThreshold	double	Threshold value required by the customer to renew the tier. Example: 5.0 for store visits, 10.0 for purchases.
--customerRenewEntityValue	double	Current value reached by the customer. Example: 1.0 store visit or 123.0 points
--customerGapToRenewValue	double	Additional value required for the tier renewal. Example: 4.0 store visits, 10.0 purchases or 1877.0 points.

Error Code

Error Code	Description	Reason
8015	Customer not found for the given identifiers	The identifier provided is not correct. When dual eligibility is enabled, if the primary identifier is missing from the input, the system returns the same error. Account ID is not defined. Applicable for sources other than Instore.