Get Started with Visier APIs
Everything you need to know to get started with Visier's suite of public APIs.
Overview
Make your first request with Visier APIs. Visier APIs make requests and return data based on your production environment in Visier unless otherwise specified.
Visier reserves the right to, without notice and at its sole discretion, add new elements to API responses. Authorized users who call Visier's APIs must set their JSON parsers to not fail on unknown properties or risk being unable to interpret such API's result set.
Get a Visier account
To use APIs, you must have a Visier account and authenticate. For more information about authenticating, see API Authentication.
Generate your API key and authentication token
To make an API request, you will need an API key and an authentication token. For more information about how to get an API key and request an authentication token, see API Authentication.
Note: If using Postman to send requests, you can request a security token directly in the tool, see Use Postman to Call Visier APIs.
Choose your tool
To use Visier APIs, you need to choose a tool to make your first request. This can be Postman or whichever method you usually use to make HTTP requests. For more information about using Postman for your first request, see Use Postman to Call Visier APIs.
Put your data files in the right place
To send data files using the API, the data files must be in a location that your API application can access. If using Postman, the data files you want to upload must be in Postman's files folder on your local device. For more information, see "Working directory" in Setting up Postman.
Make your first request
To test that you have everything set up correctly, we'll create a request to retrieve all the users in your Visier solution using the /v1/admin/users endpoint.
Replace {vanity_name} with your tenant name. The API key is expected as a header, while the security token is expected as a cookie.
Tip:
To find your vanity name:
- Go to the Global Workspace in Studio, click Settings > Single Sign-On. Then, under Single Sign-On, find your service provider endpoint; for example, https://jupiter.visier.com/VServer/auth. In this example, jupiter is the vanity name.
- As an administrating tenant, go to the Global Workspace in Studio, click Settings > Partner Single Sign-On. Then under Bypass Users (Optional), find your service provider endpoint; for example, https://jupiter.visier.com/VServer/auth. In this example, jupiter is the vanity name.
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/admin/users' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'If everything was set up correctly and the request was successful, you should see a similar response:
{
"users": [
{
"userId": "02393fdc-3b43-9648-b042-a589a781a9d0",
"username": "john@jupiter.com",
"displayName": "Test User 000",
"accountEnabled": true,
"employeeId": "",
"email": "john@jupiter.com",
"lastLogin": {
"timestamp": "1633121685629"
},
},
{
"userId": "72a6c22e-76be-a24a-92f7-7cbbed16fd58",
"username": "richard@jupiter.com",
"displayName": "Integration Test User 002",
"accountEnabled": true,
"employeeId": "",
"email": "richard@jupiter.com"
}
]
}Next steps
Now that you've successfully authenticated and completed your first API request, you can call more Visier APIs!
For detailed reference documentation, see API Reference.
Find available objects to use in an API request
To use a specific object in an API request, you must know the unique identifier of the object. For example:
- To query the pay levels of your employees, you must know the Pay Level dimension's ID.
- To commit a project, you must know the project ID.
- To check an extraction job's status, you must know the dispatching job ID.
Use APIs to retrieve unique identifiers for available objects. For example, retrieve all dimensions to find the ID of Pay Level.
Example: I want to retrieve Customer Support and Dev Operations employees by pay level
Let's say you want to query the Headcount metric filtered by Function employees and grouped by Pay Level. This query involves several objects:
- Metric: Headcount
- Analytic object: Employee
- Dimensions: Function, Pay Level
- Dimension members: Function: Customer Support, Dev Operations and Pay Level: Pay Level.
To make an API request, you need the unique IDs of the metric, analytic object, and dimensions, and the paths of the dimension members.
Find metrics
First, you need to know the unique ID of Headcount. Headcount is a metric, so you'll retrieve all metrics.
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/data/model/metrics' \
-H 'apikey:{api_key}'
-H 'Cookie:VisierASIDToken={security_token}'The response returns all the metrics in your tenant. As shown in the sample response, the id for Headcount is employeeCount.
View sample response
{
"metrics": [
{
"id": "employeeCount",
"displayName": "Headcount",
"description": "The number of employees in the organization.",
"dataStartDate": "1522627200000",
"dataEndDate": "1604102400000",
"analyticObject": "Employee",
"parameters": [],
"category": "REGULAR",
"visibleInApp": true,
"dataType": "Integer"
}
...
]
}Find analytic objects and dimensions
In this example, the IDs are the same as the display names. That is, the unique IDs are Employee, Function, and Pay_Level. However, sometimes IDs are less obvious. If you don't know the IDs, call these endpoints:
- Retrieve analytic objects: GET /v1/data/model/analytic-objects. This returns the subjects, events, and overlays in your tenant, such as Employee.
- Retrieve dimensions: GET /v1/data/model/analytic-objects/Employee/dimensions. This returns the Employee dimensions in your tenant, such as Function and Pay Level.
The responses are similar to the metrics response above. In the response body, find the id field.
Find dimension members
Next, find the dimension members to filter and group by in the API request. Because there are two dimensions, you have to make two requests.
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/data/model/analytic-objects/Employee/dimensions/Function/members' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'The path to Function dimension members are identified in the path field, as shown in the following response.
View sample response
{
"members": [
{
"fullName": "[Function].[All Functions]",
"displayName": "Overall",
"level": 0,
"path": [],
"validityRanges": []
},
{
"fullName": "[Function].[]",
"displayName": "Unknown",
"level": 1,
"path": [
""
],
"validityRanges": []
},
{
"fullName": "[Function].[Customer Support]",
"displayName": "Customer Support",
"level": 1,
"path": [
"Customer Support"
],
"validityRanges": []
},
{
"fullName": "[Function].[Dev Operations]",
"displayName": "Dev Operations",
"level": 1,
"path": [
"Dev Operations"
],
"validityRanges": []
},
{
"fullName": "[Function].[E-Commerce]",
"displayName": "E-Commerce",
"level": 1,
"path": [
"E-Commerce"
],
"validityRanges": []
},
{
"fullName": "[Function].[Finance]",
"displayName": "Finance",
"level": 1,
"path": [
"Finance"
],
"validityRanges": []
},
{
"fullName": "[Function].[HR]",
"displayName": "HR",
"level": 1,
"path": [
"HR"
],
"validityRanges": []
},
{
"fullName": "[Function].[IT]",
"displayName": "IT",
"level": 1,
"path": [
"IT"
],
"validityRanges": []
},
{
"fullName": "[Function].[Marketing]",
"displayName": "Marketing",
"level": 1,
"path": [
"Marketing"
],
"validityRanges": []
},
{
"fullName": "[Function].[Office of CEO]",
"displayName": "Office of CEO",
"level": 1,
"path": [
"Office of CEO"
],
"validityRanges": []
},
{
"fullName": "[Function].[Operations]",
"displayName": "Operations",
"level": 1,
"path": [
"Operations"
],
"validityRanges": []
},
{
"fullName": "[Function].[Product]",
"displayName": "Product",
"level": 1,
"path": [
"Product"
],
"validityRanges": []
},
{
"fullName": "[Function].[Sales]",
"displayName": "Sales",
"level": 1,
"path": [
"Sales"
],
"validityRanges": []
},
{
"fullName": "[Function].[Software Engineering]",
"displayName": "Software Engineering",
"level": 1,
"path": [
"Software Engineering"
],
"validityRanges": []
},
{
"fullName": "[Function].[Software Testing]",
"displayName": "Software Testing",
"level": 1,
"path": [
"Software Testing"
],
"validityRanges": []
}
]
}Because you want to group by all pay levels, not specific pay levels, you can retrieve the dimension information of Pay Level to retrieve the overall level that contains all pay levels.
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/data/model/analytic-objects/Employee/dimensions/Pay_Level' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'The response returns the levels Level 0 and Job Pay Level. In this example, Job Pay Level is the level to query.
View sample response
{
"dimensions": [
{
"id": "Pay_Level",
"displayName": "Job Pay Level",
"description": "The pay level or pay grade of the specified job.",
"levels": [
{
"id": "(All)",
"displayName": "Level 0"
},
{
"id": "Pay_Level",
"displayName": "Job Pay Level",
"depth": 1
}
],
"unknownMember": [
"-1.0"
],
"memberCount": 18,
"visibleInApp": true,
"tags": [
{
"id": "Organization_General",
"displayName": "Organization"
}
]
}
]
}Write the Data Query API request
Finally, put it all together. To craft the Data Query API request, use the IDs, members, and levels to specify the exact conditions of your query.
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/data/query/aggregate' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
-d '{
"query": {
"source": {
"metric": "employeeCount"
},
"timeIntervals": {
"intervalCount": 3,
"dynamicDateFrom": "SOURCE"
},
"filters": [{
"memberSet": {
"dimension": {
"name": "Function",
"qualifyingPath": "Employee"
},
"values": {
"included": [{
"path": ["Dev Operations"]
},{
"path": ["Customer Support"]
}]
}
}
}],
"axes": [
{
"dimensionLevelSelection": {
"dimension": {
"name": "Pay_Level",
"qualifyingPath": "Employee"
},
"levelIds": [
"Pay_Level"
]
}
}
]
}
}'The response returns the Headcount values for each Pay Level.
View sample response
{
"cells": [
{
"value": "0",
"support": "0",
"coordinates": [
0,
0,
0
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
0,
1
]
},
{
"value": "177",
"support": "177",
"coordinates": [
0,
0,
2
]
},
{
"value": "177",
"support": "177",
"coordinates": [
0,
0,
3
]
},
{
"value": "85",
"support": "85",
"coordinates": [
0,
0,
4
]
},
{
"value": "81",
"support": "81",
"coordinates": [
0,
0,
5
]
},
{
"value": "20",
"support": "20",
"coordinates": [
0,
0,
6
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
0,
7
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
0,
8
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
0,
9
]
},
{
"value": "54",
"support": "54",
"coordinates": [
0,
0,
10
]
},
{
"value": "1",
"support": "1",
"coordinates": [
0,
0,
11
]
},
{
"value": "2",
"support": "2",
"coordinates": [
0,
0,
12
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
0,
13
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
0,
14
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
0,
15
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
0,
16
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
1,
0
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
1,
1
]
},
{
"value": "178",
"support": "178",
"coordinates": [
0,
1,
2
]
},
{
"value": "174",
"support": "174",
"coordinates": [
0,
1,
3
]
},
{
"value": "84",
"support": "84",
"coordinates": [
0,
1,
4
]
},
{
"value": "81",
"support": "81",
"coordinates": [
0,
1,
5
]
},
{
"value": "21",
"support": "21",
"coordinates": [
0,
1,
6
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
1,
7
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
1,
8
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
1,
9
]
},
{
"value": "53",
"support": "53",
"coordinates": [
0,
1,
10
]
},
{
"value": "1",
"support": "1",
"coordinates": [
0,
1,
11
]
},
{
"value": "2",
"support": "2",
"coordinates": [
0,
1,
12
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
1,
13
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
1,
14
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
1,
15
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
1,
16
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
2,
0
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
2,
1
]
},
{
"value": "176",
"support": "176",
"coordinates": [
0,
2,
2
]
},
{
"value": "177",
"support": "177",
"coordinates": [
0,
2,
3
]
},
{
"value": "84",
"support": "84",
"coordinates": [
0,
2,
4
]
},
{
"value": "81",
"support": "81",
"coordinates": [
0,
2,
5
]
},
{
"value": "21",
"support": "21",
"coordinates": [
0,
2,
6
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
2,
7
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
2,
8
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
2,
9
]
},
{
"value": "54",
"support": "54",
"coordinates": [
0,
2,
10
]
},
{
"value": "1",
"support": "1",
"coordinates": [
0,
2,
11
]
},
{
"value": "2",
"support": "2",
"coordinates": [
0,
2,
12
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
2,
13
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
2,
14
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
2,
15
]
},
{
"value": "0",
"support": "0",
"coordinates": [
0,
2,
16
]
}
],
"axes": [
{
"dimension": {
"name": "Measures",
"qualifyingPath": ""
},
"positions": [
{
"path": [
"MeasureName"
]
}
]
},
{
"dimension": {
"name": "DateInRange",
"qualifyingPath": ""
},
"positions": [
{
"path": [
"2026-05-01T00:00:00.000Z - [0]"
]
},
{
"path": [
"2026-06-01T00:00:00.000Z - [1]"
]
},
{
"path": [
"2026-06-15T21:51:15.567Z - [2]"
]
}
]
},
{
"dimension": {
"name": "Pay_Level",
"qualifyingPath": ""
},
"positions": [
{
"path": [
"3.0"
]
},
{
"path": [
"4.0"
]
},
{
"path": [
"5.0"
]
},
{
"path": [
"6.0"
]
},
{
"path": [
"7.0"
]
},
{
"path": [
"8.0"
]
},
{
"path": [
"9.0"
]
},
{
"path": [
"10.0"
]
},
{
"path": [
"11.0"
]
},
{
"path": [
"12.0"
]
},
{
"path": [
"13.0"
]
},
{
"path": [
"14.0"
]
},
{
"path": [
"15.0"
]
},
{
"path": [
"19.0"
]
},
{
"path": [
"20.0"
]
},
{
"path": [
"999.0"
]
},
{
"path": [
"-1.0"
]
}
]
}
]
}API references
The following screenshot shows you how to read an endpoint in the Visier API reference.
- APIs and endpoints: A navigation bar to find all publicly available Visier APIs.
- Endpoint name: An action statement about what the API endpoint does.
- Method and URL: The action and URL associated with the API endpoint. Visier APIs use GET, POST, PUT, PATCH, and DELETE methods. The URL shown in the API reference is a shortened version of the full API URL; for example, /v1/data/query/aggregate is short for https://{vanity-name}.api.visier.io/v1/data/query/aggregate. To copy the URL to your clipboard, click the Copy button .
- Request samples: An example of the request body fields and the schema for the fields. To copy the sample to your clipboard, click Copy.
- Headers, parameters, and request body schema: The headers, parameters, and request body fields that you can set in the API request. Each field has a description and data type. To expand a field that contains additional fields, click the Expand button .
- Responses: The potential response to your API call, including all possible success or error response fields.