Vee API Code Samples

Selection of code samples that demonstrate the use of the Vee API. Copy and edit these code samples to suit your needs.

When using the code samples, remember to replace:

{vanity_name} with your tenant name
{api_key} with your API key
{security_token} with a valid security token

Ask Vee a question

Use this sample request to start a conversation with Vee.

Copy

cURL sample request: Ask Vee what the headcount by gender is in each organization

1
2
3
4
5
6
7
8
9
10
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/vee/question' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
-d '{
    "question": "What is the headcount by gender in each org?",
    "options": {
        "includeVisual": "true"
    }
}'

The response returns Vee's answer to the question and a conversationState object containing a unique ID for the conversation. To ask a follow-up question or continue the conversation with Vee, include the conversationState from the response in your next /question call.

View sample response

Copy

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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
    "conversationState": {
      "questionState": [
        "Cl1XaGF0IGlzIHRoZ.."
      ]
    },
    "statusCode": {
      "statusCode": "VEE_API_SUCCESS",
      "statusMsg": "Successful Vee response for question=What is the headcount by gender in each org?"
    },
    "narrative": "In Apr 2024, the Headcount: for Man & Operations was the largest at 165 (16.1% of total) and for Woman & BlueSphere was the smallest at 1 (0.1% of total).",
    "chartUrl": "http://{vanity_name}.visier.com/hr/prod/appcontainer#/analytics/queryFnChart?fn=Query%28metrics%5BHeadcount%...%5BBreakdown%5D%2C+groupby%5BEmployee.Gender%2C+Employee.Organization%5D%2C+time%5Bthis_month%5D%2C+time_granularity%5Bmonth%5D%29%3B",
    "schema": {
      "metrics": [
        "Headcount"
      ],
      "dimensions": [
        {
          "name": "Organization"
        },
        {
          "name": "Gender"
        },
        {
          "name": "Gender",
          "paths": [
            "Employee"
          ]
        },
        {
          "name": "Organization",
          "paths": [
            "Employee"
          ]
        }
      ]
    },
    "data": {
      "dataJson": "{\"schema\":[..]}",
      "context": "{\"filters\":[],\"timeFilter\":[\"Apr 2024\"]}",
      "visual": {
        "image": "iVBORw0KGgoAAAANS..",  # base64 encoded PNG of rasterized chart
        "title": "Trend of Average Hourly Rate by Gender",
        "context": "{\"filters\":[],\"timeFilter\":[\"Apr 2024\"]}"
      }
}

Use this sample request to ask a follow-up question or continue a conversation with Vee.

Copy

cURL sample request: Ask Vee a follow-up question to the previous question

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/vee/question' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
-d '{
    "question": "what about by tenure?",
    "conversationState": {
      "questionState": [
        "Cl1XaGF0IGlzIHRoZ.."
      ]
    },
    "options": {
      "includeVisual": "false"
    }
}'

The response returns Vee's answer to the question and a new conversationState object containing a unique ID for the continued conversation.

View sample response

Copy

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
29
30
{
    "conversationState": {
      "questionState": [
        "Cl1XaGF0IGlzIHRoZ..",
        "ZXIsRW1wbG95ZWqoi.."
      ]
    },
    "statusCode": {
      "statusCode": "VEE_API_SUCCESS",
      "statusMsg": "Successful Vee response for question=what about by tenure?"
    },
    "narrative": "In Apr 2024, the Headcount by Tenure Range were: 0 to 1 yr was 205 (20% of total), 1 to 2 yrs was 121 (11.8% of total) and 2 to 3 yrs was 91 (8.86% of total)and 4 more.",
    "chartUrl": "http://{vanity_name}.visier.com/hr/prod/appcontainer#/analytics/queryFnChart?fn=Query%28metrics%5BHeadcount%...%5BBreakdown%5D%2C+groupby%5BEmployee.Tenure_Range%5D%2C+time%5Bthis_month%5D%2C+time_granularity%5Bmonth%5D%29%3B",
    "schema": {
      "metrics": [
        "Headcount"
      ],
      "dimensions": [
        {
          "name": "Tenure Range"
        },
        {
          "name": "Tenure Range",
          "paths": [
            "Employee"
          ]
          }
      ]
    }
}

Use this sample request to ask a question and request for relevant documents such as analyses and reports.

Copy

cURL sample request: Ask a question and request relevant documents

1
2
3
4
5
6
7
8
9
10
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/vee/question' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-d '{
    "question": "What is the turnover rate?",
    "options": {
        "includeRelatedAnalyses": true,
        "includeRelatedReports": true
    }
}'

The response returns Vee's answer to the question and a relatedDocuments object containing the details of the related document such as the unique ID, title, description, and URL to view the document in Visier, or the click-through link for Embedded Partners if configured.

View sample response

