Planning Data Load API Code Samples

Selection of code samples that demonstrate the use of the Planning Data Load 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 "Planning Data Load" in API Reference.

Retrieve a list of plans

Use this sample request to retrieve all your plans.

Copy

Retrieve a list of plans

1
2
3
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1alpha/planning/model/plans' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

Use this sample request to retrieve plans with the following attributes:

Display name: Test
Plan status: In Progress
Created on or after: 2024-11-13
Created on or before: 2024-11-13

Copy

Retrieve all plans with the display name Test, plan status In Progress, and created on 2024-11-13

1
2
3
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1alpha/planning/model/plans?displayName=Test&planStatus=IN_PROGRESS&createdStart=2024-11-13&createdEnd=2024-11-13' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns a list of plans and their plan IDs.

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
{
    "plans": [
      {
        "uuid": "93668189-8734-4cd8-b340-e9bb9f4a38f0",
        "displayName":"“Workforce Plan FY 2025",
        "modelId": "WorkforcePlanModel",
        "scenarios": [
          {
            "uuid": "7af12ba3-6e7a-453e-924e-0585ba22b8c6",
            "displayName": "Default"
          }
        ],
        "currencyCode": "USD"
      },
      {
        "uuid": "b9759dbb-855f-4229-a7a3-937c14a88ffc",
        "displayName": "Headcount FY2024",
        "modelId": "Headcount_And_Cost_Planning",
        "scenarios": [
          {
            "uuid": "a7f039c7-1c44-48cd-aa57-89c93d445bf3",
            "displayName": "Default"
          }
        ],
        "currencyCode": "USD"
      },
      {
        "uuid": "31468b5e-41e0-4fdc-86ae-39a94dc5e337",
        "displayName": "Headcount Plan FY2023",
        "modelId": "Headcount_And_Cost_Planning",
        "scenarios": [
          {
            "uuid": "a7f039c7-1c44-48cd-aa57-89c93d445bf3",
            "displayName": "Default"
          }
        ],
        "currencyCode": "USD"
      },
      {
        "uuid": "04120831-7cb5-461a-affc-3f50816300e3",
        "displayName": "Workforce and Cost Plan for FY 2025",
        "modelId": "Headcount_And_Cost_Planning",
        "scenarios": [
          {
            "uuid": "a7f039c7-1c44-48cd-aa57-89c93d445bf3",
            "displayName": "Default"
          }
        ],
        "currencyCode": "USD"
      },
    ],
    "page": 1
}

Retrieve a plan's details

Use this sample request to retrieve a specific plan and its schema.

Copy

Retrieve plan 93668189-8734-4cd8-b340-e9bb9f4a38f0 with its schema

