Freshsales

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.

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:

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

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

   EXPAND ↓

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

   EXPAND ↓

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:

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

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.