Skip to content

Suggestions API


Anindita Basu    Sonu Fakiha Feedback

Use the suggestions API to upload up to 50 suggestions at a time. You can make only POST calls to this API.

Base URL

The base URL is https://<client-instance>.lms.getvymo.com/external. Get the value of <client-instance> from Vymo Support.

Rate limits

Requests must be limited to:

  • 10 requests in a minute
  • 50 suggestions in a request

Request headers

All requests must include the following headers:

  • client: Name of the client instance, for example, agency-demo.
  • auth-key: The authorization key for using the API, for example X9xxxXxXxxxXXXxX.

Here is an example header.

curl --location --request POST 'https://client-instance.lms.getvymo.com/external/api-endpoint' \
--header 'Content-Type: application/json' \
--header 'client: client-instance' \
--header 'auth-key: X9xxxXxXxxxXXXxX' \
--data-raw '[
...
]'

the header tab of postman

In this example, you must replace the following bits with real values: api-endpoint, client-instance, and X9xxxXxXxxxXXXxX. Get the values for client and auth-key from Vymo Support. The value of api-endpoint is given in the next section.

POST /api/v2/bulk/suggestions

The API endpoint for a POST request is is /api/v2/bulk/suggestions. All POST requests must contain the parameters listed in the following table.

Parameters marked with an asterisk (*) denote a required parameter.

Parameter Type Description
id * String The ID for the API request. Use it later to make updates to the same request if the request fails.
user_id * String The user ID or employee ID of the person to show the suggestion to. A suggestion can be shown to only one person.
date_of_suggestion * String The date on which to show the suggestion. Must be in the ISO 8601 format of YYYY-MM-DD, and must be within 3 days of the date of the request.
suggestion_type * String One of the following suggestion types: calendar, lead_details, partner_details, lead_list, partner_list, activity_details, goal_details. See Use cases.
suggestion_type_params * Object The parameters of the specified suggestion type. See Resources reference.
display_template_id * String The template ID for the suggestion. The only possible value is league_of_excellence.
display_template_params * array A list of codes and values of all required parameters for the template ID. See the code-value resource.

Use cases

What you want to do Which API resource to use Click-to-action options
Nudge someone to schedule some meetings calendar View the calendar
Suggest someone that they should follow up with a specific lead lead_details Call the lead, see their location on the map, view their details
Suggest someone that they should follow up with a specific partner partner_details Call the partner, see their location on the map, schedule an activity
Nudge someone to follow up with a few leads lead_list View the list
Nudge someone to engage with a few partners partner_list View the list
Nudge someone to do an activity activity_details View the activity details
Nudge someone to complete a goal goal_details View the goal

Resources reference

Parameters marked with an asterisk (*) denote a required parameter.

calendar

Use this resource to show someone their calendar for that week.

No extra parameters are required. Therefore, the suggestion_type_params object is empty.

The parameters that need input from you are highlighted. Do not change the values for the other parameters.

  • Line 1: Request headers (see Request headers)
  • Line 3: A random string that you can use to keep track of this specific API request
  • Line 4: The user ID of the person who should see this suggestion on their device
  • Line 5: A date that's either today or within the next 3 days
  • Line 6: The suggestion type (see the table at POST /api/v2/bulk/suggestions)
  • Lines 12, 16, and 20: The values for the variables used in the subtitle of the suggestion card (see code_value)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<... request headers ...>
{
    "id": "1ab2-3cde4fg56-7hij8-9KL012",
    "user_id": "abc123defgh4",
    "date_of_suggestion": "1857-08-15",
    "suggestion_type": "calendar",
    "suggestion_type_params": {},
    "display_template_id": "league_of_excellence",
    "display_template_params": [
        {
            "code": "Gap",
            "value": "12345.67"
        },
        {
            "code": "Next Slab",
            "value": "Master"
        },
        {
            "code": "CIF Name",
            "value": "Aparichita Vyakti"
        }
        ]
}

calendar suggestion

lead_details

Use this resource to show the the details of a lead to a specific person.

Parameters marked with an asterisk (*) denote a required parameter.

Parameter Type Description
external_id * String The ID of the lead. To get this ID, log in to the web app, go to the leads list, locate the lead, open it, and copy the value from the Vymo Code field.

