Spec: Identify

identify method is used to give an identity to your users and record data about them.

We recommend you calling identify method in following scenarios:

  1. After a user Signup
  2. After a user Login to your application
  3. All the pages that are accessible by the Logged in user. Because, calling identify method in Sign in will identify the newly signed in users. But, you might miss out identifying the already signed in Users. So, keeping the identify call in a file and sharing it across all the pages in your application will solve this problem.

identify method has the following fields:

FIELD TYPE DESCRIPTION
userID
(Required)
String This is the unique identification that you can give to your User. Usually Database ID will be used as userID. Refer userID section to know more.
properties
(Optional)
Object This contains the information you know about the user. Refer properties section to know more.
successCallback (Optional) Function A function that is executed after receiving the success response for identify call. This callback is available only in Javascript Library.
failureCallback (Optional) Function A function that is executed incase of failed identify calls. This callback is available only in Javascript Library.
UserID

This should be the unique identification that you can give to your user. This can be the database ID or email address or user name of the user.

Since, database ID of the user is unique and will not change anytime, we would recommend you to use database ID instead of email address or username. This guarantees that, even if user changes their email address, you can still recognize them as the same person.

Properties

Properties contains the information of an user.

Properties is an optional field in identify call. But, If you are using database ID as userID, it is mandatory to pass atleast "Email" under properties.

Properties payload will contain key value pairs, where key should be the Label of any of the Freshsales fields. This fields can be the default field that Freshsales provided or custom field that you have created.

Fields that can be passed under Properties can be found at Admin Settings >> Lead fields in your Freshsales Account.

If you wish to pass company details of the user, you should be bundling all those details under company key. Fields that can be passed under company can be found at Admin Settings >> Account Fields in your Freshsales Account. Similary, fields that can be passed under deal key can be found at Admin Settings >> Deal Fields in your Freshsales Account.

Here's a example of the above explanation:

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ "First name" : "John", "Last name" : "Doe", "Email" : "john.doe@example.com", "Message": "Sample Message", "company" : { "Name" : "Example" }, "deal": { "Product" : "Sample Product" } }
EXPAND ↓

There are certain properties reserved such as fs_update or fs_contact which should be used for their intended meaning. Refer How identify call works section to know more about these reserved properties.

  1. fs_update:

    This accepts boolean value i.e, either true or false. This will have a default value of true. You can send this along with other properties of the user. i.e,

    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    { "First name" : "John", "Last name" : "Doe", "Email": "john.doe@example.com", "fs_update" : false, "Message": "Sample Message", "company" : { "Name" : "Example" } }
  2. fs_contact:

    This accepts boolean value i.e, either true or false. This will have a default value of false. You can send this along with other properties of the user. i.e,

    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    { "First name" : "John", "Last name" : "Doe", "Email": "john.doe@example.com", "fs_contact" : true, "Message" : "Sample Message", "company" : { Name" : "Example" } }

You should make sure that the piece of user information that is sent for a field should match with the type of the field. Below is the list of different types of fields Freshsales supports, along with the description explaining about the format data should be sent:

FIELD TYPE DESCRIPTION
Text field Information should be of maximum 255 characters.
Text area Information can be of size more than 255 characters.
Number

Information should be in a valid number with the format (11, 4) i.e, maximum 11 digits before the decimal point maximum 4 digits after the decimal point.

If you are passing "+1" or "-1" for a Number field, the existing value will be incremented / decremented by 1. If you are passing just 1, the existing value will be replaced by 1. This feature will be useful, if you have created a custom field with label "Number of items purchased" and want to increment the value every time User purchases a new item.

Date picker Information should be in ISO 8601 format.
Checkbox Information should be a boolean value i.e, either "true" or "false"
Dropdown

Information should be a value same as one of the options of the dropdown. i.e, If you have a dropdown "Business type" which has three options "Integrator", "Analyst" and "Investor". Your data should look as shown below:

Copied Copy
1
2
3
4
5
6
7
{ ..., "Business type" : "Analyst" .... }

The above is applicable for all default and custom dropdown fields.

Radio button This works similar like Dropdown field mentioned above.

You can even create custom fields on the fly using identify. i.e,

  1. If you are sending a field "Message" in your payload, if there exists no custom field with that label in your Freshsales account, a new custom field with label "Message" of type Text will be created automatically.
  2. Here, type Text will be decided based on the value that you send for that field. i.e, "Sample Message".
  3. If you send { "DOB": "22/11/1990" }, a custom field with label "DOB" of type Date picker will be created, if there exists no custom field with that label already.
How identify call works:
Case 1:

If you send email as UserID in Identify call, under the assumption that email is Unique in your application. i.e, there can't be two users with the same email, we process your request as described below:

  1. We first search in contacts and then in leads to find a matching record with that Email.
  2. If no record is found, we use fs_contact parameter to decide whether to create a Lead or Contact. fs_contact will be false by default - this means, we create a Lead if no records are found in the step1.

Here, fs_contact parameter is used only to decide which record(Lead/Contact) to create. It has nothing to do with searching in Leads and Contacts. Search will happen anyways.

If you send fs_update set to false, we skip the step 1 i.e, we will create a Lead/Contact(based on fs_contact) every time we receive an identify call without searching for matching record.

Case 2:

If you send database ID as UserID in identify call, which is common in applications where Email is not Unique, we process your request as described below:

  1. We will create a Lead/Contact based on fs_contact parameter without searching for matching records on receiving the first identify call.
  2. Later, all the identify and track calls with that UserID will be associated with the same Lead/Contact that we created in the step1.
Help and Support
Send us a message
Chat with us