Create Group

    Creates a new group corresponding to an external key managed by the client.

    API Type

    Server API

    Request URL

    https://apis.worksmobile.com/r/{API ID}/organization/v3/domains/{domainId}/groups/{externalKey}

    HTTP Method

    POST (Content-Type: application/json; charset=UTF-8)

    Path Parameters

    Parameter Type Length Required Description
    domainId Integer Y Domain ID
    externalKey String 100 characters Y Group external key
    ● It must be unique in a tenant.
    ● Special characters \%#/? are not allowed.

    Request Body

    Parameter Type Length Required Description
    name String 100 characters Y Group name
    ● It must be unique in a domain.
    description String 300 characters N Description
    display Boolean Y Indicates whether to show the group.
    ● It indicates whether to show the group in search results for users who are not managers or members.
    serviceAlarm Boolean Y Indicates whether to send service alarms.
    serviceManageEnable Boolean Y Indicates whether the group manager can change whether to use the service.
    managers List Y Group managers
    ● The users must also be the members of the group to use the group features (chatroom/note/schedule/folder) .
    managers[].domainId Integer Y Manager's domain ID
    managers[].externalKey String 100 characters Y Manager's user external key
    members List Y Group members
    managers[].domainId Integer Y Member's domain ID
    managers[].kind String Y Type of members
    ● DOMAIN_USER: User
    ● DOMAIN_ORGUNIT: Organization
    ● DOMAIN_GROUP: Group
    managers[].externalKey String 100 characters Y Member's user/organization/group external key
    messageUse Boolean Y Indicates whether to use group chatrooms
    noteUse Boolean Y Indicates whether to use group notes.
    ● Available only if a group chatroom is used.
    calendarUse Boolean Y Indicates whether to use group schedules.
    ● Available only if a group chatroom is used.
    folderUse Boolean Y Indicates whether to use group folders.
    ● Available only if a group chatroom is used.
    mailUse Boolean Y Indicates whether to use group emails (for the Basic/Premium products only).
    ● Set this to “false” for the Lite product.
    ● If it is "true," email is also required.
    email String 90 characters N Group email address (if mailUse is “true”).
    ● localpart@domain
    ● A localpart must start with a lowercase English letter, a number or an exclamation mark (!).
    ● A dot (.) cannot be the first or last character of a localpart, and two or more consecutive dots are not allowed.
    ● A localpart must be between 2 and 64 characters, and can contain lowercase English letters, numbers, dot (.), hyphen (-), underscore (_) and exclamation mark (!) only.
    aliasEmails List 5 N Group sub email addresses (if mailUse is "true").
    ● Each email address can be up to 90 characters long.
    ● localpart@domain
    ● A localpart must start with a lowercase English letter, a number or an exclamation mark (!).
    ● A dot (.) cannot be the first or last character of a localpart, and two or more consecutive dots are not allowed.
    ● A localpart must be between 2 and 64 characters, and can contain lowercase English letters, numbers, dot (.), hyphen (-), underscore (_) and exclamation mark (!) only.
    receiveExternalMail Boolean N Indicates whether to receive external emails (if mailUse is "true").
    externalEmails List 500 N External email addresses to receive group emails.
    ● A company email address is not allowed.
    membersToReceiveFrom List N Users who can send an email to the group email address (if mailUse is "true").
    ● Receives group emails only from the users specified in this field.
    membersToReceiveFrom[].domainId Integer Y User's domain ID
    membersToReceiveFrom[].externalKey String 100 characters Y User's external key
    membersToSendout List N Users who can use the group email address as their sending address (if mailUse is "true").
    ● The users specified in this field must be the members or managers of the group. (Those who are not the members or managers of the group will be excluded from the list).
    membersToSendout[].domainId Integer Y User's domain ID
    membersToSendout[].externalKey String 100 characters Y User's external key

    Request Example

    POST https://apis.worksmobile.com/r/apiid/organization/v3/domains/123/groups/EX123

    {
    "name": "Groups Name",
    "description": "Description",
    "display": true,
    "serviceAlarm": true,
    "serviceManageEnable": true,
    "members": [
        {
        "domainId": 1,
        "externalKey": "USER001"
    }],
    "members": [{
            "domainId": 1,
            "externalKey": "USER001",
            "kind": "DOMAIN_USER"
        },
        {
            "domainId": 1,
            "externalKey": "ORGUNIT001",
            "kind": "DOMAIN_ORGUNIT"
        },
        {
            "domainId": 1,
            "externalKey": "GROUPS002",
            "kind": "DOMAIN_GROUPS"
        }
    ],
    "messageUse": true,
    "noteUse": true,
    "calendarUse": false,
    "folderUse": false,
    "mailUse": true,
    "email": "groups_email@example.com",
    "aliasEmails": [
        "groups_alias@example.com"
    ],
    "receiveExternalMail": true,
    "externalEmails": [
        "external@external.com"
    ],
    "membersToReceiveFrom": [{
        "domainId": 1,
        "externalKey": "USER001"
    }],
    "membersToSendout": [{
        "domainId": 1,
        "externalKey": "USER001"
    }]
}

    Response

    It returns HTTP status 200 with no response if successful.

    Error Code

    It returns an error code and message on failure.
    Refer to Organization Integration REST API Error Codes for details.