Get Customer Details

Retrieves all the details of a customer. Use embed and other parameters to get a specific information as per needed.

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 methodGET
Pagination supported?No
Rate limitNA
Batch supportNA

Request query parameters


Field NameData TypeDescriptionMandatory
sourceEnumSource on which the customer identifier is available.
Example: INSTORE, MARTJACK, WECHAT, ALL, MAPP_SDK
Yes
accountIdStringAccount ID for sources with multiple accounts.Mandatory for all the sources except Instore.
embedArray of StringsDetails 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
identifierNameEnumIdentifier type used to get the customer details.
Supported values: cardnumber, mobile, email, externalId, wechat
Yes
identifierValueStringValue of the specified identifier.Yes
includedFraudDetailsBooleanPass true to fetch fraud details of the customer if available.No
includedUserGroup2LoyaltyDetailsBooleanPass true to include group loyalty details in the response.No
userGroup2IdLongUnique ID of the user group to fetch customer details of that specific group.No
includedAllUserGroup2BooleanPass true to fetch customer details across all the groups of the customer.No
gapToUpgradeIntegerPrerequisite: 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
gapToRenewIntegerPrerequisite: 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.
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!