Creating or Updating user profile with Identify

The identify method is used to create or update a user profile in CustomerLabs. With identify method, you can update the user traits of a user in CustomerLabs.

It is a reserved method that triggers event called Create user.

Syntax

Javascript

properties = {
  // customProperties object
};

_cl.identify(properties)

Before jumping to identify method, let’s understand what are External IDs.

What are External IDs?

An External ID is any identifier that is not natively generated by CustomerLabs but is used to recognize a user or group in another platform.

Examples:

• Email address stored in your CRM → identify_by_email
• Facebook FBP cookie → facebook__fbp
• Your internal customer ID → crm_user_id
• Shopify cart token → shopify_cart_token

When the same external ID appears across multiple events, CustomerLabs merges them into a single unified profile, improving match quality when syncing to ad platforms like Meta and Google Ads.

User External IDs

User External IDs are stored under the external_ids object inside customProperties.

Reserved User External ID Keys

Key	Description
customerlabs_user_id	CustomerLabs anonymous user ID
identify_by_email	User’s email address
identify_by_phone	User’s phone number
shopify_cart_token	Shopify cart token
facebook__fbp	Facebook Browser Pixel cookie
google_analytics__client_id	GA4 client ID
facebook_lead_id	Facebook Instant Form lead ID

Javascript

var customProperties = {
    "external_ids": {
        "<external_id_key>": {
            "t": "string",
            "v": "<value>"
        }
    }
};

Note

You can also define custom external IDs (e.g., crm_user_id, lead_id, hubspot_contact_id) for granular identity tracking. These are stored on the user profile and can be used to identify users in future events.

Caution

Do not rename reserved keys (e.g., don’t use fb_fbp instead of facebook__fbp). Using standard key names ensures proper processing when syncing with ad platforms.

Building the Properties Object

To trigger the identify method, user_traits object and identify_by with ib: true attribute must be added to the customProperties object. external_ids object can also be added (but not mandatory) to the customProperties object.

Javascript

properties = {
  customProperties : {
    user_traits : {
      // traits
    },
    external_ids : {
      // external ids
    },
    <identifier> : {
      // trait used for identify by
      "ib" : true
    }
  }
};

_cl.identify(properties)

Reserved User Traits keys

The below keys are reserved for user traits in CustomerLabs.

• First Name: first_name
• Last Name: last_name
• Email: email
• Phone: phone
• Address line 1: address1
• Address line 2: address2
• City: city
• State/Province: state
• Country: country
• Country Code: country_code
• Postal Code: zip
• CustomerLabs User ID: customerlabs_user_id
• Shopify Cart Token: shopify_cart_token

Note

To trigger the identify method, atleast one unique field is mandatory under user_traits (preferably email or phone or user id as this is usually unique to that user).

Setting up the ib flag

identify_by object (flagged with ib: true) that helps the system search for the user based on a specific property key to which ib is set to true and assign user traits to that user.

Syntax Rules

• There should only be one identifier that ib is associated with per identify method call.
• The identifier with ib should be also added under customProperties.
• The value of ib should be set to true for the identifier when it is added to customProperties.

Reserved keys for ib

Reserved Identify By keys are,

• Identify by Email: identify_by_email
• Identify by Phone: identify_by_phone
• CustomerLabs User ID: customerlabs_user_id
• All the reserved user_traits and external_ids keys can be used as identify by.

Example: Identify by Email

Javascript

var email = "johndoe@example.com";

var properties = {
  "customProperties": {
    "user_traits": {
      "t": "Object",
      "v": {
        "first_name": { "t": "string", "v": "John" },
        "last_name": { "t": "string", "v": "Doe" },
        "phone": { "t": "number", "v": "1234567890" },
        "email": { "t": "string", "v": email }
      }
    },
    "external_ids": {
      "identify_by_phone": {
        "t": "string",
        "v": "1234567890"
      }
    },
    "identify_by_email": {
      "t": "string",
      "v": email,
      "ib": true // The system will identify the user by this email
    }
  }
};
_cl.identify(properties);

Example: Conditional ib Assignment

When either email or phone or both may be available, use conditional logic to set the primary ib correctly.

Javascript

// sample variables
var email = "johndoe@example.com";
var phone = "123456789";

// identify_by
var customProperties = {
    "user_traits": {
        "first_name": {
            "t": "string",
            "v": "John"
        },
        "last_name": {
            "t": "string",
            "v": "Doe"
        },
        "email": {
            "t": "string",
            "v": email
        },
        "phone": {
            "t": "string",
            "v": phone
        }
    }
}

if (email && email !== "") {
  customProperties["identify_by_email"] = {
    "t": "string",
    "v": email,
    "ib": true
  };
  if (phone && phone !== "") {
    customProperties["external_ids"] = {
      "t": "Object",
      "v": {
        "identify_by_phone": {
          "t": "string",
          "v": phone
        }
      }
    };
  }
}
else if (phone && phone !== "") {
  customProperties["identify_by_phone"] = {
    "t": "string",
    "v": phone,
    "ib": true
  };
}

if (email || phone) {
  _cl.identify(customProperties);
}

Note

The above example illustrates how to use identify_by in case there are multiple identifiers. Since there can only be one ib per event, the other identifier is added under external_ids.

So, we are telling the system that this user is primarily identified by email, but also has an alternate identifier (phone) which is added to external ids for future use. If email is not present, then phone will be used to identify the user.

Update User

The “Update user” event is used to update the details (user_traits) of a user during a particular session. This is useful for multi-step forms where you collect information gradually.

To trigger an update of user traits across your workflow, you can send the event name as Update user.

Syntax

Javascript

_cl.identify("Update user", properties)

Note

ib is not a mandatory attribute for Update user event. If ib is not provided, the system will update the user traits based.

Example

Javascript

var properties = {
  "customProperties": {
    "user_traits": {
      "t": "Object",
      "v": {
        "first_name": { "t": "string", "v": "John" },
        "last_name": { "t": "string", "v": "Doe" },
        "phone": { "t": "number", "v": "123456789" },
        "email": { "t": "string", "v": "johndoe@example.com" }
      }
    },
    "identify_by_email": {
      "t": "string",
      "v": "johndoe@example.com"
    }
  }
};
_cl.identify("Update user", properties);

Tip

View a detailed example Here – Tracking Multi-step Forms Submissions