CRM Recommendation Rules

Recommendation rules play a vital role in defining the assets that are recommended to your sales reps. The process starts with an administrator defining rules for specific object relations and tags. When circumstances correspond to these rules, the correct assets are presented as recommendations.

By creating your own recommendation rules, you can use them to obtain a custom set of Showpad assets and present them as you wish in Salesforce.

Key Features

• Create personalized recommendation rules
• Retrieve the details of your recommendation rules by specifying a Salesforce or tag ID(s)
• Update an existing recommendation rule
• Delete an existing recommendation rule

Prerequisites

• A Salesforce instance integrated with Showpad
• Admin privileges on Showpad and Salesforce
• Ultimate subscription to Showpad

How Rules Work

Recommendation rules by linking the tags of your Showpad assets with the fields defined in Salesforce. When the conditions in your rule are met, your Showpad content with the designated tag is displayed as recommendations.

Example

You can define a rule that specifies when a sales rep is working with a Lead in the Energy sector of the Industry market in Salesforce, assets with the Power2023 tag in Showpad are recommended.

To create this rule, you would define the following CRM conditions and Showpad tag criteria:

"conditions": [
     {
        //CRM Info
        "items": [
           {
            "fieldName": "Industry",
            "objectName": "Lead",
            "operator": "equals",
            "value": "Energy"
            }
        ]
     }
    ],
    //Showpad Tag Info
    "tags": {
        "all": ["ba16a6afc2d4247862c9986aa09772fd"]
        //all assets with the ID for Power2023
    }

Managing Rules

You can manage your Recommendation Rules for Salesforce in the Showpad Online Platform. This Help Center article provides all the details.

Requests Overview

Base Endpoint

Every request must be prefixed with the base endpoint: https://{{subdomain}}.api.showpad.com

CRM Recommendation Rules use Showpad API v4. Therefore, your calls will use the base endpoint + the API version + the purpose of the call:

https://{{subdomain}}.api.showpad.com/v4/crm/recommendations/rules

CRM Instance ID

The crmInstanceId is used to identify the Salesforce instance you've integrated with Showpad. You can get your instance identifier by viewing the Details in the Integrations > CRM section of the Showpad Online Platform:

Request Body

The database definitions described in the table below are used to specify the conditions that must be met within your CRM for the following request types:

• Create Rule
• Update Rule

Item	Data Type	Description
objectName	string	The main object type.
childObjectName	string	optional A subordinate of the main object.
fieldName	string	A specific field within the main or child object.
operator	string	How the fieldName and the value are evaluated. Available values: equals equalnot contains containsnot startswith startswithnot endswith endswithnot
value	string	This specific information you want to work with.

Tags

You can refine your requests by specifying Showpad tags to specify that the rule only applies to assets with the designated tag(s).

Three options are available for defining how to match assets with the tags:

• all - An asset must contain every one of the tags listed.

• any - An asset must contain at least one of the tags listed.

• none - An asset must not contain any of the tags listed.

Create Rule

You can create a recommendation rule with the following request:

Method	Endpoint	Description
Post	/v4/crm/recommendations/rules	Creates a CRM recommendation rule.

Example

This rule specifies that when a sales rep is working with an Opportunity in the Chew Toys sector of the Dog Toys market in your CRM, assets with the Big Bone tag in Showpad are recommended.

curl --request POST  \
--url 'https://{{subdomain}}.api.showpad.com/v4/crm/recommendations/rules' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ myAPItoken }}' \
--data '{
    "crmInstanceId": "myCRMInstanceId",
    "conditions": [
        {
            "items": [
                {
                    "objectName": "opportunity",
                    "childObjectName": "dogToys",
                    "fieldName": "chewToys",
                    "operator": "equals",
                    "value": "bigBone"
                }
            ]
        }
    ],
    "tags": {
        "all": ["big_bone"],
        "any": [],
        "none": []
    }
}'

Response

201: Created

{
    "id": "01H9TERHN6Z0AHENMV14K5YKPR",
    "crmInstanceId": "myCRMInstanceId",
    "conditions": [
        {
            "items": [
                {
                    "objectName": "opportunity",
                    "childObjectName": "dogToys",
                    "fieldName": "chewToys",
                    "operator": "equals",
                    "value": "bigBone"
                }
            ]
        }
    ],
    "tags": {
        "all": ["big_bone"],
        "any": [],
        "none": []
    },
    "createdAt": "2023-09-08T13:12:36.000Z",
    "updatedAt": "2023-09-08T13:12:36.000Z"
}

Retrieve Rules

Specific CRM Instance

You can retrieve a list of all of the recommendation rules for your Salesforce instance by specifying your CRM instance ID with a call to the following endpoint:

Method	Endpoint	Description
GET	/v4/crm/recommendations/rules	Returns all CRM recommendation rules for the specified CRM instance.

Example

