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:
-
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. -
Traits about the user - A
trait
describes information about the user, like their name or phone number. Allidentify
calls require theemail
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).
- For example, if you’re using MongoDB it might look something likeÂ
- 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 theemail
trait share the same value. Both fields are required, and should be explicitly defined.
- 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
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