Creates a group for a specified tenant.

post https://{tenanturl}/v2.0/Groups

Entitlement required: manageUserGroups (Manage users and groups), or manageAllUserGroups (Synchronize users and groups), or manageUserStandardGroups (Manage users and standard groups).
Note: You only need one entitlement, but you can have more than one.

To create a group, a displayName is required. An optional Description attribute can be set to describe the group. A group can be created with or without members. When a group is created with members, a list of members needs to be passed in.

By default, an email is sent to each regular user member added to the group. Federated user members do not get an email notification. The email template for branding is at "notifications/user_management/group/{locale}/group_added_email.xml". Pass in the themeId query parameter to brand the email template for notifications. To turn off email notifications, send the notifications option "urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification": {"notifyType":"NONE"} in the payload.

Limitations for tenants that support large groups:

- A maximum of 256 first-level, nested group members is allowed.

- A maximum of 2,500 users members is allowed in the input payload. To add more members, use PATCH.

To check whether the tenant supports large groups, run the GET /v2.0/SCIM/capabilities API.

Query Params

themeId

string

The identifier of the theme that you want to apply.

Body Params

The group object that contains the attributes for the group that is to be created.

schemas

array of strings

required

An array of strings that contain the URIs that indicate the namespaces of the SCIM schemas that define the attributes in the current JSON structure. The schemas "urn:ietf:params:scim:schemas:core:2.0:Group", urn:ietf:params:scim:schemas:extension:ibm:2.0:Group", and "urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification" are valid. The core group schema is required.

schemas*

displayName

string

required

The display name of the group. Maximum length is 255 characters.

members

array of objects

A list of members that are being added. When creating a group, the number of elements must be less than or equal to 10,000.

members

urn:ietf:params:scim:schemas:extension:ibm:2.0:Group

object

urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification

object

externalId

string

Identifier of the Group resource as defined by the provisioning client. Maximum length is 240 characters.

visible

boolean

Responses

Response body

object

schemas

array of strings

required

An array of strings that contain the URIs that indicate the namespaces of the SCIM schemas that define the attributes in the current JSON structure. The schemas "urn:ietf:params:scim:schemas:core:2.0:Group" and "urn:ietf:params:scim:schemas:extension:ibm:2.0:Group" are returned in the response.

schemas*

string

The unique identifier for the resource as defined by the service. This attribute is read-only and will be sent by the service. Any value that is specified for this attribute in the JSON POST or PUT request payload is ignored.

displayName

string

required

A human-readable name for the group.

bookmark

string

An opaque string that is used by the system to get the next 2500 members of this group. The existence of this element in the GET /v2.0/Groups/{id} response payload indicates that more members exist that were not returned in the call. To get the next set of members, the caller makes an additional call to the same endpoint, and passes the bookmark value as a query parameter named "nextPage". For example ?nextPage=XASDGAJDGKAWHGI=. The caller can continue to make calls to the endpoint until no bookmark element are returned in the response payload, which indicates that all group members were returned. A bookmark is generated from a membershipType query. The bookmark feature is available for tenants that have large group support enabled.

urn:ietf:params:scim:schemas:extension:ibm:2.0:Group

object

description

string

The description for the group.

groupType

string

The group type. This value is read-only.

standard reserved

membersPerPage

int32

Members per page. For large group support, this property is the count of members returned in the members array.

totalMembers

int32

required

The total number of members that are in the group.

memberStartIndex

int32

The start index of members that are returned on the page.

owners

array of objects

A list of owners for the group. For large group support, the group ownership is automatically set and enforced when the request has restricted groups that are associated with the access token's user subject identifier.

owners

object

value

string

required

The id of the group owner

$ref

string

The URI of the SCIM resource representing the user. This value is readonly.

displayName

string

The display name of the user. This value is readonly.

meta

object

resourceType

string

The field that indicates the type of resource.

created

string

A DateTime string that indicates when the resource was created.

lastModified

string

A DateTime string that indicates when the resource was last modified.

location

string

The URI of the resource that is being returned.

deactivated

string

A readonly string that indicates why the account is deactivated. Valid values are "api", "timestamp", and "cleanup". The value "api" means that the user was deactivated by using an API. The value "timestamp" means that the user was deactivated by the system because the account expired. The value "cleanup" means that the user was deactivated by the system during account cleanup processing.

