Identify your users

Having Clearbit.js on your site allows you to associate companies to anonymous visitors by their IP address, and create Company segments around them. By identifying users on self-identifying actions (e.g. form submissions, account creation, account login), Clearbit X can track your visitors at the person level, allowing you to filter your Person segments by page history.

 

Clearbit allows you to add page view data to an identified user, alongside any custom attributes you'd like (e.g. UTM parameters, advertise campaign data), which can then be referenced within Clearbit X. Clearbit.js uses cookies to track and save all of this data to the user's browser session.

 

In order to successfully implement and identify calls within Clearbit X, your team will need front-end engineering resources that are comfortable working with JavaScript so they can connect those identify events to user actions.

 

https://help.clearbit.com/hc/article_attachments/360033929094/Screen_Shot_2019-05-08_at_11.34.29_PM.png

 

The identify method is how you can associate your users and their page views to a user_id and email. Here is the identify method definition:

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

 

The identify call accepts the following arguments:

 

Parameter Data type Description
userId string, required This is a unique and immutable ID for the user. 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 object, required A dictionary of traits you know about the user, like their `email` or `company_domain`. This email is what will be associated with subsequent events. Some traits are special (see traits section for more details).

 

Here's an example of an identify call made, where only the userId and the email trait are defined:

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

 

Wait a moment! Instead of copying and pasting the above code onto your site, you’ll need to replace all those hard-coded strings with details about the currently logged-in user.

 

Generating Identify event IDs

In cases where your application and database have universally unique identifiers for each user (UUIDs), we recommend using those same UUIDs as your identify event ID. We'll automatically reconcile all Person data across multiple profiles that have the same identify event ID.

 

This is especially useful for consolidating all events when a user changes their email address associated with their account on your website, as all prior event data under that same event ID will be carried over to the new Person profile.

 

If your application does not have access to database user IDs, you'll instead want to either randomly generate a UUID for each user, or for simplicity's sake, pass the email address along as the event ID.

Avoid attempting to pass any IDs from third party databases or CRMs such as Salesforce or Marketo, as there's a higher technical hurdle to send that data from those respective systems over to your frontend.

 

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.

 

Person Traits

You can include as many attributes as necessary in your identify event, and attach those traits to a person. Note that traits are fully customizable and you can pass in as many as you'd like. However, the table below lists specific traits that Clearbit treats with unique behavior:

 

Trait Data type Description
email string, required  This is the email address of the user that is being identified. An example would be "marcus@helloperil.com". This is the most important trait, which is used to create or join person records in Clearbit X.
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".

 

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 addressalex@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 X. To add company traits, you would use the Group method, and pass along as many custom traits inside the trait object.

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.