The parameters that need input from you are highlighted. Do not change the values for the other parameters.

  • Line 1: Request headers (see Request headers)
  • Line 3: A random string that you can use to keep track of this specific API request
  • Line 4: The user ID of the person who should see this suggestion on their device
  • Line 5: A date that's either today or within the next 3 days
  • Line 6: The suggestion type (see the table at POST /api/v2/bulk/suggestions)
  • Line 8: The parameter of the suggestion type at line 6
  • Lines 14, 18, and 22: The values for the variables used in the subtitle of the suggestion card (see code_value)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<... request headers ...>
{ 
   "id": "1ab2-3cde4fg56-7hij8-9KL012",
   "user_id": "abc123defgh4",
   "date_of_suggestion": "1857-08-15",
   "suggestion_type": "lead_details",
   "suggestion_type_params": {
     "external_id": "G292FHEASZ"
   },
    "display_template_id": "league_of_excellence",
    "display_template_params": [
        {
            "code": "Gap",
            "value": "12345.67"
        },
        {
            "code": "Next Slab",
            "value": "Master"
        },
        {
            "code": "CIF Name",
            "value": "Aparichita Vyakti"
        }
        ]
}

lead details suggestion

partner_details

Use this resource to suggest to a specific activity for a specific partner to a specific person, and display the partner details.

Parameters marked with an asterisk (*) denote a required parameter.

Parameter Type Description
external_id * String The ID of the partner. To get this ID, log in to the web app, go to the partners list, locate the partner, open it, and copy the value from the Vymo Code field.
activity_code * String The activity type to be scheduled, for example, meeting or branch visit. To get this code, log in to the web app, go to the module where this activity is defined, click Task configurations, locate the activity, scroll to the Activity Definition section, and copy the value from the code field.

The parameters that need input from you are highlighted. Do not change the values for the other parameters.

  • Line 1: Request headers (see Request headers)
  • Line 3: A random string that you can use to keep track of this specific API request
  • Line 4: The user ID of the person who should see this suggestion on their device
  • Line 5: A date that's either today or within the next 3 days
  • Line 6: The suggestion type (see the table at POST /api/v2/bulk/suggestions)
  • Line 8: The Vymo ID of this partner
  • Line 9: The code of the suggested activity
  • Lines 15, 19, and 23: The values for the variables used in the subtitle of the suggestion card (see code_value)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<... request headers ...>
{
"id": "1ab2-3cde4fg56-7hij8-9KL012",
"user_id": "abc123defgh4",
"date_of_suggestion": "1857-08-15",
"suggestion_type": "partner_details",
"suggestion_type_params": {
    "external_id": "abc1defgh2",
    "activity_code": "bank_branch_visit"
},
"display_template_id": "league_of_excellence",
"display_template_params": [
    {
        "code": "Gap",
        "value": "12345.67"
    },
    {
        "code": "Next Slab",
        "value": "Master"
    },
    {
        "code": "CIF Name",
        "value": "Aparichita Vyakti"
    }
    ]
    }

partner details suggestion

lead_list

Use this resource to display the leads list, filtered by a date range and a state, to a specific person.

Parameters marked with an asterisk (*) denote a required parameter.

Parameter Type Description
module_code * String The code of the leads module. To get this code, log in to the web app, go to the module, click Module Name Settings, and copy the value from the Module Code field.
created_start_date String The start date for the date range to filter the leads list by creation date, in the ISO 8601 format of YYYY-MM-DD. If not specified, the entire lead list is shown. If created_end_date is specified, leads created till that date are shown.
created_end_date String The end date for the date range to filter the leads list by creation date, in the ISO 8601 format of YYYY-MM-DD. If not specified, all leads from the created_start_date onward are shown. If created_start_date is blank, all leads created up to this date is shown.
state_code String The code for the current state of the lead. To get this code, log in to the web app, go to the module, click States configuration, and copy the value from the Code field. If not specified, leads in all states are shown.

The parameters that need input from you are highlighted. Do not change the values for the other parameters.

  • Line 1: Request headers (see Request headers)
  • Line 3: A random string that you can use to keep track of this specific API request
  • Line 4: The user ID of the person who should see this suggestion on their device
  • Line 5: A date that's either today or within the next 3 days
  • Line 6: The suggestion type (see the table at POST /api/v2/bulk/suggestions)
  • Line 8: The code of the module that the leads belong to
  • Lines 9 and 10: The date range within which the leads were created
  • Line 11: The state that the leads are in
  • Lines 17, 21, and 25: The values for the variables used in the subtitle of the suggestion card (see code_value)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<... request headers ...>
{
"id": "1ab2-3cde4fg56-7hij8-9KL012",
"user_id": "abc123defgh4",
"date_of_suggestion": "1761-01-14",
"suggestion_type": "lead_list",
"suggestion_type_params": {
    "module_code": "leads",
     "created_start_date":"1526-04-21",
     "created_end_date":"1556-11-05",
     "state_code":"lead_new"
},
"display_template_id": "league_of_excellence",
"display_template_params": [
  {
        "code": "Gap",
        "value": "12345.67"
    },
    {
        "code": "Next Slab",
        "value": "Master"
    },
    {
        "code": "CIF Name",
        "value": "Aparichita Vyakti"
    }
]
}

