Skip to main content
Documentation
Documentation
Adaptive Planning
Last Updated: 2026-06-26
Versions

Versions

URL Endpoint

HTTPS://api.adaptiveplanning.com/api/rest/modeling/<version>/<tenant>/versions
HTTPS://api.adaptiveplanning.com/api/rest/modeling/<version>/<tenant>/cloneVersion
(POST only)
Version: v1
Category
Metadata submission, modification, and retrieval
Description
Metadata Modification
Permissions Required to Invoke
Model Management
Model
Parameters Required on Request
Varies for endpoint:
PATCH, POST, DELETE: version name.
none for GET

Supported HTTP VERB(s)

(Note: Version folders are not supported for any of the endpoints below)
HTTP verb
Single Resource
Collection Resource
Description
GET
Not Supported
Supported
Retrieve all versions of the tenant.
DELETE
Supported
Not Supported
Delete existing deltable version.
PATCH
Supported
Not Supported
Create/update actuals versions, or update plan versions.
POST
Supported
Not Supported
Create a new plan version.

GET

Request URI
/api/rest/modeling/v1/{tenant}/versions:
Retrieves all versions of the tenant
Retrieves all versions of the tenant in a list.
Properties not shown on the UI for specific versions are not included in their corresponding version objects in the response. For example, startOfVersion for sub-actuals versions.
Able to use pagination via the 'limit' and 'offset' parameters.
The following version properties are currently not supported/displayed in GET:
Base version (for virtual versions), enable constant currency reporting (for virtual versions),
Calculate formula values, Admin access, user access, editable sheets access, privileged actuals access, group, group access level.
Sample Request URI:
HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/DACCO/versions?limit=25&offset=1
Sample Request Body:
<Leave blank>
Query Parameters:
Name
Description
Required
limit
The maximum number of objects in a single response.
N
offest
The zero-based index of the first object in a response collection. The default is 0.
Use offset with the limit parameter to control paging of a response collection.
N
Path Parameters:
Name
Description
Required
tenant
The tenant to operate on, e.g. GREENCO
Y
Sample Reponse
200 OK
Note: the Start of Version for actuals versions and the Left Scroll Limit for plan versions are both displayed under the startOfVersion property (pointer A).
Similarly, the End of Version for actuals versions and the End of Plan for plan versions are both displayed under the endOfVersion property (pointer D).
The Starting Scroll Location for actuals versions and the Start of Plan for plan versions are both displayed under the startingScrollLocation property (pointer C).
Successful response.
Sample Response
 
{
    "data": [
        {
            "name": "Test-Actuals-Version",
            "shortName": "Test-Actuals-Version-Shortname",
            "versionType": "ACTUALS",
            ...
            "lockLeadingCompletion": true
        },
        {
            "name": "JE Sub under Actuals",
            "shortName": "JE01",
            "parent": "Actuals",
            ...
            "journalEntryVersion": true,
            "journalEntryVersionProperties": {
                "journalEntryNumbering": "N",
                "startingNumber": 0
            },
            ...
        },
        ...
    ],
    "limit": 12,
    "offset": 4,
    "total": 12
}

DELETE

Request
/api/rest/modeling/v1/{tenant}/versions:
Delete an existing version
Deletes the version with the specified version name.
The root actuals version and the default version cannot be deleted.
Sample Request URI:
HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/DACCO/versions?versionName={versionName}
Sample Request Body:
<Leave blank>
Query Parameters
Name
Description
Required
versionName
Name of the existing verstion to delete.
Y
instanceCode
The instanceCode to retrieve values from. For example, GLOBO. If no instanceCode is specified, the default instance of the user is used.
N
Path Parameters
Name
Description
Required
tenant
The tenant to operate on, e.g. GREENCO
Y
Sample Response
204 NO_CONTENT
Successful response is blank with status code 204.

PATCH

