Add Members
Adds member information. You can add any members except Admin members.
If SSO is used, a member becomes active right after being added, and can use the service.
If SSO is not used, a member has a status of not activated when added. In this case, the member password needs to be created by “ADMIN” or “MEMBER.” The default is "MEMBER."
- When the password is created by "ADMIN": The member should log in with the password created by the Admin, change the password and then log in with the new password again so as to become active.
- When the password is created by "MEMBER": The member should set a password via the invitation message that has been sent to his or her personal email address (which is required) and log in with the password so as to become active.
API Type
Server API
Request URL
https://apis.worksmobile.com/r/{API ID}/organization/v2/domains/{domainId}/users/{externalKey}
HTTP Method
POST (Content-Type: application/json; charset=UTF-8)
Path Parameters
Parameter | Type | Length | Required | Description |
---|---|---|---|---|
domainId | Integer | Y | The primary position's domain ID | |
externalKey | String | 100 characters | Y | An external key for members in the primary position For a group of companies, it must be unique in the group. Special characters \%#/? are not allowed. |
Request Body
Parameter | Type | Length | Required | Description |
---|---|---|---|---|
String | 90 characters | Y | Account. Member's email address for the Basic and Premium products. id@group for the Lite product. ● localpart@domain (localpart@group for the Lite product) ● A localpart must start with a lowercase English letter or a number. ● 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 40 characters, and can contain lowercase English letters, numbers, dot (.), hyphen (-), and underscore (_) only. |
|
name | Object | Y | Name | |
name.lastName | String | N | Family name. The full name can be up to 80 characters long. Either lastName or firstName must be specified. The following special characters are allowed only: ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~ |
|
name.firstName | String | N | Given name. The full name can be up to 80 characters long. Either lastName or firstName must be specified. The following special characters are allowed only: ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~ |
|
name.phoneticLastName | String | 100 characters | N | Family name in Furigana. (Katakana only) |
name.phoneticFirstName | String | 100 characters | N | Given name in Furigana. (Katakana only) |
i18nNames[] | List | N | Names by language code | |
i18nNames[].language | String | N | Language code. ●ko_KR ●ja_JP ●zh_CN ●zh_TW ●en_US |
|
i18nNames[].firstName | String | 100 characters | N | Given name in the language. A family name is followed by a given name on the organization chart. The following special characters are allowed only: ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~ |
i18nNames[].lastName | String | 100 characters | N | Family name in the language. A family name is followed by a given name on the organization chart. The following special characters are allowed only: ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~ |
nickName | String | 100 characters | N | Nickname. The following special characters are allowed only: ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~ |
privateEmail | String | 256 characters | N | Personal email address. Required if SSO is not used and “passwordConfig.passwordCreationType” is “MEMBER.” Required if the member is the Admin. The email address must be valid. |
aliasEmails | List<String> | 10 | N | Sub email addresses Available only for the Basic/Premium products. ● Each email address can be up to 90 characters long. ● localpart@domain ● A localpart must start with a lowercase English letter or a number. ● 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 40 characters, and can contain lowercase English letters, numbers, dot (.), hyphen (-), and underscore (_) only. |
employmentTypeExternalKey | String | 100 characters | N | External key for employment types. It is available only if "useEmploymentType" of the "Enable Employment Types" API is "true." If this parameter is omitted, no employment type applies. |
searchable | Boolean | N | Indicates whether to enable auto-complete and search for members. Default: true |
|
passwordConfig | Object | N | If this parameter is omitted, the password is created by the member. | |
passwordConfig.passwordCreationType | String | N | Password creation type ● ADMIN: The password is created by the Admin ● MEMBER: The password is created by the member |
|
passwordConfig.password | String | N | Required if “passwordCreationType” is “ADMIN.” | |
organizations[] | List | N | List of domains (companies) to which the member belongs (including both the primary and secondary positions) | |
organizations[].domainId | Integer | Y | Domain ID ● Required if organizations[] is specified. ● Primary/secondary positions: A member has only one position if organizations[].domainId is the same as the domainId in Path Parameter, and has the secondary position if not. |
|
organizations[].externalKey | String | 100 characters | N | An externalKey for members. ● If not specified, it is set to the externalKey in Path Parameter. ● For a group of companies, it must be unique in the group. ● Special characters, \%#/? are not allowed. |
organizations[].email | String | 90 characters | N | Email address Use this parameter if a member needs two different email addresses for the primary and secondary positions while using the Basic/Premium products. ● localpart@domain ● A localpart must start with a lowercase English letter or a number. ● 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 40 characters, and can contain lowercase English letters, numbers, dot (.), hyphen (-), and underscore (_) only. |
organizations[].levelExternalKey | String | 100 characters | N | An external key for levels. It is available only if "useLevel" of the "Enable Levels" API is "true." If this parameter is omitted, no level applies. |
organizations[].orgUnits[] | List | 20 | N | List of organizations |
organizations[].orgUnits[].externalKey | String | 100 characters | Y | An external key for organizations |
organizations[].orgUnits[].represent | Boolean | N | Indicates whether or not it is the default organization. ● If this parameter is not specified, the first one of organizations[].orgUnits[] becomes the default organization. ● If you need to set a company as the default or secondary organization, set this parameter to "true" for the default organization, or "false" for the secondary organization. |
|
organizations[].orgUnits[].positionExternalKey | String | 100 characters | N | An external key for positions. It is available only if "usePosition" of the "Enable Positions" API is "true." If this parameter is omitted, no position applies. |
organizations[].orgUnits[].manager | Boolean | N | Indicates whether the member is a manager. If it is true, the member becomes the manager and the previous manager, if there is, is relieved of his or her duties. ● Default: false |
|
organizations[].orgUnits[].display | Boolean | N | Indicates whether to show the member. ● It indicates whether to show the member on the organization chart. ● Default: true |
|
organizations[].orgUnits[].receiveEmail | Boolean | N | Indicates whether to enable team features. ● Default: true ● Use this parameter when you need to limit the following team features of a member for security purposes: receiving messages in the team room, sharing files and receiving organization emails. ● If this parameter is true, the following team features are enabled. - As a member of the team room (Message/Note/Calendar/Folder), the member can send/receive messages, view notes, receive shared calendar events and view folders. - The member can receive email messages sent to the organization. - The member can receive calendar events shared to the organization. - The member can view the organization calendar. - The member can view files in the drive shared to the organization. - The member can view boards with the permissions given to the organization. - The member can respond to surveys of the organization. - The member also becomes a member of the group which the organization belongs to. ● If this parameter is false, all the team features described above are disabled. Set this parameter to false if you do not allow the member to use the team features. |
|
telephone | String | 100 characters | N | Telephone number. Only numbers with the following characters are allowed: - * # + P T ( ) |
cellphone | String | 100 characters | N | Mobile phone number. Only numbers with the following characters are allowed: - * # + P T ( ) |
fax | String | 100 characters | N | Fax number. Only numbers with the following characters are allowed: - * # + P T ( ) |
location | String | 100 characters | N | Office location |
task | String | 100 characters | N | Task |
messenger | Object | N | ||
messenger.protocol | String | 8 characters | Y | Messenger protocol. ● LINE: LINE ● FACEBOOK: Facebook ● TWITTER: Twitter ● CUSTOM: Custom protocol |
messenger.customProtocol | String | 100 characters | N | Custom protocol if the messenger protocol is "CUSTOM" |
messenger.messengerId | String | 100 characters | Y | Messenger ID |
birthdayCalendarType | String | 1 character | N | Birthday type. ● S: Solar calendar ● L: Lunar calendar |
birthday | String | 10 characters | N | Date of birth (yyyy.mm.dd) |
hireDate | String | 10 characters | N | Date of hire (yyyy.mm.dd) |
locale | String | N | Refer to Language Codes. | |
timeZone | String | N | Refer to Timezone Codes v2. | |
customField | Object | N | Custom field. A schema must be added first with the “Add Custom Field Schemas” API. |
|
customField.{schemaKey}[] | List | 10 | Y | Custom field schema key (schemaKey) defined in the primary position’s domain. A schema key is the key of the map. This field can have up to 10 schema keys. |
customField.{schemaKey}[].value | String | 100 characters | N | Custom field’s text to display |
customField.{schemaKey}[].link | String | 300 characters | N | URL if the type of custom field is link - A value or link must be specified. - If both of them are specified where the value is "Homepage1" and the link is "https://www.unicef.org": <a href = "https://www.unicef.org"> Homepage1 </a> - If only a value is specified, a hyperlink is not created. - If only a link is specified, it is displayed as text. |
Request Example
POST https://apis.worksmobile.com/r/apiid/organization/v2/domains/123/users/EX123
{
"email": "david.jones@example.com",
"name": {
"lastName": "Jones",
"firstName": "David",
"phoneticLastName": "",
"phoneticFirstName": ""
},
"i18nNames": [
{
"language": "en_US",
"firstName": "Jones",
"lastName": "David"
}
],
"nickName": "rabbit",
"privateEmail": "big@example.com",
"aliasEmails": [
"david.jones.alias1@example.com",
"david.jones.alias2@example.com"
],
"employmentTypeExternalKey": "Full-Time",
"searchable": true,
"organizations": [
{
"domainId": 123,
"externalKey": "EX123",
"email": "david.jones@example.com",
"levelExternalKey": "manager",
"orgUnits": [
{
"externalKey": "Sales1",
"represent": true,
"positionExternalKey": "staff",
"manager": false,
"display": false,
"receiveEmail": false
},
{
"externalKey": "Sales2"
}
]
},
{
"domainId": 456,
"externalKey": "EX123",
"email": "david.jones@example.com",
"orgUnits": [
{
"externalKey": "Marketing1",
"represent": true,
"positionExternalKey": "staff",
"manager": true,
"display": true,
"receiveEmail": true
},
{
"externalKey": "Marketing2",
"represent": false,
"receiveEmail": false
}
]
}
],
"telephone": "031-310-7982",
"cellphone": "010-1234-1234",
"fax": "031-234-1234",
"location": "grenn-office",
"task": "developer",
"messenger": {
"protocol": "CUSTOM",
"customProtocol": "INSTAGRAM",
"messengerId": "david"
},
"birthdayCalendarType": "S",
"birthday": "1980.01.01",
"hireDate": "2018.01.01",
"locale": "ko_KR",
"timeZone": "Pacific/Midway",
"customField": {
"schema123": [
{
"value": "Homepage1",
"link": "https://www.unicef.org"
},
{
"value": "Homepage2"
},
{
"link": "https://wfuna.org"
}
],
"schema456": [
{
"value": "CRAFTON Tower"
},
{
"value": "Green Factory"
}
]
}
}
Response
It returns HTTP status 200 with no response when the API call is successful.
Error Code
It returns an error code and message when the API call fails.
Refer to Organization Integration REST API Error Codes for details.