Identity ResolutionUpdated 03/01/2019

Learn how to resolve Users and Accounts according to your custom business logic beyond Hull’s default identity resolution strategy.

To combine data about the same person or company, you need to match a set of unique identifiers together — this process is called identity resolution.

Identity resolution is a critical step to creating a single source of truth for your customer data.

Hull’s Identity Resolution Strategy

Hull’s identity resolution algorithms work on a system of claims. You can see how the Hull identity resolution strategy works here and how the claims lookup strategy works here.

In summary, unless a higher-order identifier is specified then:

  • Person profiles (Users) will be matched by email
  • Company profiles (Accounts) will be matched by domain
  • Email is used to match Users to Accounts with the same Domain

Specifying your “leading system” with an external ID

Each User and Account record in a database needs a unique identifier. The “leading system” is the provider of that unique identifier and becomes the central profile to associate data around.

Hull’s default behavior assumes that it is the leading system. The unique identifier is the Hull-assigned identifier for each User and Account. Hull will then merge any duplicate email or domain from services into one profile.

However, some team’s business logic requires more complex relationships between people and companies.

For example, a person (with one email) may have many bank accounts for different purposes — these separate bank accounts shouldn’t be merged indiscriminately. Instead, the bank account number should be the primary identifier.

Your leading system might be your production database connected to your product, or your CRM. Here you’ll have a separate identifier or id to associate everything about a person (or company) including their email address(es).

You can import this identifier into hull and define it as the external_id in Hull. This is the highest priority identifier in Hull’s identity resolution strategy — profiles with an external_id cannot be merged.

Associating people and companies

By default, Hull will match Users by email with Accounts of the same domain. Once set, this will not be overwritten unless it is explicitly changed.

These freemail addresses (like won’t write into a domain.

Warning: Data enrichment connectors may be able to write to user.domain and associate data. If this is incorrect, you may end up with falsely associated Users and Accounts.

Custom Linking Users and Accounts

You can link a User with an Account using Processor or Incoming Webhooks.

You can do this by setting a claim with the hull.account() call. Supported claims are domain, id (not recommended), and external_id.

To link an account that is identified by the domain, you would write:

hull.account({ domain: <value> })

This example is link a User's Account from Clearbit or the Account domain.

const { clearbit, domain } = user;

// Define which domain to use to identify the account
const accountDomain = domain || clearbit.employment_domain;

// Link the User to the account identified by accountDomain
hull.account({ domain: accountDomain });

Merging duplicate contacts and accounts in 3rd party tools

Hull’s identity resolution strategy ensures there is a unique profile within your Hull Organization. Data will be mapped from this profile to your third party systems.

Hull does not automatically merge and deduplicate contacts and accounts in your third party tools. Data might be ingested from multiple duplicate profiles and merged within Hull, but Hull does not identify or delete profiles in other tools.