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
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1alpha/vee/question' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \ 
-d '{
      "question": "What is the headcount by gender in each org?",
      "options": {
        "includeVisual": "true",
        "includeData": "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.

Copy 
{
    "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
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1alpha/vee/question' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \ 
-d '{
    "question": "what about by tenure?",
    "conversationState": {
      "questionState": [
        "Cl1XaGF0IGlzIHRoZ.."
      ]
    },
    "options": {
      "includeVisual": "false",
      "includeData": "false"
    }'

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

Copy 
{
    "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"
          ]
          }
      ]
    }
}

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
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1alpha/vee/feedback' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \ 
-d '{
    "response": {
      "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 Operations & Man was the largest at 165 (16.1% of total) and for E-Commerce & Transgender Man 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": "iVBORw0KGgoAAA.."
          "title": "Trend of Average Hourly Rate by Gender",
          "context": "{\"filters\":[],\"timeFilter\":[\"Apr 2024\"]}"
        }
    },
    "isApproved": "false",
    "description": "I wanted to see more orgs in the answer!"
    }'

The response returns whether the API request was successful.

Copy 
{
    "statusCode": "VEE_API_SUCCESS",
    "statusMsg": "Your feedback for the response has been recorded."
}

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
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1alpha/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?".

Copy 
{
  "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"]
    }
  }..]
}