Add Customer

Introduction

This API registers customers in the organization with the primary identifiers being either the mobile number, email ID, or external ID. To add a customer, you must provide at least one of these parameters.

Pre-requisites

Make sure you have the right authentication and appropriate access control configured.

Access group resource: Write access to customer group resource. For more information on access control, see the access group documentation.
Authentication: Basic authentication details. For more information on authentication, see the Authentication documentation.
Define all the necessary configurations. The mandatory attributes for customer registration depend on the configurations set on InTouch Settings > Registration Configuration.
Define custom and extended fields according to your requirements, if you need to use them during registration.

Header Information

You can define certain attributes in the API header section, and also specify the Audit-related user context details.

Header Name	Description
Authentication/Authorization Type	Should be Basic Auth
Request / Content Type	Should be application/json
Response Type	Should be application/json
USER-CONTEXT-ENTITY-TYPE	Refers to the classification of the user. This field does not have predefined validations, and you can define any values according to your specific requirements. For example, you could classify a user as an "Intouch Admin User". This field is not displayed in Member Care.
USER-CONTEXT-ENTITY-ID	Refers to a unique identifier associated with the user entity type. For instance, it could be an Intouch admin user ID such as 3124587. This field does not have predefined validations, and you can define any values according to your specific requirements. This field is not displayed in Member Care.
USER-CONTEXT-ENTITY-SOURCE	Refers to the source through which changes are made. The standard values for this field are: API IMPORT CONNECT_PLUS MEMBER_CARE REQUEST_WORKFLOW. Note: You can raise a JIRA request to the sustenance team and add more values, as per your requirement.
USER-CONTEXT-ENTITY-SOURCE-ID	Refers to ID if associated with the user source. This field does not have any validations.

Rate limit

Demo and Testing Clusters: 1,000 requests per minute per API key
Other Organizations: The rate limit is brand-specific.

To modify the limit, create a ticket with the Capillary Product support team.

Body parameters

Field	Type	Required	Description
customer	Object	Yes	The customer entity is the focal point around which all data revolves. It includes customer information about purchase history, behavioral activities, loyalty details, the user groups they are part of, reward and coupon details, and other related information.
.mobile	string	Yes	The customer’s mobile number. Add a mobile number with the country code. Only numeric characters are supported (0-9).
.email	string	Yes	The customer’s valid email address. Supported characters: a-z A-Z 0-9 - _ + . and @
.external_id	string	Yes	The customer’s external identifier. Special characters are not recommended. Maximum length is 250 characters.
.firstname	string		The customer’s first name. Alphanumeric, spaces, hyphens, apostrophes are supported. The maximum length is 100 characters.
.lastname	string		The customer’s last name. Alphanumeric, spaces, hyphens, apostrophes are supported. The maximum length is 100 characters.
.updated_on	datetime		The date and time when the customer was last updated. Format: YYYY-MM-DD HH:MM:SS Example: 2025-02-26 09:10:00
.registered_till	string		The till name registered with the customer. Maximum length is 50 characters.
.associated_with	string		The till name associated with the customer. Maximum length is 50 characters.
.type	enum		The customer type. Values allowed are loyalty, non_loyalty.
.source	string		The source from where the customer's data is collected or registered from. Example: an in-store system. Values allowed are InStore, Facebook, WebEngage, WeChat, E-commerce, Website, Line, Mobile App, and more.
.accountId	string		A unique identifier associated with the specific source or channel through which the customer's profile was created or registered.
.fraud_status	enum		The customer’s fraud status. Values allowed are NORMAL, OUTLIER, FRAUD, INTERNAL, INVALID.
..status	string
.commChannels	Object		The medium through which a customer can receive messages or notifications from the brand. Values allowed are SMS, email, mobile push notifications, WeChat, LINE, WhatsApp, and others.
..type	string		Modes of communication with the customer. Values allowed are mobile, email, card number.
..value	string		Value of the type of communication.
..primary	string		Indicates if the communication type is the primary contact.
..verified	string		Indicates if this communication type is verified.
..meta	Object		Contains meta information of the customer.
.custom_fields	Object		Custom fields are used to store information specific to a brand's needs, such as customer preferences or product attributes. To use these fields during registration, you must define them beforehand.
..name	string		Name of the custom field.
..value	string		Value for the custom field.
.extended_fields	Object		Extended fields are predefined, standardized fields that capture additional information for various entities, such as customers or transactions. To use them during registration, they must be pre-defined.
..name	string		Name of the extended field.
..value	string		Value of the extended field.

