Skip to main content
Documentation
Documentation
Adaptive Planning
Last Updated: 2023-06-23
Instances

Instances

URL Endpoint

HTTPS://api.adaptiveplanning.com/api/rest/security/<version>/<tenant>/users/instances
Version: v1
Category
Data Update
Description
Assign users to instances when using Adaptive Planning multi-instances in a parent-child hierarchy.
Permissions Required To Invoke
Admin access > Users
The Multi-instance User Access API enables you to retrieve and change instance assignments for a user.

Supported HTTPS VERBs:

HTTP Verb
Single Resource
Collection Resource
Description
GET
Not Supported
Supported
Retrieves all the instance assignments of users, including their default instance assignment.
PATCH
Supported
Not Supported
Adds a new instance to the instance assignment of an existing user.
PUT
Supported
Not Supported
Updates and replaces existing instances assigned to a user with the specified data in the request body.

GET

Request:
/users/instances:
Retrieves a collection of instances assigned to users.
Retrieves all the instance assignments of users, including their default instance assignment. You can filter by instanceCode. Pagination uses the default values for limit or offset if these query parameters are missing.
Sample Request URI
HTTPS://api.adaptiveplanning.com/api/rest/security/v1/default/users/instances?offset=5&limit=5
Sample Request Header:
Accept-Language: en
Sample Request Body
Query Parameters
Name
Description
Required
instanceCode
The unique identifier of an instance defining the instance context to retrieve the list of users for that instance. If an instance code isn’t specified, all users from the default instance of the API caller are retrieved.
N
limit
The maximum number of objects in a single response. The default is 500. The maximum is 500.
N
offset
The zero-based index of the first user in a response collection. The default is 0.
Use offset with the limit parameter to control paging of a response collection.
N
Sample Response
200
Successful Response
Sample Response
 

{
    "links": {
        "next": "https://api.adaptiveplanning.com/api/rest/security/v1/default/users/instances?offset=10&limit=5",
        "previous": "https://api.adaptiveplanning.com/api/rest/security/v1/default/users/instances?offset=0&limit=5"
    },
    "total": 26,
    "users": [
        {
            "userGuid": "111SampleUserGuid",
            "userName": "sampleuser1@company.com",
            "wid" : "14400000000000000000000000000samplewid",
            "instances": [
                {
                    "code": "sampleCompany",
                    "default": true
                }
            ]
        },
        {
            "userGuid": "222SampleUserGuid",
            "userName": "sampleuser2@company.com",
            "wid" : "31100000000000000000000000000samplewid",
            "instances": [
                {
                    "code": "sampleCompany",
                    "default": true
                }
            ]
        },
        {
            "userGuid": "474C4F424F0000000000000001sampleGuid",
            "userName": "sampleuser3@company.com",
            "wid" : "34400000000000000000000000000samplewid",
            "instances": [
                {
                    "code": "sampleCompany",
                    "default": true
                }
            ]
        },
        {
            "userGuid": "111C4F424F0000000000000001sampleGuid",
            "userName": "sampleuser5@company.com",
            "wid" : "343400000000000000000000000000samplewid",
            "instances": [
                {
                    "code": "sampleCompany",
                    "default": true
                }
            ]
        },
        {
            "userGuid": "374C4F424F0000000000sampleGuid",
            "userName": "sampleuser4@company.com,
            ""wid" : "355000000000000000000000000samplewid",
            "instances": [
                {
                    "code": "sampleCompany_Child1"
                },
                {
                    "code": "sampleCompany_Child2"
                },
                {
                    "code": "sampleCompany",
                    "default": true
                }
            ]
        }
    ]
}

PATCH:

Request:
users/instances?instanceCode={INSTANCECODE}:
Partially updates the instance assignment of an existing user.
Adds a new instance to the instance assignment of an existing user. If you specify the default attribute for an instance, it replaces the current default instance assignment of the user.
Specify a user identifier in the userIdentifier query parameter.
In the request body, specify a userIdentifier.
Sample Request URI
HTTPS://api.adaptiveplanning.com/api/rest/security/v1/default/users/instances?userIdentifier=userName