Request:
/api/rest/modeling/v1/{tenant}/versions:
Create/update actuals versions, or update plan versions.
If specified version identifier exists, updates the existing actuals/plan version. If not, creates a new actuals version using that identifier.
There are currently two sets of version identifiers supported via query parameters:
-version name
One and only one of the above query parameters is required to be specified in the URL for each call.
Sample Request URI:
HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/DACCO/versions?versionName={versionName}
Request Body
-JSON containing the version properties to be updated for the existing version, or to be specified for the new version to be created.
Update:
-For updates, no specific property is required in the request body (except for versionType), but a request body is still necessary. The request body section of
POST
 outlines the list of properties for different types of Plan versions.
-Indicator properties (e.g. journalEntryVersion) cannot be updated; however they can still stay in the request body as long as they have the correct unchanged value.
-Parent updating is currently not supported.
-When updating non-leaf versions (versions that have children), the user groups of these versions can only have "FULL_ACCESS" or "HIDDEN" access types. "FULL_ACCESS" shows up as, and is equivalent to, "VISIBLE" on the UI.
-Group Access details (group ID and group access level) can be removed via specifying groupId=0 in the request body of an update call.
Create:
-For creates, the following properties are available for specification in the request body:
Properties
Description
Required (For Actuals)
Required (For Journal Entry)
Property name in request body
Value Type
Default Value
Short name
Version short name.
N
N
shortName
String
empty string
Parent
Parent of this version.
N
N
parent
String (version name)
root actuals version
Version Type
Type of version (ACTUALS or PLANNING)
Y, ACTUALS
Y, ACTUALS
versionType
String
Description
Description
N
N
description
String
empty string
Administrators access
Version access level for administrators.
N
N
administratorsAccess
VersionAccessControl
inherited from parent
User access
version access level for users.
N
N
userAccess
VersionAccessControl
inherited from parent
Privileged actuals access
Version access level for anyone with the Privileged Actuals Access permission.
N
N
privilegedActualsAccess
VersionAccessControl
inherited from parent
Group ID
A specified user group ID
N
N
groupId
Integer
inherited from parent
Group Access level
Version access level of the specified user group.
Y if Group ID is specified.
Y if Group ID is specified.
groupAccessLevel
VersionAccessControl
inherited from parent
Audit trail
Keeping/deleting audit trail information.
N
N
auditTrail
Boolean
false (inherited from parent for Journal Entry versions)
Journal Entry Version
Whether the version to be created is a journal entry.
N
Y, true
journalEntryVersion
Boolean
returnId
Returns a version id if it is set true. New version id if the operation created a new version. Otherwise, it returns the id of the existing version that has been updated.
N
N
returnId
Boolean
false (returns 204 No Content with it as false, it returns 200 OK with version in the response if it's set as true)
Archived Version
If true, it will archive this version. When a version is archived, it keeps values from changing upon future model structure or formulas changes. This parameter is used for plan versions that are locked.
N
N
archivedVersion
Boolean
false
-The VersionAccessControl value type can take on the following string values: "HIDDEN", "LOCKED", "LOCKED_EXCEPT_NOTES", "IMPORT_AND_NOTES", "FULL_ACCESS"
-Group IDs are obtainable via exportGroups public API.
-Journal Entry versions are not supported for companies with consolidation disabled.
Journal Entry Version Properties:
The following properties exist under the journalEntryVersionProperties nested object (see sample request body) and are only used for JE Versions:
Properties
Description
Required (for Actuals)
Required (for Journal Entries)
Property name in the request body
Value Type
Default Value
Journal entry numbering
Specify how journal entries will be numbered. Can be either automatic (A), manual (M), or none (N).
Unused
N
journalEntryNumbering
String
none (N)
Prefix
Prefix of JE Numbering
Unused
Y if Journal Entry numbering is automatic (A) or manual (M)
prefix
String
Starting number
Starting number of JE numbering
Unused
Y if Journal entry numbering (A)
startingNumber
Integer
Root Actuals-Specific Properties:
The following properties are only used when updating root actuals:
Properties
Description
Required
Property name in request body
Value Type
Start of version
Start of version
N
startOfVersion
String (time period code)
End of version
End of version
N
endOfVersion
String (time period code)
Starting scroll location
Starting scroll location of version
N
startingScrollLocation
String (time period code)
Completed values through
When the actuals overlay on plan version stops
N
completedValuesThrough
String (time period code)
Enable workflow
Lets you submit actuals by level in Workflow.
N
endableWorkflow
Boolean
Sample Request Body:
Request Body
 
{
        "parent": "Parent Version",
        "versionType": "ACTUALS",
        ...
        "administratorsAccess": "FULL_ACCESS",
        "usersAccess": "IMPORT_AND_NOTES",
        ...
        ...
        "auditTrail": true
}
Sample Request Body for versions with nested properties (Journal Entry versions and virtual versions):
Request Body
 
{
        "parent": "Actuals",
        "versionType": "ACTUALS",
        "shortName": "test JE version",
        "journalEntryVersion": "true",
        "journalEntryVersionProperties": {
                "journalEntryNumbering": "A",
                "prefix": "JE-Prefix",
                "startingNumber": "25"
        },
        ...
        "auditTrail": true
}
Query Parameters:
Name
Description
Required
versionName
Name of the new version to create, or the existing version to update.
Y
proceedWithWarnings
An optional query parameter used to dismiss warning messages. If not set to true, potential warnings will be returned before the call executes. Dismiss them by specifying this parameter to true in the URL.
N
instanceCode
The instanceCode to retrieve values from. For example, GLOBO. If no instanceCode is specified, the default instance of the user is used.
N
Path Parameters:
Name
Description
Required
tenant
The tenant to operate on, e.g. GREENCO
Y
Publishing Access Properties:
The following request body properties are only used when WD is enabled:
Sample Response
204 NO_CONTENT
Successful response is blank with status code 204.

POST

Request:
/api/rest/modeling/v1/{tenant}/cloneVersion:
Create a new plan version
Creates a new plan or prediction version via cloning a source/default version, or creates a virtual version.
There are currently two sets of version identifiers supported via query parameters:
-new version name
One and only one of the above is required to be specified in the URL for each call
Sample Request URI:
HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/DACCO/cloneVersion?newVersionName=Budget 2012&
sourceVersionName=Budget 2011&
copyAllData=true&
copySharedFormulasAndRules=true&
copyAllOverrideFormulas=false
Request body:
JSON containing the version properties to be specified for the new version to be created.
Name
Description
Required (for Plan)
Required (for Predictive)
Required (for Virtual)
Property name in request body
Value Type
Default Value
Short name
Version short name.
N
N
N
shortName
String
empty string
Parent
Parent folder of this version.
N
N
N
parent
String (folder name)
Version Type
Type of version (ACTUALS or PLANNING)
Y, PLANNING
Y, PLANNING
Y, PLANNING
versionType
String
Description
Description.
N
N
N
description
String
empty string
Locked version
Locks the entire version for all users, including master formulas and other account formulas.
N
Unused
Unused
lockedVersion
Boolean
inherited from source version
Calculate formula values
Available for plan versions that have Locked Version checked. Used to preserve the calculated results of formulas and references in most accounts and to increase the performance of locked versions.
N
Unused
Unused
calculateFormulaValues
Boolean
false
Archived Version
If true, it will archive this version. When a version is archived, it keeps values from changing upon future model structure or formula changes. This parameter is used for plan versions that are locked.
N
Unused
Unused
archivedVersion
Administrators access
Version access level for administrators.
N
N
N
administratorsAccess
VersionAccessControl
inherited from source version (Plan); IMPORT_AND_NOTES (Predictive); LOCKED (Virtual)
Users access
Version access level for users.
N
N
N
usersAccess
VersionAccessControl
inherited from source version (Plan); IMPORT_AND_NOTES (Predictive); LOCKED (Virtual)
Editable sheet access
Version access level for anyone with the Editable Sheet Access permission.
N
N
N
editableSheetAccess
VersionAccessControl
inherited from source version (Plan, Predictive)
Group ID
A specified user group's ID.
N
N
N
groupId
Integer
inherited from source version (Plan, Predictive)
Access level
Version access level of the specified user group.
N
N
N
groupAccessLevel
VersionAccessControl
inherited from source version (Plan, Predictive)
Left scroll limit
Left scroll limit of version.
N
N
Unused
startOfVersion
String (time period code)
inherited from source version
End of plan
End of plan
N
N
Unused
endOfPlan
String (time period code)
inherited from source version
Start of plan
Start of plan
N
N
Unused
startOfPlan
String (time period code)
inherited from source version
Lock leading time period
Makes specified periods of data uneditable in the version. Shown as "Lock leading {leaf stratum} through" on the UI.
N
Unused
Unused
lockLeadingTimePeriod
String (time period code)
inherited from source version
Lock leading completion
The "Completion {leaf stratum}" option for the property above. This property and "Lock leading time period" cannot both be specified in the request body.
N
Unused
Unused
lockLeadingCompletion
Boolean
inherited from source version
Default
Makes the version the default version for all users.
N
Unused
Unused
default
Boolean
false
Audit trail
Keeping/deleting audit trail information.
N
N
Unused
auditTrail
Boolean
inherited from source version
Actuals overlay includes unavailable levels
Displays all levels, even ones that are no longer used, in actuals overlays.
N
N
Unused
actualsOverlayIncludesUnavailableLevels
Boolean
false
Actuals version for overlay
Overlays the plan data with the specified actuals version's data.
N
N
Unused
actualsVersionOverlay
String (version name)
root actuals version
Drill into Transactios ID
Enables the ability to drill into transactions for the version.
N
N
Unused
drillIntoTransactionId
Integer
default report
Predictive Version
Whether the version to be created is a predictive version.
Unused
Y, true
Unused
predictiveVersion
Boolean
Virtual Version
Whether the version to be created is a virtual version.
Unused
Unused
Y, true
virtualVersion
Boolean
returnId
It returns a version id if it is set true. New version id if the operation created a new version. Otherwise, it returns the id of the existing version that has been updated.
N
N
N
returnId
Boolean
false (returns 204 No Content with it as false, it returns 200 OK with version in in the response if it's set as true)
-The VersionAccessControl value type can take on the following string values: "HIDDEN", "LOCKED", "LOCKED_EXCEPT_NOTES", "IMPORT_AND_NOTES", "FULL_ACCESS"
-Locked plan versions cannot have "IMPORT_AND_NOTES" or "FULL_ACCESS" set for any user group.
-Predictive versions cannot have "FULL_ACCESS" set for any user group.
-Virtual versions can only have "HIDDEN" or "LOCKED" set for any user group.
-Plan and predictive versions cannot be created for companies that have consolidation enabled without planning.
Version Virtual Properties
The following properties exist under the virtualVersionProperties nested object and are only used for Virtual Versions:
Name
Description
Required (for Plan)
Required (for Predictive)
Required (for Virtual)
Property name in request body
Value Type
Default Value
Base Version
The version that will provide the base data for the virtual version. Cannot be a virtual version or sub actuals version.
Unused
Unused
N
baseVersion
String (version name)
default version
Exchange rate version
The version that will provide the exchange rate for the virtual version used for constant currency reporting. Cannot be a virtual version or sub actuals version.
Unused
Unused
N
exchangeRateVersion
String (version name)
root actuals version
Enable Constant Currency Reporting
Enable/disable constant currency reporting.
Unused
Unused
N
enableConstantCurrencyReporting
Boolean
false
Offset
Amount of offset backward (positive integer) or forward (negative integer).
Unused
Unused
N
offset
Integer
0
Publishing Access Properties
The following request body properties are only used when WD is enabled:
Name
Description
Required (for Plan)
Required (for Predictive)
Required (for Virtual)
Property name in request body
Value Type
Default Value
Financial Plans
Enable/disable financial plans for this version.
Only used when Adaptive Planning for Financial Plans is enabled.
N
Unused
Unused
financialPlans
Boolean
false
Headcount Plans
Enable/disable headcount plans for this version.
Only used when either Adaptive Planning for Financial Plans or Adaptive Planning for the Workforce is enabled.
N
Unused
Unused
headcountPlans
Boolean
false
Workforce Action Plans
Enable/disable workforce action plans for this version.
Only used when Adaptive Planning for the Workforce is enabled.
N
Unused
Unused
workforceActionPlans
Boolean
false
Sample Request Body
Request Body
 
{
        "parent": "Parent Folder",
        "versionType": "PLANNING",
        "description": "Test Plan Version",
        ...
        ...
        "usersAccess": "LOCKED_EXCEPT_NOTES",
        "editableSheetAccess": "LOCKED",
        ...
        "startOfVersion": "2012",
        "endOfVersion": "2013",
        "startingScrollLocation": "01/2012",
        "lockLeadingTimePeriod": "02/2012",
        "actualsOverlayIncludesUnavailableLevels": true
}
Query Parameters
Name
Description
Required (for Plan)
Required (for Predictive)
Required (for Virtual)
Parameter name in URL
Default Value
Source version name
The name of the version to clone from. If not specified, clones from the default version.
N
N
Unused
sourceVersionName
New version name
Name of the new version to be created.
Y
Y
Y
newVersionName
Copy all data
If true, copies all data.
N
Unused
Unused
copyAllData
false
Copy shared formulas and rules
If true, copies shared formulas and rules.
N
Unused
Unused
copySharedFormulasAndRules
false
Copy all override formulas
If true, copies all override formulas.
N
N
Unused
copyAllOverrideFormulas
false
Copy splits in GL and custom accounts
If true, copies splits in GL and custom accounts.
N
Unused
Unused
copySplitsInGLAndCustomAccounts
false
Copy modeled rows
If true, copies modeled rows.
N
Unused
Unused
copyModeledRows
false
Copy cell, sheet and workflow notes
If true, copies cell, sheet and workflow notes (if applicable).
N
Unused
Unused
copyAllNotes
false
Reset workflow status to in progress
If true, resets workflow status to in progress.
N
Unused
Unused
resetWorkflowStatusToInProgress
false
Copy audit trail history
If true, adds as report parameter choice to all reports.
Unused
Unused
copyAuditTrailHistory
false
Add as report parameterchoice to all reports
If true, adds as report parameter choice to all reports.
N
Unused
Unused
addAsReportParameterChoiceToAllReports
false
Copy recalculated values of sheets
If true, copies recalculated values of sheets.
N
Unused
Unused
copyRecalculatedValuesOfSheets
false
Proceed with Warnings
An optional query parameter used to dismiss warning messages. If not set to true, potential warnings will be returned before the call exectues. Dismiss them by specifying this parameter to true in the URL.
N
N
N
proceedWithWarnings
false
Instance Code
The instanceCode to retrieve values from. For example, GLOBO. If no instanceCode is specified, the default instance of the user is used.
N
N
N
instanceCode
Default instance of the user
Run asynchronously
If true, the clone version job will run asynchronously. The job id will be returned in the response, which can be used to get the status of the clone version job by sending request to endpoint
GET
https://api.adaptiveinsights.com/api/rest/modeling/v1/{tenant}/jobs/{id}
N
N
N
async
false
-"Reset workflow status to in progress" is not supported for companies with Workflow disabled.
-"Copy recalculated values of sheets" is not supported if MODEL ISOLATION feature flag is off.
Path Parameters:
Name
Description
Required
tenant
The tenant to operate on, e.g. GREENCO
Y
Sample Response:
204 NO_CONTENT
Successful response is blank with status code 204.
200
Successful response. The job detail will be returned.
Response body:
Name
Description
Possible Values
id
The job id
Integer
sourceId
Unique identifier of the job within its type. E.g. for version creation, it would be the new version name.
String
type
Type of the job
"VersionCreation"
userId
The Id of the user initialized the job
Integer
status
Status of the job
"INVALID", "IN_PROGRESS", "SUCCESS", "FAILURE"
errorMessage
Error message if the job fails
String in preferred language
createdOn
The creation time of the job
String represent datetime in ISO 8601 format
updatedOn
The last update time of the job
String represent datetime in ISO 8601 format
returnSuccessData
Additional data related to the job or the object created by the job. This is optional and defaults to false.
BooleanExample