Instances

URL Endpoint

Supported HTTPS VERBs:

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.