Business Keys

Business Keys allow Merchants to group customers and verifications by their source, brand, business line, or any other dimension that matters to operations. Each Business Key carries its own configuration, so a single Shufti account can apply distinct rules and settings to different customer groups without operating in isolated environments.

This documentation explains how to create and manage Business Keys in the BackOffice, how to configure duplicate account detection per key, and how Business Keys behave across the rest of the BackOffice.

Where to find Business Keys

Business Keys are managed from:

Settings → General Settings → Business Keys

From this page, Merchants can view existing Business Keys, create new ones, edit their configurations, or delete keys that are no longer in use.

Creating a Business Key

On the Business Keys page, click Create Business Key. The creation form contains the following fields.

• Name (required): The unique label that identifies this Business Key across the BackOffice, Reports, and API responses. The name is case-sensitive, must be unique within the account, and becomes immutable after creation. Plan the name carefully, as it cannot be changed later.
• Description (optional): A short note explaining the purpose of this key. Useful for teams managing multiple keys. This field can be edited at any time.
• Duplicate Account Detection (required): Controls how Shufti detects and handles duplicate applicants for customers tagged with this Business Key. See Duplicate Account Detection settings.

When the form is submitted, the new Business Key becomes immediately available across Verification Settings, the Journey Builder, Reports, Customer Profiles, and the API.

Duplicate Account Detection settings

Duplicate Detection determines whether Shufti should treat a new applicant as a duplicate of an existing customer, and what action to take when a match is found. Each Business Key carries its own Duplicate Account Detection block, so different customer groups can be treated differently within the same account.

A returning customer who verifies again using the same customer ID is recognised as the same person and is not treated as a duplicate, regardless of the configured scope or matching criteria.

Each Business Key configuration consists of two parts:

• Scope: The set of existing customers Shufti checks against when looking for duplicates.
• Matching criteria: The attributes Shufti compares, and the action taken when a match is found.

Scope

Merchants can pick one of the following scopes:

• Within this Business Key: The new applicant is compared only against existing customers carrying the same Business Key. Recommended when Merchants do not want to allow duplicate accounts for customers within the same Business Key.
• Across all Business Keys: The new applicant is compared against every customer in the account, regardless of Business Key. Recommended when the same person should not be allowed to onboard twice anywhere in the account.
• Across selected Business Keys: The new applicant is compared against customers in a chosen subset of Business Keys. When this option is selected, a Business Key selector appears for choosing which keys to include in the comparison.

The Across selected Business Keys option becomes available once more than one Business Key has been created.

Matching criteria

Matching criteria define which attributes Shufti compares between the new applicant and existing customers, and what action to take when one or more criteria match. Each criterion has:

• A checkbox to enable the criterion, which controls whether Shufti evaluates it.
• An action that determines what happens when the criterion matches an existing customer.

Two actions are available per criterion:

• Decline: The new verification is automatically declined and the applicant cannot complete onboarding for this Business Key.
• Flag in Report: The verification is allowed to proceed, but the resulting report carries a duplicate flag so reviewers can investigate before final approval.

Criterion	What it compares	Default state	Default action
Full Name + Date of Birth	The applicant's full name and date of birth as extracted from the verification document.	Enabled	Decline
Document Number	The document number, compared against existing documents of the same document type (passport against passport, ID against ID, and so on).	Enabled	Decline
Face	The applicant's selfie or document portrait matched against existing face records.	Enabled	Decline
Email	The email address associated with the applicant.	Disabled	Flag in Report
Phone	The phone number associated with the applicant.	Disabled	Flag in Report
Device Fingerprint	A fingerprint derived from the device used to complete verification. The same fingerprint across two applicants suggests the same device, regardless of the document or details submitted.	Disabled	Flag in Report

Document Number is intentionally scoped to the same document type so that a passport number which happens to overlap with an ID card number is not treated as a match.

How criteria are combined

Criteria are evaluated independently. If any enabled criterion matches an existing customer, the configured action for that criterion applies.

