Getting started with clearbit.js

The clearbit.js snippet loads a client-side JavaScript library that makes it easy to send data from your website to Clearbit. With this library, you can send page views and custom person or company traits to Clearbit X.

 

 

Add the clearbit.js snippet to your website HTML

Copy the JavaScript snippet from the clearbit.js configuration page and paste it directly before the closing </head> tag in your website's HTML.
  
Next, add any domains that you'll be loading Clearbit tags on to the Allowed Referrers list. This is a security measure that will ensure your public API key won't be used on any other sites.
 
If you just want to send your web traffic to Clearbit X, you're all done! Clearbit will automatically identify which companies are visiting your site. Visit your Clearbit Companies Dashboard to see your live web traffic. 
If you want to be more precise about which known people (as opposed to which companies) are on your site at a given time, you'll want to identify your users.

 

Identify your users

Identifying users allows you to add page view data as well as custom attributes to people in Clearbit X. Note that clearbit.js uses cookies to save all of this data to the session.

 

  
The `identify` method is how you associate your users and their page views to a recognizable `user_id` and `email`. Here is the `identify` method definition: 
clearbit.identify([userId], [traits]);

 

The `identify` call has the following fields:

 

Parameter
Datatype
Description
userId
string, optional
This is the unique and immutable ID for the user. An example would be an ID generated by a database or a UUID.
traits
object, optional
A dictionary of traits you know about the user, like their `email` or `company_domain`. This is what will be associated with all events. Some traits are special (see below for more details).

 

Here's an example of a basic `identify` call:
clearbit.identify("77e21cfd-2198-4000-944c-529097fc7019", {
  
email: "alex@clearbitexample.com"
}); 
Wait a moment! When you copy and paste the above code on your site, you’ll need to replace all those hard-coded strings with details about the currently logged-in user. We suggest using a backend template to inject an `identify` call into the footer of every page of your site where the user is logged in. That way, no matter which page they are on, they will be identified.
Depending on your templating language, it might look something like this:
clearbit.identify('{{ user.id }}', {
'email': '{{ user.email }}'
});

 

Note: A common mistake is to put values directly into this script tag without the surrounding quotes. This may cause an error, like "Unexpected Token." To avoid data loss, be certain to check that the identify call is working as expected when your page is loaded, and that no errors show up in the JavaScript console.

 

Traits

Traits are values that are associated with the user. Using traits, you can append custom data from your user database that may not exist in your CRM.
Important: The safest way to identify traits is to wrap them in quotes to avoid JavaScript syntax issues.
clearbit.identify("77e21cfd-2198-4000-944c-529097fc7019", {
 "email": "alex@clearbitexample.com",

"User Location": "San Francisco"
})

Person Traits

Simply include attributes in your identify event to attach that trait to the person. Note that traits can be totally customizable. However, there are specific traits that Clearbit treats a bit differently.
 
Trait
Datatype
Description
email
string, required
This is just the email of the user. 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:
clearbit.identify("77e21cfd-2198-4000-944c-529097fc7019", {
 '
email': "alex@clearbitexample.com",
 '
company_domain': "clearbitexample.com,
'customer': "true"
});

 

This identify event will create a person with the email`alex@clearbitexample.com` if one doesn't already exist, and attach a `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

Company traits allow you to add custom attributes to companies in Clearbit X. To add a company trait you would use a group event. Note: this requires the visitor to already be identified.

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

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

 

Troubleshooting

The best way to troubleshoot clearbit.js is to take a look at your browser's developer console. The console allows you to write JavaScript and execute methods manually. You also can inspect the Network Tab in the developer console to view requests going from the browser to Clearbit's servers.

Are you loading clearbit.js?

Open theJavaScript console. Type in `clearbit` and hit enter.
 
clearbit-console-troubleshoot.gif  
If you see the data type being loaded, then it's working! Otherwise, it means that clearbit.js is not being loaded onto the website.

Have you listed your domain(s) in Allowed Referrers list?

The Allowed Referrers list tells Clearbit which domains to accept requests from. If it's not in this list, then Clearbit will not accept requests from that domain.

How do I open the JavaScript console in your debugger?

The JavaScript console is a part of a browser's developer tools. The console reveals syntax bugs and errors that may occur in your JavaScript code. Additionally, you may execute valid JavaScript by typing into the console. Most browser developer tools allow you to see request traffic as well.
  • Chrome: COMMAND+OPTION+J (Mac) or CTRL+SHIFT+J (Windows).
  • Firefox: COMMAND+OPTION+K (Mac) or CTRL+SHIFT+K (Windows) and then click on the Console tab.
  • Safari: COMMAND+OPTION+I (Mac) or CTRL+ALT+I (Windows) and then click on the Console tab.
  • IE: F12 and then click on the Console tab.

What's next?

Clearbit X is as good as the data you provide it. To level up your data:
After you've added your data sources, then: