Legacy : Set Up an Identify Call

Last Updated: January 12, 2024

🔍 Please note: this article is for customers on Standard Bundle, Enrichment, or Clearbit Platform plans.

Implementation requires technical know-how, including front-end development skills and experience working with Javascript. Identify calls are sent to the Clearbit tag installed on your website. They're typically triggered using custom code or with a tagging system like Google Tag Manager.

Skip Ahead to:

Anatomy of an Identify Call

Here is the identify method definition:

clearbit.identify([userId], [traits]);

Each identify call contains two things:

  1. A unique user ID - The userId is a permanent and robust identifier (like a database ID) that is used to identify which user to match events and traits to. When possible, use an ID generated by a non-third party database (i.e. your own user IDs, and not IDs from SFDC or Marketo). Otherwise, you can use a randomly generated UUID, or pass along the email address of the user that is being identified.
  2. Traits about the user - A trait describes information about the user, like their name or phone number. All identify calls require the email trait, which Clearbit uses to enrich with additional company, technology, and employee data.

Here's what a typical identify call looks like:

clearbit.identify("77e21cfd-2198-4000-944c-529097fc7019", {
  "email": "alex@clearbitexample.com",
  "company_domain": "clearbitexample.com"
});

Setting the User ID

Every identify call must have a User ID, which is referenced across the user's lifetime. User IDs are a more permanent and robust identifier, like a database ID. Since these IDs are consistent across a customer’s lifetime, identify calls should include a User ID as often as possible. Depending on the technology you use, and your technical resources, we recommend setting your User ID based on one of these three options, in order of preference:

  • Use your database ID
    • For example, if you’re using MongoDB it might look something like 123f191e810c17629de765ea.
    • We recommend using database IDs instead of simple email addresses or usernames, because database IDs never change. That guarantees that you can still recognize them as the same person, tracking their traits and behavior, even as they change jobs (and adopt new emails).
  • Set a randomly generated UUID
    • If you don’t have any readily available database ID, you can always generate a new random one—we recommend UUIDs.
  • Use their email address (most common)
    • The simplest way to implement identify calls is to set the User ID using the user's email address.Here's the payload of an identify call using the email as the User ID:
    • clearbit.identify("alex@clearbitexample.com", {
  "email": "alex@clearbitexample.com",
        "company_domain": "clearbitexample.com" // example optional custom trait.
});
    • As you can see the userId and the email trait share the same value. Both fields are required, and should be explicitly defined.

Traits

Traits are values that are associated with the user and can also be used for building out segments with specific criteria. Using traits, you can append any custom data from your user database that may not exist as a field within your CRM.

Standard Traits

The identify call will accept any custom trait fields, but have two standard traits that Clearbit uses to match users to records, and to enrich profiles with company, technology, and employee data:

Trait Data Type Description
email string, required The email address of the user that is being identified. An example would be alex@clearbitexample.com. This trait is required, and is used to create or join Person records in Clearbit.
company_domain string, optional The domain of the company. Clearbit uses this trait to associate the user with their company. An example would be clearbitexample.com.

Person Traits

You can include as many attributes as necessary in your identify event, and attach those traits to a person. Here is an example of a more complex identify call where the custom trait "customer" is passed along, noting that the visitor is a user of the product:

clearbit.identify("77e21cfd-2198-4000-944c-529097fc7019", {
 "email": "alex@clearbitexample.com",
 "company_domain": "clearbitexample.com,
 "customer": "true"
});

The above identify event will create a Person profile with the email address alex@clearbitexample.com if one doesn't already exist, and attach the customer trait with the value true. It will also create a company with the domain clearbitexample.com if one doesn't already exist.

Company Traits

Similar to Person traits, Company traits allow you to add custom attributes to companies within Clearbit. To add company traits, you would use the Group method, and pass along as many custom traits inside the trait object.

đź“ť Please note: This method requires that your visitor has already been identified.

clearbit.group('ACCOUNT-GUID-1234-5678-9012', {
 'plan': "enterprise"
});

In the above example, a plan trait with the value enterprise, would be added to the company associated with the identified person

Related Articles