Concepts API Code Samples

Selection of code samples that demonstrate the use of the Concepts 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

These code samples may not include all available parameters and request body fields for each endpoint. For the endpoint's full request schema, see "Concepts V2" in API Reference.

Retrieve a list of concepts by analytic object

Use this sample request to retrieve all the concepts for a specific analytic object. Optionally, specify the query parameters type to only retrieve a specific concept type and with to retrieve more detailed information about each concept. Default is to return basic information.

Copy

cURL sample request: Retrieve a list of all concepts for Employee in tenant WFF_j1r~c7o

1
2
3
4
5
curl -X GET --url 'https://{vanity_name}.api.visier.io/v2alpha/data/model/analytic-objects/Employee/concepts' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'TargetTenantID:WFF_j1r~c7o' \
-H 'ProjectID:8a0fd408-cee9-49ee-9a1d-857b43b7fae9'

The response returns the details of all concepts for the analytic object, including object names, concept types, and descriptions.

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
"concepts": [
    {
      "executionContext": {
        "tenantCode": "WFF_j1r~c7o",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "concept": {
        "objectName": "customIsEmployee",
        "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
        "basicInformation": {
          "displayName": "Custom is-Employee",
          "description": "Some customized version of Workers who are employees."
        },
        "details": {
          "memberSelection": {
            "analyticObjectFilterList": {
              "analyticObjectFilters": [
                {
                  "analyticObjectName": "Employee",
                  "filters": [
                    {
                      "dimensionName": "Contract_Type",
                      "memberSelections": [
                        {
                          "namePath": [
                            "Seasonal"
                          ]
                        },
                        {
                          "namePath": [
                            "Temporary"
                          ]
                        },
                        {
                          "namePath": [
                            "True"
                          ]
                        },
                        {
                          "namePath": [
                            "Non-guaranteed Hours"
                          ]
                        }
                      ],
                      "isExcluded": true
                    }
                  ]
                }
              ]
            },
            "tagList": {
              "tags": [
                {
                  "objectName": "Organization_General"
                }
              ]
            },
            "visibleInAnalytics": true,
            "includeWithVee": true
          }
        },
        "versionInformation": {
            "versionType": "Tenant",
            "edited": "2023-10-01T12:00:00Z",
            "editor": "John_Doe"
        }
      }
    }
  ]
}'

Retrieve a list of concepts

Use this sample request to retrieve all the concepts in the specified project. To retrieve concepts from production, omit ProjectID.

Copy

cURL sample request: Retrieve a list of all concepts from project 8a0fd408-cee9-49ee-9a1d-857b43b7fae9 in tenant WFF_j1r~c7o

1
2
3
4
5
curl -X GET --url 'https://{vanity_name}.api.visier.io/v2alpha/data/model/concepts' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'TargetTenantID:WFF_j1r~c7o' \
-H 'ProjectID:8a0fd408-cee9-49ee-9a1d-857b43b7fae9'

Optionally, specify type to only retrieve a specific concept type.

Copy

cURL sample request: Retrieve a list of all selection concepts

1
2
3
curl -X GET --url 'https://{vanity_name}.api.visier.io/v2alpha/data/model/concepts?type=selection' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

Optionally, specify with to retrieve more detailed information about each concept. Default is to return basic information.

Copy

cURL sample request: Retrieve a list of all selection concepts with detailed information

