The Freshsales REST API allows for third-party services, like SalesScreen, to retrieve records using the API Key of a specific Freshsales user. Records belonging to the following entities (or modules) can be retrieved:

When using a Freshsales admin user's API Key, we can retrieve records belonging to any user across the organization, with the exception of sales activity records. Freshsales currently only allows for sales activity records associated with the API Key-owner to be retrieved.

When retrieving records belonging to these entities, we utilize their pre-defined views (filters) defined in Freshsales.

Let's look at the Deal entity. It has a collection of views in its Freshsales dashboard. A couple of examples are: My Deals and Won Deals.

When configuring a workflow in SalesScreen to retrieve Deal records, we have to choose one of the Deal views to pull records from. Most of these views are configured with a filter in Freshsales; e.g., the Won Deals view has the following filter:

If we decide to synchronize Deal records from the Won Deals view, we know that we're only going to receive "Default Pipeline" Deals whose stage = "Won". If need be, we can add additional filters in the SalesScreen workflow so that only a subset of these records are actually processed and stored in SalesScreen.

As mentioned in the beginning of this article, we can't pull sales activity records from the API regardless of which Freshsales user is associated with them. We can only retrieve sales activity records associated with the Freshsales user whose API Key we're utilizing to retrieve the records.

Since the Freshsales-SalesScreen integration only allows for one API Key to be provided (the key must belong to a Freshsales admin user) during the set-up, we have to do a work-around in order to synchronize sales activity records for all users to SalesScreen; web hooks.

Freshsales supports the creation of web hook workflows. A web hook can push a notification to an external system, like SalesScreen, whenever a Freshsales record of a specific type is created or modified — regardless of who owns the record. Thus, SalesScreen can receive these notifications and subsequently retrieve the necessary information about the specific record, in order to process and store it.

The following example shows how we can configure a web hook workflow for Appointment records. Notice that Tasks, Appointments and Call logs are the only sales activity types supported.

We choose the workflow action to be "Trigger Webhook".

In the web hook settings view, you only need to provide the Callback URL and check the entity's id field checkbox, under the Content section. Save and activate the workflow.

You can find the Callback URL for a specific SalesScreen workflow by clicking on its Cogwheel > Advanced > Web Hook here:

Manage > Settings > Integrations > Manage Freshsales > Settings > Import Users

NOTE: Since the only sales activity web hook triggers offered today are Task, Appointment and Call logs, SalesScreen can't synchronize other default or custom sales activity types.

NOTE: There is a chance that Freshsales will allow us to retrieve sales activity records associated with any users across the organization, at some point in the future.