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
Sample Request Body
Sample PATCH Request Body
 

{
      "userName": "SampleUser1@SampleCompany.com",
      "instances": [
          {
              "code": "SampleCompany"
          },
          {
              "code": "SampleCompany_Child",
              "default": true
          }
      ]
  }
Query Parameters
Name
Description
Required
instanceCode
An instance code which is higher in the same instance hierarchy as the instance being added for an existing user. Only users with access to the higher-level parent instance can add child instances.
N
userIdentifier
A userIdentifier is used to determine the unique Adaptive Planning user. Possible values: userName, wid, userGuid.
Y
Request Header
Content Type
application/json
Authorization
Basic or token based
Payload Parameters
Name
Description
Required
wid
The Workday ID of a user.
N
userName
The username (login name) of a user.
N
userGuid
The Global unique user identifier, system-assigned at user creation.
N
instance Code
An instanceCode of company to be assigned to a user in the Payload.
Y
default
The default instanceCode assigned to a user in the Payload.
N

PUT:

Request:
users/instances
:
Updates & replaces existing instances assigned to a user
Updates an existing instance assigned to a user with the specified userIdentifier. Replaces instances assigned to the user with specified data in the request body.
  • If an instance assignment isn't a part of existing instances assigned to a user, adds the instance.
  • If an instance assignment isn't a part of the request body, access to the instance is removed if it existed previously.
  • Specify a user identifier in the userIdentifier query parameter.
  • Specify an instance code in the instanceCode query parameter as needed.
  • A user identifier in the userIdentifier query parameter.
  • In the request body, specify these required fields: <userIdentifier> (Username, WID or userGUID). <userIdentifier> is the value you specified in the userIdentifier query parameter.
  • If you specify the default attribute for an instance, replaces the current default instance for the user.
Sample Request URI
HTTPS://api.adaptiveinsights.com/api/rest/security/v{1}/{default}/users/instances?userIdentifier=userName
Sample Request Body
Sample PUT Request Body 

{
      "userName": "sampleUser@SampleCompanyParent.com",
      "instances": [
          {
              "code": "SampleCompanyParent"
          },
          {
              "code": "SampleCompanyChild",
              "default": true
          },
          {
              "code": "SampleCompanyGrandChild"
          }
      ]
  }
Query Parameters
Name
Description
Required
instanceCode
An instance code which is higher in the same instance hierarchy as the instance being added for an existing user. Only users with access to the higher-level parent instance can add child instances.
N
userIdentifier
A userIdentifier is used to determine the unique Adaptive Planning user. Possible values: userName, wid, userGuid.
Y
Request Header
Content Type
application/json
Authorization
Basic or token based
Payload Parameters
Name
Description
Required
wid
The Workday ID of a user.
N
userName
The username (login name) of a user.
N
userGuid
The Global unique user identifier, system-assigned at user creation.
N
instance Code
An instanceCode of company to be assigned to a user in the Payload.
Y
default
The default instanceCode assigned to a user in the Payload.
N
Responses
Responses
List of status codes supported:
200
Successful response.
Example Response
Sample 200 Successful PATCH Response
 

{
"userName": "SampleUser@SampleComopany.com",
"instances": [
    {
        "code": "SampleCompany"
    },
    {
        "code": "SampleCompany_Child1",
        "default": true
    }
]
}
500
Internal Server Error
Example: If User invalid.
Sample 500 Response
 

{
 "status": {
     "errorMessage": "User with username user@samplecompany.com does not exists in company SampleCompany. "
 },
 "userName": "user@samplecompany.com"
}
Example: if invalid instanceCode
Sample 500 Response
 

{
  "userName": "user@samplecompany.com",
  "instances": [
      {
          "status": {
              "errorMessage": "SampleOtherCompany not in SampleCompany network. API Caller: APICaller@samplecompany.com  not authorized to assign user: user@samplecompany.com to Instance: SampleOtherCompany "
          },
          "code": "SampleCompany",
          "default": true
      },
      {
          "code": "SAMPLECOMPANY_CHILD2"
      }
  ]
}
405
Invalid Resource or operation
403
User has insufficient permissions
404
Resource not found.