1
2
3
curl -X GET --url 'https://{vanity_name}.api.visier.io/v2alpha/data/model/concepts?type=selection&with=details' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the details of all concepts for the analytic object, including object names, concept types, and descriptions.

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
"concepts": [
    {
      "executionContext": {
        "tenantCode": "WFF_j1r~c7o",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "concept": {
        "objectName": "customIsEmployee",
        "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
        "basicInformation": {
          "displayName": "Custom is-Employee",
          "description": "Some customized version of Workers who are employees."
        },
        "details": {
          "memberSelection": {
            "analyticObjectFilterList": {
              "analyticObjectFilters": [
                {
                  "analyticObjectName": "Employee",
                  "filters": [
                    {
                      "dimensionName": "Contract_Type",
                      "memberSelections": [
                        {
                          "namePath": [
                            "Seasonal"
                          ]
                        },
                        {
                          "namePath": [
                            "Temporary"
                          ]
                        },
                        {
                          "namePath": [
                            "True"
                          ]
                        },
                        {
                          "namePath": [
                            "Non-guaranteed Hours"
                          ]
                        }
                      ],
                      "isExcluded": true
                    }
                  ]
                }
              ]
            },
            "tagList": {
              "tags": [
                {
                  "objectName": "Organization_General"
                }
              ]
            },
            "visibleInAnalytics": true,
            "includeWithVee": true
          }
        },
        "versionInformation": {
            "versionType": "Tenant",
            "edited": "2023-10-01T12:00:00Z",
            "editor": "John_Doe"
        }
      }
    }
  ]
}'

Retrieve a concept's details

Use this sample request to retrieve the details of a specific concept.

Copy

cURL sample request: Retrieve the details of customIsEmployeein tenant WFF_j1r~c7o

1
2
3
4
5
curl -X GET --url 'https://{vanity_name}.api.visier.io/v2alpha/data/model/concepts/customIsEmployee' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'TargetTenantID:WFF_j1r~c7o' \
-H 'ProjectID:8a0fd408-cee9-49ee-9a1d-857b43b7fae9'

The response returns the details of the requested concept, including its object name, concept type, and description.

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
"concepts": [
    {
      "executionContext": {
        "tenantCode": "WFF_j1r~c7o",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "concept": {
        "objectName": "customIsEmployee",
        "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
        "basicInformation": {
          "displayName": "Custom is-Employee",
          "description": "Some customized version of Workers who are employees."
        },
        "details": {
          "memberSelection": {
            "analyticObjectFilterList": {
              "analyticObjectFilters": [
                {
                  "analyticObjectName": "Employee",
                  "filters": [
                    {
                      "dimensionName": "Contract_Type",
                      "memberSelections": [
                        {
                          "namePath": [
                            "Seasonal"
                          ]
                        },
                        {
                          "namePath": [
                            "Temporary"
                          ]
                        },
                        {
                          "namePath": [
                            "True"
                          ]
                        },
                        {
                          "namePath": [
                            "Non-guaranteed Hours"
                          ]
                        }
                      ],
                      "isExcluded": true
                    }
                  ]
                }
              ]
            },
            "tagList": {
              "tags": [
                {
                  "objectName": "Organization_General"
                }
              ]
            },
            "visibleInAnalytics": true,
            "includeWithVee": true
          }
        },
        "versionInformation": {
            "versionType": "Tenant",
            "edited": "2023-10-01T12:00:00Z",
            "editor": "John_Doe"
        }
      }
    }
  ]
}'

Create concepts

Use this sample request to create a new concept. To create new concepts that publish directly to production, omit projectId.

Copy

cURL sample request: Create a new concept

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
curl -X POST --url 'https://{vanity_name}.api.visier.io/v2alpha/data/model/concepts' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
-d '{
    "concepts": [{
      "executionContext": {
        "tenantCode": "WFF_j1r",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "concept": {
        "objectName": "customIsEmployee",
        "basicInformation": {
          "displayName": "Custom is-Employee",
          "description": "Some customized version of Workers who are employees."
        },
        "details": {
          "memberSelection": {
            "analyticObjectFilterList": {
              "analyticObjectFilters": [
                {
                  "analyticObjectName": "Employee",
                  "filters": [
                    {
                      "dimensionName": "Contract_Type",
                      "memberSelections": [
                        {
                          "namePath": [
                            "Seasonal"
                          ]
                        },
                        {
                          "namePath": [
                            "Temporary"
                          ]
                        },
                        {
                          "namePath": [
                            "True"
                          ]
                        },
                        {
                          "namePath": [
                            "Non-guaranteed Hours"
                          ]
                        }
                      ],
                      "isExcluded": true
                    }
                  ]
                }
              ]
            },
            "tagList": {
              "tags": [
                {
                  "objectName": "Organization_General"
                }
              ]
            },
            "visibleInAnalytics": true,
            "includeWithVee": true
          }
        }
      }
    }
  ]
}'