api timestamp cleanup

members

array of objects

A list of members that belong to this group. If the group has more than 10,000 members, then this array is empty, unless large group support is enabled for the tenant. With large group support enabled, each call to the GET /v2.0/Groups/{id} endpoint returns at most 2,500 members of the group. If more members of the group exist that were not returned, a bookmark is returned in the response. The bookmark is used to get the next set of group members. See the "bookmark" property for more details.

members

object

string

The unique identifier for the resource as defined by the service. This attribute is read-only and is sent by the service. Any value that is specified for this attribute in the JSON POST or PUT request payload is ignored.

externalId

string

Valid for user type members only. A unique identifier for the resource that is defined by the provisioning client. It identifies a resource between the provisioning client and the service provider. The client can use a filter to locate the resource with the identifier from the provisioning domain.

userName

string

required

Valid for user type members only. The unique identifier for the user that is typically used by the user to directly authenticate to the service provider. It is often displayed to the user as their unique identifier within the system (as opposed to the id or externalId attributes, which are generally opaque and not user-friendly identifiers). Each user must include a non-empty userName value. This identifier must be unique across the service consumer's entire set of users. It must be a stable ID that does not change when the same user is returned in subsequent requests.

title

string

Valid for user type members only. The user's title, such as "Vice President".

name

object

required

displayName

string

The name of the user or group that is displayed to users. Each member returned may include a non-empty displayName value. For a user type member, typically it is the full name of the user that is being described, for example, Babs Jensen or Ms. Barbara J Jensen. However, if that information is unavailable, a username or handle can be used, for example, bjensen. The value is the primary textual label by which this user is normally displayed by the service provider when presenting information to users.

preferredLanguage

string

Valid for user type members only. The language code identifying the preferred language of this identity, for example, en-us or fr-ca.

active

boolean

Valid for user type members only. A Boolean value that indicates the user's administrative status. The definitive meaning of this attribute is determined by the service provider. For example, a value of true indicates that the user is, for example, able to log in, while a value of false indicates that the user's account has been suspended. If not specified, the value defaults to true.

emails

array of objects

required

Valid for user type members only. A list of email addresses that are associated with the user.

emails*

object

value

string

required

The e-mail addresses for the user. The value is canonicalized by the service provider. For example, bjensen@example.com instead of bjensen@EXAMPLE.COM. Must be RFC 2822 compliant. Maximum length is 80 characters.

type

string

required

A label that indicates the attribute function; for example, "work". Only a single email is allowed.

work

addresses

array of objects

required

Valid for user type members only. A list of addresses that are associated with the user.

addresses*

object

locality

string

The city or locality component. Maximum length is 128 characters.

country

string

The country name component. Maximum length is 128 characters.

type

string

A label that indicates the attribute's function; for example, "work" or "home".

work

streetAddress

string

The street address. Maximum length is 128 characters.

postalCode

string

The postal code. Maximum length is 40 characters.

formatted

string

The formatted value of the address. Maximum length is 500 characters.

primary

boolean

Indicates whether this is address is the primary address for correspondence.

region

string

The region. Maximum length is 128 characters.

phoneNumbers

array of objects

Valid for user type members only. A list of phone numbers that are associated with the user.

phoneNumbers

object

value

string

required

A list of phone numbers that are associated with the user. The value is be canonicalized by the service provider according to format in RFC3966, for example, "tel:+1-201-555-0123". Canonical type values are work, home, mobile, fax, and pager. Maximum length is 32 characters.

type

string

required

A label that indicates the attribute's function; for example, "work" or "home".

work home mobile pager fax

type

string

required

The type of group member.

user group

urn:ietf:params:scim:schemas:extension:ibm:2.0:User

object

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

object

value

string

required

A sub-attr required by the SCIM specification that contains the "id" of the SCIM resource.

$ref

string

required

A sub-attr required by the SCIM specification the contains the URI of the SCIM resource.

externalId

string

Identifier of the Group resource as defined by the provisioning client.

Language

URL


xxxxxxxxxx
1
curl --request POST \
2
     --url https://tenant_url/v2.0/Groups \
3
     --header 'accept: application/scim+json' \
4
     --header 'content-type: application/scim+json'

Choose an example:

application/scim+json

201Created.

400The request was incorrect.

403Forbidden.

409The group exists.

500An internal server error occurred.