1
2
3
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1alpha/planning/model/plans/93668189-8734-4cd8-b340-e9bb9f4a38f0?withSchema=true' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns the plan's scenarios, currency, plan items, and segments.

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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
{
    "plan": {
      "uuid": "93668189-8734-4cd8-b340-e9bb9f4a38f0",
      "displayName": "Workforce Plan FY 2025",
      "modelId": "WorkforcePlanModel",
      "scenarios": [
        {
          "uuid": "7af12ba3-6e7a-453e-924e-0585ba22b8c6",
          "displayName": "Default"
        }
      ],
      "currencyCode": "USD"
    },
    "schema": {
      "planItems": [
        {
          "id": "Involuntary Turnover",
          "displayName": "Annual involuntary turnover rate",
                  "dataType": "rate"
        },
        {
          "id": "Voluntary Turnover",
          "displayName": "Annual resignation rate",
                  "dataType": "rate"
        },
        {
          "id": "Base Pay Change Rate",
          "displayName": "Change in base pay",
                  "dataType": "rate"
        }
      ],
      "timePeriods": [
        {
          "date": "2024-01-01",
          "displayName": "Jan 2024"
        },
        {
          "date": "2024-02-01",
          "displayName": "Feb 2024"
        },
        {
          "date": "2024-03-01",
          "displayName": "Mar 2024"
        }
      ],
      "planSegmentLevels": [
        {
          "id": "Organization_Hierarchy.Level_2",
          "displayName": "Level 2",
          "order": 1,
          "segmentId": "Organization_Hierarchy",
          "segmentDisplayName": "Organization Hierarchy"
        },
        {
          "id": "Organization_Hierarchy.Level_3",
          "displayName": "Level 3",
          "order": 2,
          "segmentId": "Organization_Hierarchy",
          "segmentDisplayName": "Organization Hierarchy"
        },
        {
          "id": "Organization_Hierarchy.Level_4",
          "displayName": "Level 4",
          "order": 3,
          "segmentId": "Organization_Hierarchy",
          "segmentDisplayName": "Organization Hierarchy"
        }
      ],
      "planSegmentLevelMembers": [
        {
          "segmentLevelId": "Organization_Hierarchy.Level_2",
          "members": [
            {
              "id": "[Organization_Hierarchy].[-1].[-1]",
              "displayName": "Root - Direct reports"
            },
            {
              "id": "[Organization_Hierarchy].[Customer Support]",
              "displayName": "Customer Support"
            },
            {
              "id": "[Organization_Hierarchy].[Product]",
              "displayName": "Product"
            }
          ],
          "segmentId": "Organization_Hierarchy"
        },
        {
          "segmentLevelId": "Organization_Hierarchy.Level_3",
          "members": [
            {
              "id": "[Organization_Hierarchy].[NA Customer Support]",
              "displayName": "NA Customer Support",
              "parentId": "[Organization_Hierarchy].[Customer Support]"
            },
            {
              "id": "[Organization_Hierarchy].[Asia Customer Support]",
              "displayName": "Asia Customer Support",
              "parentId": "[Organization_Hierarchy].[Customer Support]"
            },
            {
              "id": "[Organization_Hierarchy].[Product Management]",
              "displayName": "Product Management",
              "parentId": "[Organization_Hierarchy].[Product]"
            },
            {
              "id": "[Organization_Hierarchy].[Innovation Center]",
              "displayName": "Innovation Center",
              "parentId": "[Organization_Hierarchy].[Product]"
            }
          ],
          "segmentId": "Organization_Hierarchy"
        },
        {
          "segmentLevelId": "Organization_Hierarchy.Level_4",
          "members": [
            {
              "id": "[Organization_Hierarchy].[Central Call Center]",
              "displayName": "Central Call Center",
              "parentId": "[Organization_Hierarchy].[NA Customer Support]"
            },
            {
              "id": "[Organization_Hierarchy].[East Call Center]",
              "displayName": "East Call Center",
              "parentId": "[Organization_Hierarchy].[NA Customer Support]"
            },
            {
              "id": "[Organization_Hierarchy].[Asia Call Center]",
              "displayName": "Asia Call Center",
              "parentId": "[Organization_Hierarchy].[Asia Customer Support]"
            },
            {
              "id": "[Organization_Hierarchy].[Asia Operations]",
              "displayName": "Asia Operations",
              "parentId": "[Organization_Hierarchy].[Asia Customer Support]"
            }
          ],
          "segmentId": "Organization_Hierarchy"
        },
        {
          "segmentLevelId": "Location.Location_1",
          "members": [
            {
              "id": "[Location].[APAC].[Australia]",
              "displayName": "Australia",
              "parentId": "[Location].[APAC]"
            },
            {
              "id": "[Location].[APAC].[Japan]",
              "displayName": "Japan",
              "parentId": "[Location].[APAC]"
            },
            {
              "id": "[Location].[EMEA].[Poland]",
              "displayName": "Poland",
              "parentId": "[Location].[EMEA]"
            }
          ],
          "segmentId": "Location"
        },
        {
          "segmentLevelId": "Location.Location_3",
          "members": [
            {
              "id": "[Location].[APAC].[Australia].[Victoria].[Melbourne]",
              "displayName": "Melbourne",
              "parentId": "[Location].[APAC].[Australia].[Victoria]"
            },
            {
              "id": "[Location].[APAC].[Japan].[Kansai].[Osaka]",
              "displayName": "Osaka",
              "parentId": "[Location].[APAC].[Japan].[Kansai]"
            },
            {
              "id": "[Location].[EMEA].[Poland].[Masovian].[Warsaw]",
              "displayName": "Warsaw",
              "parentId": "[Location].[EMEA].[Poland].[Masovian]"
            }
          ],
          "segmentId": "Location"
        }
      ]
    }
}

Upload plan data