The response returns whether the concepts were successfully created.

View sample response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "successes": [
    {
      "executionContext": {
        "tenantCode": "WFF_j1r",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "objectName": "customIsEmployee",
      "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
      "displayName": "Custom is-Employee"
    }
  ],
  "failures": []
}

Update concepts

Use this sample request to update an existing concept. The request body is similar to POST, but requires the concept's UUID.

Copy

cURL sample request: Update customIsEmployee

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v2alpha/data/model/concepts' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
-d '{
    "concepts": [{
      "executionContext": {
        "tenantCode": "WFF_j1r",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "concept": {
        "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
        "objectName": "customIsEmployee",
        "basicInformation": {
          "displayName": "Modified Custom is-Employee",
          "description": "Some customized version of Workers who are employees."
        },
        "details": {
          "memberSelection": {
            "analyticObjectFilterList": {
              "analyticObjectFilters": [
                {
                  "analyticObjectName": "Employee",
                  "filters": [
                    {
                      "dimensionName": "Contract_Type",
                      "memberSelections": [
                        {
                          "namePath": [
                            "Seasonal"
                          ]
                        },
                        {
                          "namePath": [
                            "Temporary"
                          ]
                        },
                        {
                          "namePath": [
                            "Non-guaranteed Hours"
                          ]
                        }
                      ],
                      "isExcluded": true
                    }
                  ]
                }
              ]
            },
            "tagList": {
              "tags": [
                {
                  "objectName": "Organization_General"
                }
              ]
            },
            "visibleInAnalytics": true,
            "includeWithVee": false
          }
        }
      }
    }
  ]
}'

The response returns whether the concepts were successfully updated.

View sample response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "successes": [
    {
      "executionContext": {
        "tenantCode": "WFF_j1r",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "objectName": "customIsEmployee",
      "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
      "displayName": "Custom is-Employee"
    }
  ],
  "failures": []
}

Partially update concepts

Use this sample request to patch an existing concept.

Copy

cURL sample request: Update the display name and description of concept 45aad864-1df1-428e-9c1e-006eb1803301

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
curl -X PATCH --url 'https://{vanity_name}.api.visier.io/v2alpha/data/model/concepts' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
-d '{
    "concepts": [{
      "executionContext": {
        "tenantCode": "WFF_j1r",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "concept": {
        "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
        "basicInformation": {
          "displayName": "Employee selection",
          "description": "Official definition of what constitutes an employee in the organization."
        }
      }
    }
  ]
}'

The response returns whether the concepts were successfully updated.

View sample response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "successes": [
    {
      "executionContext": {
        "tenantCode": "WFF_j1r",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "objectName": "customIsEmployee",
      "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
      "displayName": "Custom is-Employee"
    }
  ],
  "failures": []
}

Delete concepts

Use this sample request to delete an existing concept. To delete the concept and publish it to production immediately, omit projectId.

Copy

cURL sample request: Delete concept 45aad864-1df1-428e-9c1e-006eb1803301

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl -X DELETE --url 'https://{vanity_name}.api.visier.io/v2alpha/data/model/concepts' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
-d '{
  "concepts": [
    {
      "executionContext": {
        "tenantCode": "WFF_j1r",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "concept": {
        "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
      }
    }
  ]
}'

The response returns whether the concepts were successfully deleted.

View sample response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "successes": [
    {
      "executionContext": {
        "tenantCode": "WFF_j1r",
        "projectId": "8a0fd408-cee9-49ee-9a1d-857b43b7fae9"
      },
      "objectName": "customIsEmployee",
      "uuid": "45aad864-1df1-428e-9c1e-006eb1803301",
      "displayName": "Custom is-Employee"
    }
  ],
  "failures": []
}