leads list suggestion

partner_list

Use this resource to display the partners list, filtered by a date range, to a specific person.

Parameters marked with an asterisk (*) denote a required parameter.

Parameter Type Description
module_code * String The code of the partners module. To get this code, log in to the web app, go to the module, click Module Name Settings, and copy the value from the Module Code field.
created_start_date String The start date for the date range to filter the partners list by creation date, in the ISO 8601 format of YYYY-MM-DD. If not specified, all partners are shown.
created_end_date String The end date for the date range to filter the partners list by creation date, in the ISO 8601 format of YYYY-MM-DD. If not specified, all partners from the created_start_date onward are shown. If created_start_date is blank, all partners created up to this date is shown.

The parameters that need input from you are highlighted. Do not change the values for the other parameters.

  • Line 1: Request headers (see Request headers)
  • Line 3: A random string that you can use to keep track of this specific API request
  • Line 4: The user ID of the person who should see this suggestion on their device
  • Line 5: A date that's either today or within the next 3 days
  • Line 6: The suggestion type (see the table at POST /api/v2/bulk/suggestions)
  • Line 8: The code of the module that the partner belong to
  • Lines 9 and 10: The date range within which the leads were created
  • Lines 16, 20, and 24: The values for the variables used in the subtitle of the suggestion card (see code_value)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<... request headers ...>
{
"id": "1ab2-3cde4fg56-7hij8-9KL012",
"user_id": "abc123defgh4",
"date_of_suggestion": "1761-01-14",
"suggestion_type": "partner_list",
"suggestion_type_params": {
    "module_code": "agents",
     "created_start_date":"1526-04-21",
     "created_end_date":"1556-11-05",
},
"display_template_id": "league_of_excellence",
"display_template_params": [
  {
        "code": "Gap",
        "value": "12345.67"
    },
    {
        "code": "Next Slab",
        "value": "Master"
    },
    {
        "code": "CIF Name",
        "value": "Aparichita Vyakti"
    }
]
}

partners list suggestion

activity_details

Use this resource to show the details of a specific activity.

Parameters marked with an asterisk (*) denote a required parameter.

Parameter Type Description
activity_id * String The ID of the activity. To get this ID, log in to the web app, go to the module where this activity is defined, click Task configurations, locate the activity, and copy the value from the code field in the Activity Definition section.

The parameters that need input from you are highlighted. Do not change the values for the other parameters.

  • Line 1: Request headers (see Request headers)
  • Line 3: A random string that you can use to keep track of this specific API request
  • Line 4: The user ID of the person who should see this suggestion on their device
  • Line 5: A date that's either today or within the next 3 days
  • Line 6: The suggestion type (see the table at POST /api/v2/bulk/suggestions)
  • Line 8: The code of the activity for which the details must be displayed
  • Lines 14, 18, and 22: The values for the variables used in the subtitle of the suggestion card (see code_value)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<... request headers ...>
{
"id": "1ab2-3cde4fg56-7hij8-9KL012",
"user_id": "abc123defgh4",
"date_of_suggestion": "1761-01-14",
"suggestion_type": "activity_details",
"suggestion_type_params": {
    "activity_id": "activity_id"
},
"display_template_id": "league_of_excellence",
"display_template_params": [
  {
        "code": "Gap",
        "value": "12345.67"
    },
    {
        "code": "Next Slab",
        "value": "Master"
    },
    {
        "code": "CIF Name",
        "value": "Aparichita Vyakti"
    }
]
}

activity details suggestion

goal_details

Use this resource to show the target and achievement details of an assigned goal.

Parameters marked with an asterisk (*) denote a required parameter.

Parameter Type Description
goal_code * String The code of the goal. To get this code, log in to the web app, click Customize > Goal definitions > Task configurations, locate the goal, and copy its code.

The parameters that need input from you are highlighted. Do not change the values for the other parameters.

  • Line 1: Request headers (see Request headers)
  • Line 3: A random string that you can use to keep track of this specific API request
  • Line 4: The user ID of the person who should see this suggestion on their device
  • Line 5: A date that's either today or within the next 3 days
  • Line 6: The suggestion type (see the table at POST /api/v2/bulk/suggestions)
  • Line 8: The code of the goal for which the details must be displayed
  • Lines 14, 18, and 22: The values for the variables used in the subtitle of the suggestion card (see code_value)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<... request headers ...>
{
"id": "1ab2-3cde4fg56-7hij8-9KL012",
"user_id": "abc123defgh4",
"date_of_suggestion": "1761-01-14",
"suggestion_type": "goal_details",
"suggestion_type_params": {
    "goal_code": "walk_to_babylon"
},
"display_template_id": "league_of_excellence",
"display_template_params": [
  {
        "code": "Gap",
        "value": "12345.67"
    },
    {
        "code": "Next Slab",
        "value": "Master"
    },
    {
        "code": "CIF Name",
        "value": "Aparichita Vyakti"
    }
]
}

