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
    email 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.