User groups

User groups help you manage the permissions and access of users that have the same roles or responsibilities in a company. After you add a user to a user group, they automatically inherit all permissions and access defined by the roles assigned to that user group. User the user-group-member object to add and delete users from user groups.

List user groups

get/objects/company-config/user-group

Returns a collection with a key, ID, and link for each user group. This operation is mostly for use in testing; use the query service to find user groups that meet certain criteria and specify the properties that are returned.

Permissions and other requirements
SubscriptionAdministration
User typeBusiness user with admin privileges
PermissionsUsers - List, View, and Groups
SecurityOAuth2
Responses
200

OK

400

Bad Request

Request samples 
Response samples 
application/json
{
  • "ia::result": [
    • {
      • "key": "1",
      • "id": "Warehouse users",
      • "href": "/objects/company-config/user-group/1"
      },
    • {
      • "key": "96",
      • "id": "AP users",
      • "href": "/objects/company-config/user-group/96"
      },
    • {
      • "key": "21",
      • "id": "Administrators",
      • "href": "/objects/company-config/user-group/21"
      }
    ],
  • "ia::meta": {
    • "totalCount": 3,
    • "start": 1,
    • "pageSize": 100,
    • "next": null,
    • "previous": null
    }
}
Create a user group
post/objects/company-config/user-group
Creates a new user group.



Permissions and other requirements



SubscriptionAdministration


User typeBusiness user with admin privileges


PermissionsUsers - Add and Groups







SecurityOAuth2 
Request 
Request Body schema: application/json
required
User group to create


id
required
string
Name of the user group. The name cannot be changed after the group is created.


 
 Example:  "AP"
description
required
string
Description of the user group.


 
 Example:  "Accounts Payable"
Array of objects
List of roles assigned to the user group. All users in the group inherit the permissions defined by the roles. Only applies to companies that use role-based permissions instead of user-based permissions.


 
 Array 
key
string
Unique key of the role.


 
 Example:  "7"
id
string
Name of the role.


 
 Example:  "Warehouse users"
Responses 
201
Created


400
Bad Request


Request samples 
application/json
{
  • "id": "GL users",
  • "description": "General Ledger account managers",
  • "roles": [
    • {
      • "key": "7"
      },
    • {
      • "key": "65"
      },
    • {
      • "key": "72"
      }
    ]
}
Response samples 
application/json
{
  • "ia::result": {
    • "key": "41",
    • "id": "GL users",
    • "href": "/objects/company-config/user-group/41"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Get a user group
get/objects/company-config/user-group/{key}
Returns detailed information for a specified user group.



Permissions and other requirements



SubscriptionAdministration


User typeBusiness user with admin privileges


PermissionsUsers - List, View, and Groups







SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned unique key for the user group.


 
 Example:  41
Responses 
200
OK


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "key": "41",
    • "id": "GL users",
    • "description": "General Ledger managers",
    • "audit": {
      • "createdDateTime": "2024-02-15T11:39:04Z",
      • "modifiedDateTime": "2024-02-15T11:39:04Z",
      • "createdBy": "51",
      • "modifiedBy": "51"
      },
    • "roles": [
      • {
        },
      • {
        },
      • {
        }
      ],
    • "href": "/objects/company-config/user-group/41"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Update a user group
patch/objects/company-config/user-group/{key}
Updates an existing user group by setting field values. Any fields not provided remain unchanged.  A new value for the roles array will replace the existing array.



Permissions and other requirements



SubscriptionAdministration


User typeBusiness user with admin privileges


PermissionsUsers - Edit and Groups







SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned unique key for the user group.


 
 Example:  41
Request Body schema: application/json
description
string
Description of the user group.


 
 Example:  "Accounts Payable"
Array of objects
List of roles assigned to the user group. All users in the group inherit the permissions defined by the roles. Only applies to companies that use role-based permissions instead of user-based permissions.


 
 Array 
key
string
Unique key of the role.


 
 Example:  "7"
id
string
Name of the role.


 
 Example:  "Warehouse users"
Responses 
200
OK


400
Bad Request


Request samples 
application/json
{
  • "description": "Who can manage GL accounts"
}
Response samples 
application/json
{
  • "ia::result": {
    • "key": "41",
    • "id": "GL users",
    • "href": "/objects/company-config/user-group/41"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Delete a user group
delete/objects/company-config/user-group/{key}
Deletes a user group.



Permissions and other requirements



SubscriptionAdministration


User typeBusiness user with admin privileges


PermissionsUsers - Delete and Groups







SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned unique key for the user group.


 
 Example:  41
Responses 
204
No Content


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "ia::error": {
      • "code": "invalidRequest",
      • "message": "A POST request requires a payload",
      • "errorId": "REST-1028",
      • "additionalInfo": {
        },
      • "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
      }
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 0,
    • "totalError": 1
    }
}
Query user groups
post/services/core/query
Use the query service to find user groups that meet certain criteria and to specify the properties that are returned.


SecurityOAuth2 
Responses 
200
OK


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "ia::error": {
      • "code": "invalidRequest",
      • "message": "A POST request requires a payload",
      • "errorId": "REST-1028",
      • "additionalInfo": {
        },
      • "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
      }
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 0,
    • "totalError": 1
    }
}