Implement Identify Calls on Your Web Forms

Skip to:

What Is an Identify Call

Identify calls are sent using a snippet of JavaScript that communicates with the Clearbit tag. They tell the Clearbit tag who the user is (e.g. their email address) so that it can attribute past and future browsing behavior to that user in the Clearbit platform. 

Clearbit_Identify_Call.png

Each identify call includes a unique User ID, their email address, and any optional traits you know about the user.

 

Are you a Segment customer? Clearbit's Segment integration allows you to import your identified user traits and page views directly into Clearbit! We recommend that Segment customers use the Segment Identify spec and send that data to Clearbit so that you get the full benefit of Segment's CDP and avoid having to manage redundant code.

Sending Identify calls allows you to track user behavior for activity-based segmentation, Contact Audience targeting, and accurately tracking conversions from ads.

When should I send an Identify call? Clearbit recommends that you make an Identify call whenever a user fills out a form, signs up, or updates their user information in your app.

Check the identify user guide for more examples →

 

When to Send an Identify Call

We recommend that you make an Identify call whenever a user fills out a form, signs up, or updates their user information in your app.

For example...

Common marketing Identify calls

  • When a user fills out a contact form (e.g. a demo request)
  • When a user downloads content (e.g. an ebook) or registers for a webinar
  • When a user subscribes for a newsletter

Common in-app Identify calls

  • After a user first signs up
  • After a user logs in
  • When a user updates their info in your app (for example, they change or add a new address)
  • Upon loading any pages that are accessible by a logged in user (optional)

How frequently should I send Identify calls? If possible, we recommend sending an Identify call whenever a user reveals their identity to you, even if you have identified them before.

Why? Because most users access your website across multiple devices. And even if you manage to identify them across every device, local storage and cookies expire over time, meaning that tracking data will be lost unless you continue to re-identify users over time.

 

How to Send an Identify Call

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.

Have you installed clearbit.js on your website? If not, you can find the instructions here...

 

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.
  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 the payload of a typical identify call:

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

Wait! Before you copy and paste this code... remember to replace those hard-coded strings with your user's unique ID and email. The one above is just an example!

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.

 

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:

1. 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).

2. 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.

3. 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 audiences 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.

📝 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.

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.

📝 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.

Need Help?

Your customer care team is here to help!

For technical troubleshooting, email support@clearbit.com.

For general questions or strategic help with your Identify calls, email your dedicated Customer Success Manager.