Implement Identify calls

What is an Identify call?

The Identify call helps Clearbit identify users, track those users' actions (like page views), and record traits about them. Each identify call includes a unique User ID, their email address, and any optional traits you know about the user.

Clearbit_Identify_Call.png

The Identify call also helps advertisers track Conversion events by automatically collecting ad click data, and associating the data back to users in our database.

When to 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.

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)

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

Identify calls are sent to the Clearbit Javascript installed on your website.

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

Identify calls are typically triggered using custom code or with a tagging system like Google Tag Manager. Implementation requires technical know-how, including front-end development skills and experience working with Javascript.

How to structure 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.
  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 (recommended)

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.

This is suboptimal, but is a common and acceptable approach for marketers who do not have a user database, or do not have the technical resources required to generate and send unique IDs.

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"
});

As you can see the userId and the email trait share the same value. Both fields are required, and should be explicitly defined.

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.