Response parameters

Field	Type	Description
.success	string	Indicates the success of the operation.
.code	string	The code representing the status of the operation.
.message	string	The message describing the status of the operation.
.total	string	The total count in the response.
.success_count	string	The count of successful operations.
customer	Object
.user_id	string	The unique identifier for the customer.
.firstname	string	The customer’s first name.
.lastname	string	The customer’s last name.
.mobile	string	The customer’s mobile number.
.email	string	The customer’s valid email address.
.external_id	string	The customer’s external identifier.
.lifetime_points	string	Customer’s total lifetime points accumulated.
.loyalty_points	string	Customer’s current loyalty points.
.current_slab	string	Customer’s current slab in the loyalty program.
.tier_expiry_date	datetime	Customer's current tier expiry date.
points_summaries	Object
..programId	string	The ID of the program associated with the points summary.
..redeemed	string	The number of points redeemed.
..expired	string	The number of points expired.
..returned	string	The number of points returned.
..adjusted	string	The number of points adjusted.
..lifetimePoints	string	The lifetime points in the summary.
..loyaltyPoints	string	The loyalty points in the summary.
..cumulativePurchases	string	The cumulative purchases in the summary.
..currentSlab	string	The current slab in the points summary.
..nextSlab	string	The next slab in the points summary.
..nextSlabSerialNumber	string	The serial number of the next slab.
..nextSlabDescription	string	The description of the next slab.
..slabSNo	string	The serial number of the slab.
..slabExpiryDate	datetime	The expiry date of the slab.
..totalPoints	string	The total points of the slab.
customer	Object
.lifetime_purchases	string	Customer’s total lifetime purchases made.
.registered_on	datetime	The date and time when the customer registered.
.updated_on	datetime	The date and time when the customer's information was last updated.
.type	string	The type of customer.
.source	string	The source through which the customer was acquired.
.fraud_status	enum	The fraud status of the customer
.reason	string	The reason field (not populated in this response).
custom_fields	Object	Custom fields are used to store information specific to a brand's needs, such as customer preferences or product attributes.
..name	string	Name of the custom field.
..value	string	Value for the custom field.
extended_fields	Object	Extended fields are predefined, standardized fields that capture additional information for various entities, such as customers or transactions. To use them during registration, they must be pre-defined.
..name	string	Name of the extended field.
..value	string	Value of the extended field.
..Subscription	Object	Customer Subscription determines whether a customer has opted or not opted, receiving promotional or transactional communications from specific sources.
sideEffects	Object	Object containing side effects (additional information) for the customer creation, if any.
..entityType	string	Entity which receives points. Possible values: USER, USERGROUP2, GROUP2
..rawAwardedPoints	string	Total number of points awarded without any rounding applied.
..customerId	string	Unique ID of the customer who is awarded points
..awardedPoints	string	Total number of points awarded with rounding applied.
..type	string	Type of award rewarded to the customer.
..isReferrer	boolean	Indicates if the customer is a referrer.
item_status	Object
..success	string	Indicates the success of the customer item operation.
..code	string	The code representing the status of the customer item operation.
..message	string	The message describing the status of the customer item operation.
..warning	string	Warning codes associated with the operation.

Error codes

Error Code	Description
500	All requests have failed due to errors. Invalid or unsupported inputs passed.
1007	Error in customer registration: No Valid Mobile Number or External ID or Email provided required for registration. No valid mobile number, external ID, or email provided.

Additional Notes

API Behavior

If CONFIG_SKIP_SECONDARY_ID_ON_PRIMARY_MISMATCH is enabled, if the primary identifier is different but any of the secondary identifiers exist, a new customer is registered with the primary identifier ignoring the secondary identifier. The config is available on the Registration Page of InTouch Profile > Organization Settings > Miscellaneous.
Also, this config overrides CONF_PRIMARY_IDENTIFIER_STRICT_CHECK.