Copy

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
29
30
31
32
33
34
35
36
{
    "conversationState": {
        "questionState": [
            "CILdTY...UsdA.."
        ]
    },
    "statusCode": {
        "statusCode": "VEE_API_SUCCESS",
        "statusMsg": "Successful Vee response for question=What is the turnover rate?"
    },
    "narrative": "The most recent data available shows a Turnover Rate of 0.36% in September 2025.",
    "chartUrl": "https://.../appcontainer#/analytics/queryFnChart?fn=hHmWRQ5-NrNrNAd8IuBdsPyMVD5hNYmau-4lgN_1xVtTURlYPe5j6TUiNSrsivUc2ZmBPi1FXiYsARc9mOKDAfSGi-xNXQCVN4BjGkg7myC2b53qN2gH9MI_jcvxMGRKi58gHmU5gYUl1SRRSY21DA..",
    "schema": {
        "metrics": [
            "Turnover Rate"
        ]
    },
    "relatedDocuments": {
        "analyses": [
            {
                "id": "da5bb4a1-8d29-4eab-8137-32713841a3a2",
                "title": "How do new hire turnover and overall turnover compare?",
                "description": "Analyze trends in new hire and overall turnover to improve future plans",
                "url": "https://.../hr/auth/shared/tDwcg0-kkadzy7YohHqq1XTNTTprdbLzwHNS6FXl1hVAkLEtrHLcFxV1l25WHjDWwFVpMqyuZFq1oQaJzvTf5dFNo-_ae9a7gUdKoUQzIO9wOqy0eCYCeMMa4u2a3wY84zKFQKr81W6t5eQbx5-rFvL2FtJXibIwt4jQbO_HYlPM6P3XTCq0M-c7EZmIa8g5Ra7XdDMaGO1FahUSzH1t6yW2Db1uj8N4ToEMcToRpsU.?a=b"
            }
        ],
        "reports": [
            {
                "id": "728c2171-e894-40f9-bbb9-635a673e9e63",
                "title": "Employee Production Report Template",
                "description": "Review employee production and related attributes.",
                "url": "https://.../hr/auth/shared/vF6NcJLAk-XusZaCR16xQ7ozgUb6AXpK3tbROMgumWEGelnn10cxsNEWwjl0IVviGlYITX3G-E42sLtn4VdYGHOVlBOUUWbtyeIvIwxsU8QTgM1MnrY5zy9ebiUPH7ycX0ptWgS-elm9CvNlV-pBg9ZfQbDDDO7-szAsv1OEQo7sLRhcglytNVD7DXnbRZvBq6Q15_SpIvC_uAkjzv1IFcigmdVa_gLnF91dr6BqRFc.?a=b"
            }
        ]
    }
}

Submit Vee feedback

Use this sample request to submit feedback about Vee's answer to a question. The request body must include the answer's response object, a rating of Vee's answer, and a description of how Vee should have answered the question or how Vee can improve the answer.

Copy

cURL sample request: Submit feedback that you want Vee to return more organizations in the answer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/vee/feedback' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \ 
-H 'Content-Type: application/json' \
-d '{
    "conversation": {
        "conversationState": {
            "questionState": [
                  "Cl1XaGF0IGlzIHRoZ.."
            ]
        },
    },
    "isApproved": "false",
    "description": "I wanted to see more orgs in the answer!"
}'

The response returns whether the API request was successful.

View sample response

Copy

1
2
3
4
{
    "statusCode": "VEE_API_SUCCESS",
    "statusMsg": "Your feedback for the response has been recorded."
}

Retrieve a list of Vee question categories

Use this sample request to get a list of categories for the Vee sample questions displayed in the conversation interface.

Copy

cURL sample request: Retrieve a list of Vee question categories

1
2
3
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/vee/sample-question-categories' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns a list of categories, such as Comparisons.

View sample response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "categories": [{
    "categoryId": "e12cc3a2-e7ba-47de-a7e9-84f49a866d54",
    "basicInformation": {
      "displayName": "Adjust answer",
      "description": ""
    },
    "categoryIcon": {
      "base64Image": "iVBORw0...u003d",
      "backgroundColor": "#dcd1f0"
    },
  }, {
    "categoryId": "10df0b34-e937-4685-ad86-2a53be5ec13f",
    "basicInformation": {
      "displayName": "Comparisons",
      "description": ""
    },
    "categoryIcon": {
      "base64Image": "iVBORw0...u003d",
      "backgroundColor": "#dbf1d1"
    }
  }]
}

Retrieve a Vee question category's details

Use this sample response to get the details of a specific Vee sample question category.

Copy

cURL sample request: Retrieve a Vee question category’s details

1
2
3
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/vee/sample-question-categories/10df0b34-e937-4685-ad86-2a53be5ec13f' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the details of a specific Vee sample question category.

View sample response

Copy

1
2
3
4
5
6
7
8
9
10
11
{
  "categoryId": "10df0b34-e937-4685-ad86-2a53be5ec13f",
  "basicInformation": {
    "displayName": "Comparisons",
    "description": ""
  },
  "categoryIcon": {
    "base64Image": "iVBORw0...u003d",
    "backgroundColor": "#dbf1d1"
  }
}

Retrieve a list of sample questions to ask Vee

Use this sample request to get a list of sample questions to help your users start using Vee.

Copy

cURL sample request: Retrieve a list of sample questions

1
2
3
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/vee/sample-questions' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns a list of questions, such as What is the turnover rate?.

View sample response

Copy

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
29
30
31
32
33
{
  "questions": [{
    "question": "What is the turnover rate?",
    "metadata": {
      "categories": ["metricQuestion"]
    }
  }, {
    "question": "How many employees do we have in the US?",
    "metadata": {
      "categories": ["metricQuestion"]
    }
  }, {
    "question": "What is the relationship of span of control and turnover rate for managers?",
    "metadata": {
      "categories": ["craftVisual"]
    }
  }, {
    "question": "Is the turnover rate consistent with industry trends?",
    "metadata": {
      "categories": ["comparison"]
    }
  }, {
    "question": "What is the tenure for employees who left?",
    "metadata": {
      "categories": ["employeeEvent"]
    }
  }, {
    "question": "How has this changed over time?",
    "metadata": {
      "categories": ["adjustAnswer"]
    }
  }..]
}