get https://{host}/v2/customers/lookup/customerDetails
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.
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://nightly.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 |
|---|---|---|
| source | Enum | Source on which the customer identifier is available. Ex: INSTORE, MARTJACK, WECHAT, ALL |
| accountId | String | Account ID for sources with multiple accounts. |
| 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. |
| identifierName | Enum | Identifier type used to get the customer details. Supported values: cardnumber, mobile, email, externalId, wechat |
| identifierValue | String | Value of the specified identifier. |
| includedFraudDetails | Boolean | Pass true to fetch fraud details of the customer if available. |
| includedUserGroup2LoyaltyDetails | Boolean | Pass true to include group loyalty details in the response. |
| userGroup2Id | Long | Unique ID of the user group to fetch customer details of that specific group. |
| includedAllUserGroup2 | Boolean | Pass true to fetch customer details across all the groups of the customer. |
| gapToUpgrade | Integer | Prerequisite: Set embed=MLP to retrieve the details.The gapToUpgrade parameter retrieves the details of 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: Retrieves the gap for the current day. 1: Calculates the gap for the next day. 30: Projects the gap 30 days from the current day. Negative values are not supported. |
| gapToRenew | Integer | Prerequisite: Set embed=mlp to retrieve the details.Thie gapToRenew parameter retrieves the additional purchases, visits, points, or tracker value required for a customer to renew their tier after a specified number of days from the current date. Supported values:: 0: Retrieves the renewal value for the current day. 1: Calculates the renewal value for the next day. 30: Projects the renewal value 30 days from the current day. Negative values are not supported. Note: If the customer is in the base slab, this block will not be displayed. |
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. |