Customer Grouping

A Customer in Embermind represents a unique user, identified by combining transaction attributes. The system automatically groups transactions belonging to the same person.

Overview

Customer grouping can be based on the following attributes:

Attribute	Description
External ID	Your internal customer identifier
Email	Customer email address
Phone	Customer phone number
Card Token	Tokenized card identifier
Fingerprint	Browser fingerprint
IP Address	Customer IP address

Example: If grouping by email is enabled and two transactions share the same email address, they will be merged into a single customer profile — even if other fields (phone, card, etc.) differ.

Configuration Methods

Customer grouping settings can be configured:

In the Admin Panel: Settings → Customer Grouping
Via API: Update CompanySettings

API Configuration

Request Parameters

Parameter	Type	Required	Description
`isCompanyCustomerGroupByExternalId`	boolean	No	Enable grouping by external identifier
`companyCustomerGroupByExternalIdRegExp`	string	No	Regex to validate external identifier
`isCompanyCustomerGroupByEmail`	boolean	No	Enable grouping by email
`companyCustomerGroupByEmailRegExp`	string	No	Regex to validate email
`isCompanyCustomerGroupByPhone`	boolean	No	Enable grouping by phone
`companyCustomerGroupByPhoneRegExp`	string	No	Regex to validate phone
`isCompanyCustomerGroupByCardToken`	boolean	No	Enable grouping by card token
`companyCustomerGroupByCardTokenRegExp`	string	No	Regex to validate card token
`isCompanyCustomerGroupByFingerpint`	boolean	No	Enable grouping by fingerprint
`companyCustomerGroupByFingerpintRegExp`	string	No	Regex to validate fingerprint
`isCompanyCustomerGroupByIpAddress`	boolean	No	Enable grouping by IP address
`companyCustomerGroupByIpAddressRegExp`	string	No	Regex to validate IP address
`badScoreBorder`	number	No	Bad score border threshold
`fingerprintUseType`	string	No	Fingerprint type. Values: CLIENT / INTERNAL / EXTERNAL

Example Request

curl -X POST 'https://api.embermind.ch/api/v1/client/company-settings/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "isCompanyCustomerGroupByExternalId": true,
    "companyCustomerGroupByExternalIdRegExp": null,
    "isCompanyCustomerGroupByEmail": true,
    "companyCustomerGroupByEmailRegExp": null,
    "isCompanyCustomerGroupByPhone": true,
    "companyCustomerGroupByPhoneRegExp": null,
    "isCompanyCustomerGroupByCardToken": true,
    "companyCustomerGroupByCardTokenRegExp": null,
    "isCompanyCustomerGroupByFingerpint": true,
    "companyCustomerGroupByFingerpintRegExp": null,
    "isCompanyCustomerGroupByIpAddress": false,
    "companyCustomerGroupByIpAddressRegExp": null,
    "badScoreBorder": 50,
    "fingerprintUseType": "CLIENT"
  }'

Response (200 OK)

{
  "message": "OK"
}

Regex Validation

Each grouping attribute can be validated using a regular expression. If a value doesn't match the regex pattern, grouping by that attribute will be skipped.

Example: Only group by emails from specific domains:

curl -X POST 'https://api.embermind.ch/api/v1/client/company-settings/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "isCompanyCustomerGroupByEmail": true,
    "companyCustomerGroupByEmailRegExp": "^[a-zA-Z0-9._%+-]+@(gmail\\.com|yahoo\\.com)$"
  }'

Important Notes

If all grouping attributes are disabled, customers will not be merged — each transaction will create a separate customer.
Grouping is performed at transaction creation time. Changing settings does not retroactively regroup existing customers.
IP address grouping is disabled by default because many users may share the same IP (e.g., corporate networks, mobile carriers).

Fingerprint Use Type

Value	Description
`CLIENT`	Use the `fingerprint` field sent in transaction request
`INTERNAL`	Use Embermind's internally collected fingerprint
`EXTERNAL`	Use fingerprint from external provider (e.g., FingerprintJS Pro)

Next Steps

Scoring Rules — Configure risk scoring
Fingerprint SDK Integration — Collect browser fingerprints