curl
--url 'https://{{subdomain}}.api.showpad.com/v4/crm/recommendations/rules?crmInstanceId=5708b5480060c466a05c98522472df32' \
--header 'Authorization: Bearer {{ myAPIToken }}'

Response

{
  "count": 2,
  "items": [
    {
      "id": "01H9FK4CRME24PVVNM1JR8T1ZE",
      "crmInstanceId": "5708b5480060c466a05c98522472df32",
      "conditions": [
        {
          "items": [
            {
              "objectName": "opportunity",
              "childObjectName": "dogToys",
              "fieldName": "chewToys",
              "value": "bigBone",
              "operator": "equals"
            }
          ]
        }
      ],
      "tags": {
        "all": [],
        "any": ["951aca1a3576e1d1488f29e74756ee60"],
        "none": []
      },
      "createdAt": "2023-09-04T07:57:20.000Z",
      "updatedAt": "2023-09-05T07:29:41.000Z"
    },
    {
      "id": "01H9QWEKSPTN1A3Z2EHJM249SC",
      "crmInstanceId": "5708b5480060c466a05c98522472df32",
      "conditions": [
        {
          "items": [
            {
              "objectName": "opportunity",
              "childObjectName": "clothing",
              "fieldName": "dogShirt",
              "operator": "equals",
              "value": "goodBoy"
            }
          ]
        }
      ],
      "tags": {
        "all": [],
        "any": ["951aca1a3576e1d1488f29e74756ee60"],
        "none": []
      },
      "createdAt": "2023-09-07T13:14:07.000Z",
      "updatedAt": "2023-09-07T13:14:07.000Z"
    }
  ]
}

Specific Rule ID

You can retrieve a recommendation rule by specifying its identifier with a call to the following endpoint:

Method	Endpoint	Description
GET	/v4/crm/recommendations/rules/{ruleID}	Returns the recommendation rule for the specified identifier.

Example

curl --request GET \
--url 'https://{{subdomain}}.api.showpad.com/v4/crm/recommendations/rules/01H9TERHN6Z0AHENMV14K5YKPR' \
--header 'Authorization: Bearer {{ myAPIToken }}'

Response

{
  "id": "01H9TERHN6Z0AHENMV14K5YKPR", //rule id
  "crmInstanceId": "5708b5480060c466a05c98522472df32",
  "conditions": [
    {
      "items": [
        {
          "objectName": "lead",
          "childObjectName": "dog_food",
          "fieldName": "k9",
          "operator": "contains",
          "value": "kibble"
        }
      ]
    }
  ],
  "tags": {
    "all": ["beef"],
    "any": [],
    "none": []
  },
  "createdAt": "2023-09-08T13:12:36.000Z",
  "updatedAt": "2023-09-08T13:12:36.000Z"
}

Update Rule

You can update a recommendation rule by specifying the IDs for the rule and Salesforce instance with a call to the following endpoint:

Method	Endpoint	Description
PUT	/v4/crm/recommendations/rules/{ruleId}	Returns all CRM recommendation rules for the specified CRM instance.

Example

curl --request PUT \
--url 'https://{{subdomain}}.api.showpad.com/v4/crm/recommendations/rules/01H9TERHN6Z0AHENMV14K5YKPR' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ myAPIToken }}' \
--data '{
    "id": "01H9TERHN6Z0AHENMV14K5YKPR", //rule id
    "crmInstanceId": "5708b5480060c466a05c98522472df32",
    "conditions": [
        {
            "items": [
                {
                    "objectName": "lead",
                    "childObjectName": "dog_food",
                    "fieldName": "k9",
                    "operator": "contains",
                    "value": "kibble"
                }
            ]
        }
    ],
    "tags": {
        "all": ["chicken"],
        "any": [],
        "none": []
    },
    "createdAt": "2023-09-08T13:12:36.000Z",
    "updatedAt": "2023-09-08T13:12:36.000Z"
}

Response

200: OK

{
    "id": "01H9TERHN6Z0AHENMV14K5YKPR",
    "crmInstanceId": "myCRMInstanceId",
    "conditions": [
        {
            "items": [
                {
                    "objectName": "lead",
                    "childObjectName": "dog_food",
                    "fieldName": "k9",
                    "operator": "contains",
                    "value": "kibble"
                }
            ]
        }
    ],
    "tags": {
        "all": ["chicken"],
        "any": [],
        "none": []
    },
    "createdAt": "2023-09-08T13:12:36.000Z",
    "updatedAt": "2023-09-08T13:18:26.000Z"
}

Delete Rule

You can delete a recommendation rule by specifying the IDs for the rule and Salesforce instance with a call to the following endpoint:

Method	Endpoint	Description
DELETE	/v4/crm/recommendations/rules/{ruleId}	Permanently removes the recommendation rule from the specified CRM instance.

Example

curl --request DELETE \
--url 'https://{{subdomain}}.api.showpad.com/v4/crm/recommendations/rules/01H9TERHN6Z0AHENMV14K5YKPR' \
--header 'Authorization: Bearer {{ myAPIToken }}'