goal details suggestion

code_value

Use this resource to send the values to use in the subtitle of the suggestion card.

Parameters marked with an asterisk (*) denote a required parameter. The parameters here go into the display_template_params object (see the last row in the table at POST call parameters).

Parameter Type Description
code * String The code of the display parameter. The only possible values are Gap, Next Slab, and CIF Name.
value * String The value of code. Used as variables for the subtitle of the suggestion, for example, Your agent { { CIF Name } } is INR { { Gap } } away from the { { Next Slab } } rank.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<... request headers ...>
{
... 
"display_template_params": [
    {
            "code": "Gap",
            "value": "12345.67"
        },
        {
            "code": "Next Slab",
            "value": "Master"
        },
        {
            "code": "CIF Name",
            "value": "Aparichita Vyakti"
        }
        ]
...
}

The title and subtitle of the suggestion

Example request

An example of the partner_details suggestion type

[
    {
    "id": "xxxxxx-99xx9xx-9xxxxxx-99xxxxx",
    "user_id": "is_the_ID_of_the_person_to_display_this_suggestion_to",
    "date_of_suggestion": "1947-08-15",
    "suggestion_type": "is_one_of_the_seven_defined_types",
    "suggestion_type_params": {
            "external_id": "is_the_ID_of_the_partner",
            "activity_code": "is_the_code_of_the_activity"
        },
    "display_template_id": "league_of_excellence",
    "display_template_params": [
        {
            "code": "Gap",
            "value": "12345.67"
        },
        {
            "code": "Next Slab",
            "value": "Master"
        },
        {
            "code": "CIF Name",
            "value": "Aparichita Vyakti"
        }
        ]
    }
]

An example of the partner_details suggestion type

curl --location --request POST 'https://client-instance.lms.getvymo.com/external/api/v2/bulk/suggestions' \
--header 'Content-Type: application/json' \
--header 'client: client-instance' \
--header 'auth-key: X9xxxXxXxxxXXXxX' \
        --data-raw '[
    {
        "id": "xxxxxx-99xx9xx-9xxxxxx-99xxxxx",
        "user_id": "abcd1234efg9",
        "date_of_suggestion": "1947-08-15",
        "suggestion_type": "partner_details",
        "suggestion_type_params": {
            "external_id": "CIF_CODE",
            "activity_code": "branch_visit"
        },
        "display_template_id": "league_of_excellence",
        "display_template_params": [
            {
            "code": "Gap",
            "value": "12345.67"
        },
        {
            "code": "Next Slab",
            "value": "Master"
        },
        {
            "code": "CIF Name",
            "value": "Aparichita Vyakti"
        }
        ]
    }
]'

Example response

For a full list of status codes, see Status messages.

{
    "status": 200
    "response": {
        "api_batch_id": "string",
        "message": "All suggestions processed successfully."
        "total_count": 4
        "success_count": 4
        "failure_count": 0
    }
} 

For a full list of status codes, see Status messages.

{
    "status": 207
    "response": {
        "api_batch_id": "string",
        "message": "Partial Success / failure"
        "total_count": 4
        "success_count": 3
        "failure_count": 1
        }
    "errors":[
    {
        "id":"string",
        "error_message":"message_explains_what_went_wrong"
    }
    ]
} 

For a full list of the messages, see Status messages.

{
    "status": 400
    "error": {
        "code": 400
        "message": "Bad Request"
    }
}

Status messages

Code Message Explanation
200 Success All the suggestions were uploaded.
207 Partial Success / Failure Some of the suggestions couldn't be uploaded because they had errors.
400 Bad Request / Unable to parse JSON The request has some syntax or logical error. See the code examples, and try making the call again.
401 Unauthorized The authorization key is wrong.
412 Validation Error. Precondition failed. The request contained values that weren't valid. Verify that the codes in the request (for example, the ones for modules, activities, or display parameters) are the correct ones.
413 Payload too large. Exceeds the array limit of 500. The request had more than 50 suggestions. Reduce the number of suggestions and try making the API call again.
429 Rate limit reached More than 10 API requests were made within a minute. Wait for a few minutes and try again.
500 Internal Server Error Wait for some time and try again.

See also


Did this page help? No help at allYes, totally!
Back to top