If more than one enabled criterion matches with different actions, Decline takes precedence over Flag in Report. For example, if an applicant matches an existing customer on Face (Decline) and on Email (Flag in Report), the verification is declined because Decline is the stricter action.

Overriding Duplicate Account Detection at creation time

When a Merchant creates a verification from the Products tab or configures a Verification Journey, and selects a Business Key that has Duplicate Account Detection enabled, a Duplicate Account Detection checkbox appears next to the Business Key selector. The checkbox is enabled by default. Unchecking it disables Duplicate Account Detection for that specific verification or Journey only.

This override is local to the verification or Journey being created. The Business Key's own settings are not changed, and other verifications or Journeys that use the same Business Key continue to follow its configured Duplicate Account Detection behavior.

If the selected Business Key has Duplicate Account Detection disabled, the override checkbox is not shown.

Editing a Business Key

Open any Business Key from the list to edit. The following fields are editable:

• Description
• Duplicate Account Detection scope
• Matching criteria toggles and actions

The Name field is read-only after creation. To rename a Business Key, create a new one and migrate verifications going forward.

Changes to Duplicate Account Detection apply to new verifications from the moment the change is saved. Historical reports retain the configuration that was in effect when they were created.

Deleting a Business Key

Deleting a Business Key is destructive. From the Business Keys list, hover over the Business Key row to reveal the action icons, then click the delete icon. A confirmation dialog explains the consequences:

• The Business Key is removed from selectors in Verification Settings, the Journey Builder, and the API.
• New verifications can no longer be tagged with the deleted key.
• Existing verifications and customer profiles that already carry the key continue to display the original key name. Past verifications and reports created under this Business Key remain accessible.

Before confirming deletion, ensure no verification journey depends on the key.

How Business Keys appear across the BackOffice

Once a Business Key is created, it surfaces wherever a verification or customer is displayed.

• Customer Profile: Each profile displays the Business Key (or keys) the customer is associated with. When a customer has verifications across multiple Business Keys, all of them appear on the profile.
• Verification Settings: A single Business Key can be assigned to a verification created from the Products tab. The verification then inherits the assigned key automatically.
• Verification Journey Builder: A single Business Key can be assigned to each Journey. Verifications running through the Journey inherit the key automatically.
• Reports: The Reports list supports Business Key as a filter. When a criterion is configured with the Flag in Report action and a match is detected, the resulting report displays a duplicate flag. Reviewers can click View Duplicate Accounts on the report to see details of the matched customer(s).

Constraints

• Business Key names must be unique within the account.
• Business Key names are immutable after creation.
• A single verification or verification journey can carry one Business Key.
• A customer can appear under multiple Business Keys if they verify via multiple verifications or verification journeys in which duplicate account detection was disabled.
• Duplicate Account Detection rules apply only to verifications created after the change is saved. Historical reports retain the rules in effect at the time of verification.

Using Business Keys with the API

To assign a Business Key to a verification created via the API, include the business_key parameter in the verification request payload. The value must match the name of an existing Business Key in the BackOffice. The same value is echoed back in the verification response and in every webhook event for that verification. Supplying a business_key is optional; if omitted, the verification is processed without a Business Key tag.

Request

{
  "reference": "17374217-ae26-4c8f-94c0-b3f6a99b1c2e",
  "callback_url": "https://yourdomain.com/shufti/callback",
  "email": "[email protected]",
  "country": "GB",
  "language": "EN",
  "verification_mode": "any",
  "business_key": "Premium Onboarding",
  "document": {
    "supported_types": ["passport", "id_card", "driving_license"],
    "name": { "first_name": "", "last_name": "" },
    "dob": "",
    "document_number": ""
  },
  "face": {}
}

Response

{
  "reference": "17374217-ae26-4c8f-94c0-b3f6a99b1c2e",
  "event": "request.pending",
  "email": "[email protected]",
  "country": "GB",
  "business_key": "Premium Onboarding",
  "verification_url": "https://app.shuftipro.com/process/<token>"
}