This sample request sends a data file to Visier. This request uses the roll up calculation method and skips any rows with errors.

Copy

Upload plan_data.csv to Visier

1
2
3
4
curl --location --request PATCH 'https://{vanity_name}.api.visier.io/v1alpha/planning/data/plans/93668189-8734-4cd8-b340-e9bb9f4a38f0/scenarios/gn2tuq1948hrqb3?calculation=ROLLUP&method=SKIP_ERRORS' \
-H 'apikey: {api_key}' \
-H 'Cookie: VisierASIDToken={security_token}'
--form 'file=@"./plan_data.csv"'

The response returns details about the data that was modified in the plan, including any errors that occurred.

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
{
    "updatedCellsCount": 36,
    "errors": [
      {
        "row": 2,
        "rci": "RCIP972016",
        "errorMessage": "There is no row in the plan that corresponds to the group of segment member ids: \"[Organization_Hierarchy].[Customer Support], [Organization_Hierarchy].[NA Customer Support], [Visier_Standard_Location].[AMER].[Argentina]\". No values for this row were loaded."
      },
      {
        "row": 3,
        "rci": "RCIP972016",
        "errorMessage": "There is no row in the plan that corresponds to the group of segment member ids: \"[Organization_Hierarchy].[Customer Support], [Organization_Hierarchy].[NA Customer Support], [Visier_Standard_Location].[AMER].[Argentina]\". No values for this row were loaded."
      },
      {
        "row": 4,
        "rci": "RCIP972016",
        "errorMessage": "There is no row in the plan that corresponds to the group of segment member ids: \"[Organization_Hierarchy].[Customer Support], [Organization_Hierarchy].[NA Customer Support], [Visier_Standard_Location].[AMER].[Argentina]\". No values for this row were loaded."
      }
    ],
    "changelists": [
      {
        "planItem": "Headcount_And_Cost_Planning.Headcount",
        "changes": [
          {
            "rowMembers": [
              "[Organization_Hierarchy].[Customer Support]",
              "[Organization_Hierarchy].[NA Customer Support]",
              "[Visier_Standard_Location].[AMER].[Canada]"
            ],
            "period": "Nov 2024",
            "oldValue": 37.0,
            "newValue": 85.0
          },
          {
            "rowMembers": [
              "[Organization_Hierarchy].[Customer Support]",
              "[Organization_Hierarchy].[NA Customer Support]",
              "[Visier_Standard_Location].[AMER].[Canada]"
            ],
            "period": "Dec 2024",
            "oldValue": 37.0,
            "newValue": 85.0
          }
        ]
      }
    ]
}

Add or remove plan rows

This sample request adds and removes rows in a plan. This request skips any rows with errors.

Copy

Upload plan_rows.csv to Visier

1
2
3
4
curl --location --request PATCH 'https://{vanity_name}.api.visier.io/v1alpha/planning/data/plans/93668189-8734-4cd8-b340-e9bb9f4a38f0/rows?method=SKIP_ERRORS' \
--header 'apikey: {api_key}' \
--header 'Cookie: VisierASIDToken={security_token}'
--form 'file=@"./plan_rows.csv"'

The response returns the number of rows added and removed, the custom members created, and any errors that occurred.

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
{
    "addedRowsCount": 1,
    "removedRowsCount": 2,
    "errors": [
        {
            "row": 2,
            "rci": "RCIP972035",
            "errorMessage": "The row \"[Organization_Hierarchy].[NA Customer Support], [Visier_Standard_Location].[AMER].[Argentina]\" already exists in the plan. It was not added."
        },
        {
            "row": 3,
            "rci": "RCIP972035",
            "errorMessage": "The row \"[Organization_Hierarchy].[NA Customer Support], [Visier_Standard_Location].[b2aa1c96-2ea7-456b-9f2f-e03cd4253714].[7bbddc5c-c504-4f34-a7fa-ba493e98a06b]\" already exists in the plan. It was not added."
        }
    ],
    "customMembers": [
        {
            "id": "[Organization_Hierarchy].[Product].[b2aa1c96-2ea7-456b-9f2f-e03cd4253714]",
            "displayName": "Platform Product",
            "isCustom": true,
            "parentId": "[Organization_Hierarchy].[Product]"
        }
    ]
}