Suggestions API

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.

cURLPostman

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.

ParametersExample requestAs displayed on the app

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)

<... 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.

ParametersExample requestAs displayed on the app

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)

<... 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.

ParametersExample requestAs displayed on the app

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)

<... 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.

ParametersExample requestAs displayed on the app

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)

<... 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.

ParametersExample requestAs displayed on the app

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)

<... 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.

ParametersExample requestAs displayed on the app

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)

<... 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.

ParametersExample requestAs displayed on the app

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)

<... 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.

ParametersExample requestAs displayed on the app

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.`

<... 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

JSON, bodycURL, with headers and body

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

Request was successfulRequest was partially successfulRequest failed

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.

Suggestions API

Base URL

Rate limits

Request headers

POST /api/v2/bulk/suggestions

Use cases

Resources reference

calendar

lead_details

partner_details

lead_list

partner_list

activity_details

goal_details

code_value

Example request

Example response

Status messages

See also

POST `/api/v2/bulk/suggestions`

`calendar`

`lead_details`

`partner_details`

`lead_list`

`partner_list`

`goal_details`

`code_value`