Directory API

The Directory API helps you get and update resources of members and teams under Member in the LINE WORKS Admin, such as Member, Team, and Group. You can access the following resources using the Directory API:

• Member (users)
• Group (groups)
• Team (orgunits)
• Job level (levels)
• Position (positions)
• User type (user-types)
• Custom field (custom-fields)
• Member custom property (user-custom-properties)
• Status (profile-statuses)

To use the Directory API, you need an access token that you can get by authenticating with a user account or a service account.

The API scopes are as follows:

• directory: All resources are accessible.
• user: Only member resources are accessible.
• group: Only group resources are accessible.
• orgunit: Only team resources are accessible.

Information used to specify a resource {#designate-resource}

To access resources including members, groups, teams, job levels, positions, user types, and custom fields, you need to specify which resource you want to access using a resource ID, an external key, or a login ID.

Resource ID {#resource-id}

A resource ID is a unique value assigned by the system when each resource is added. Considering its characteristics listed below, you can use a resource ID to specify and identify a resource with the API.

• Each resource is always assigned a resource ID.
• A resource ID is a permanent value for a resource.
• A resource ID is unique among resources.
• A resource ID is always included when you get a resource using the API.

External key {#external-key}

An external key is an arbitrary value that the API user or administrator can assign to each resource in LINE WORKS.

If you add your company's system ID as an external key for a LINE WORKS resource, you can use it as is in LINE WORKS.

You can add an external key using the API or under Organization Sync in the Developer Console.
For how to bulk add external keys using the API, see Update and get external keys.

The format of an external key to specify a resource is as follows:

externalKey:ExternalKey value

Restrictions on external keys {#external-key-restrictions}

For each resource type, the characters and values for an external key must be unique within a tenant or domain.

Here are restrictions on external keys.

Login ID {#login-id}

You can specify a member's external key as a login ID.

Member (users) {#user}

This resource corresponds to members of LINE WORKS.

Caution

• The properties you can get or set using the API depend on the member properties set in the LINE WORKS Admin.

Note

• A member can have a status of the following: awaiting, pending, using, suspended, and deleted, each of which is described in the following table. You can check the status of a member using the Get a member or Get members API operation.
  |Status | Parameter | Description | |---|---|---| | awaiting | isAwaiting | The status of an account before activationDate.
  It becomes pending or using depending on whether SSO is enabled. | | pending | isPending | Not logged-in.
  A member added by the administrator has not yet logged in. | using | n/a | In use. | | suspended | isSuspended | Suspended.
  Login is not allowed, but the member data is retained. | | deleted | isDeleted | Deleted.
  The data remains for 7 days from the time of deletion and is deleted after that. |

Add and update a member {#add-update-user}

You can add and update a member. You can set a password only when adding a member.

Get members {#get-user-list}

You can get a list of members in a domain, which you can sort and filter if needed.

Get a member {#get-user-information}

Depending on how you use this API operation, you can get the response containing only specified fields.

Here are three ways of getting a member. The API operation returns different member information based on the scope specified when you get an access token.

Delete a member {#delete-user}

There are two types of deletion: delete (delayed delete) and force delete. A deleted member can be undeleted within 7 days after deletion. A member who has been deleted for 7 days or who is force-deleted cannot be recovered.

Manage member photos {#manage-user-photo}

You can manage member photos using the following API operations.

For more information about how to upload or download files, see Upload or Download Files.

Manage member statuses {#manage-user-status}

You can manage member statuses using the following API operations. For how to manage domain statuses, see Status (profile-statuses).

A member can have "current status" and "scheduled status".

{     "userProfileStatuses": [         {             "profileStatusID": "AWAY",             "statusMessage": "I'm out. ",             "startTime": "2023-05-11T09:00:00+09:00",             "endTime": "2023-05-11T12:00:00+09:00",             ...         }     ]}

Manage permission to chat with external users {#manage-link-to-externaluser}

You can manage permission to chat with external LINE WORKS users or LINE users.

Use the following API operations to manage permission to chat with external LINE WORKS users .

Use the following API operations to manage permission to chat with external LINE users.

Use the following API operations to manage a URL for adding an external contact.

Caution

• The user scope is required. With the directory scope, you cannot manage permission to chat with external users.

Suspend a user or set a leave of absence {#user -suspend-leaveofpending}

You can set a "leave of absence" or "suspend" a member. Then, the leave of absence information is displayed on the member's profile and organization chart. The member is also indicated as leaveOfAbsence when you get the member information using the API. A suspended member cannot log in to LINE WORKS; the member is indicated as isSuspended when you get the member information using the API.

Manage members {#manage-user}

You can invite members or force them to log out using the following API operations.

Group {#group}

You can create groups for communication such as projects or in-house gatherings. Use the following API operations to manage groups.

A group can use features such as Message, Note, Calendar, Task, and Folder. Groups are managed by domain. You need to specify at least one group master to manage the group, and can add members, teams or other groups to the group.

{     "groupName": "Verification",     "administrators": [         {             "userId": "user-40d6-450f-1c78-1234567890ab",             "userExternalKey": null         },         {             "userId": "user-08ee-41fb-1a61-1234567890ab",             "userExternalKey": null         }     ],     "members": [         {             "id": "user-40d6-450f-1c78-1234567890ab",             "type": "USER",             "externalKey": null         },         {             "id": "orgunit-5c41-4baf-239e-1234567890ab",             "type": "ORGUNIT",             "externalKey": null         },         {             "id": "group-6bb3-40ea-37a7-1234567890ab",             "type": "GROUP",             "externalKey": null         }     ],...}

Dynamic group {#dynamic-group}

Using dynamic groups, you can create conditions (queries) to automatically manage group members according to specific rules. Members who match the specified conditions are automatically added to or removed from a group.

Here is how to create a dynamic group query:

Available attributes {#dynamic-group-query-property}

You can use the following attributes to create a query.

Functions {#dynamic-group-query-function}

Negative support

Add an exclamation mark (!) before a conditional statement enclosed with parentheses (()).

Conditions {#dynamic-group-query-condition}

A condition is the smallest unit of a query. The format of a condition is as follows:

{attribute} {operator between attribute and value} {value} 

Example) user.userTypeId == 'usertypei-70c3-46a8-22dd-03ef7c571975'

Operators {#dynamic-group-query-operator}

Here are the logical operators that can be used between conditions.

• &&: AND operator. It requires that both conditions are true.
• ||: OR operator. It requires that at least one of the conditions is true.

You can use the following operator between an attribute and a value.

• ==: Equality operator. It requires that the attribute and the value are equal.

Condition priority {#dynamic-group-query-priority}

The priority of conditions is as follows:

1. Conditions in parentheses
2. Conditions combined with &&
3. Conditions combined with ||
4. If the priorities are equal, the conditions are evaluated from left to right.

Example)

• A || B && C: B && C is evaluated first.
• (A || B) && C: (A || B) is evaluated first.
• A || B || C: A || B is evaluated first.

Restrictions {#dynamic-group-query-restrictions}

The following restrictions apply:

• Up to 10 attributes are available for a query.
• A negative statement can only be applied to one condition.
• A negative statement cannot be included in a function.
• The depth of the parentheses to indicate the evaluation order must be 2 or less.

Team (orgunits) {#orgunit}

You can add teams (orgunits) to LINE WORKS according to your company's team information. For projects or in-house gatherings, use groups rather than teams. You can manage teams using the following API operations:

A team can use features such as Message, Note, Calendar, Task, and Folder. Teams are managed by domain. You can find and set a member's team in teams (orgUnits).

{     "email": "user@example.com",     "organizations": [         {          ...             "orgUnits": [                 {                     "orgUnitId": "orgunit-0faa-4f37-22bb-1234567890ab",                     "orgUnitName": "Sales team",                     ...                }             ]         }     ],     ...

Access restrictions in the organization chart {#orgunit-access-restrict}

You can set access restrictions in the organization chart.

You can manage member access restrictions using the following API operations.

You can manage user type access restrictions using the the following API operations.

You can manage team access restrictions using the following API operations.

Access restrictions apply in the following order: "member," "user type," and "team."
For example, if a specific user's access restrictions are set for a member, user type, and team, those for a member apply; depending on the restriction type, the user can view their own information, their team, or their team and specified teams only.

Job level {#level}

Levels are job grades, such as assistant manager or manager, given to members. You can manage levels using the following API operations.

Levels are managed by domain. You can specify and get a member's job level using an automatically assigned levelID.

{    "email": "user@example.com",    "organizations": [       {          "domainId": 12345678,          "organizationName": "Sample store",          "levelId": "level-1999-4212-7979-1234567890ab",          "levelName": "Executive"...

Position {#position}

Positions refer to a work responsibility assigned to each member. You can manage positions using the following API operations.

Positions are managed by domain. Since a member can belong to multiple teams (orgUnits), the member can be assigned a different position for each team.

{     "email": "user@example.com",     "organizations": [         {             ...             "orgUnits": [                 {                     "orgUnitId": "orgunit-0faa-4f37-22bb-1234567890ab",                     "orgUnitName": "Sales team",                     "primary": false,                     "positionId": null,                 ...                },                {                     "orgUnitId": "orgunitc-1d15-4cdf-246b-1234567890ab",                     "orgUnitName": "Sales 1",                     "primary": true,                     "positionId": "position-821e-41af-8142-1234567890ab",                     "positionName": "Manager",                     ...                }             ]         }     ],     ...}

User type {#user-type}

User types (user-types) are an attribute used to grant a member different permissions, such as permission to use services, access restrictions in the organization chart, and sharing restrictions in a drive or board. You can manage user types using the following API operations.

User types are managed by domain. You can specify and get a member's user type using an automatically assigned userTypeId.

{    "email": "user@example.com",    "userTypeId": "employmenttype-75b9-48dd-917a-1234567890ab",    "usertypeName": "Contract employee"

Custom field {#custom-field}

Custom fields (custom-fields), such as links, can be additionally assigned to a member. You can manage custom fields using the following API operations.

You can add up to 5 custom fields per domain. Members can add up to 100 values using the custom fields added to the domain.

{     "email": "user@example.com",     "customFields": [         {             "customFieldId": "customfield-36fe-4b1a-af0e-1234567890ab",             "value": "It changes the work culture",             "link": null,             "customFieldExternalKey": "CustomFldProject"         },         {             "customFieldId": "customfield-36fe-4b1a-af0e-1234567890ab",             "value": "Health comes first before anything.",             "link": null,             "customFieldExternalKey": "CustomFldProject"         }     ],     ...}

Caution

• We recommend that you use member custom properties (user-custom-properties) rather than custom fields. Using custom fields prevents you from accessing new features only available with member custom properties (user-custom-properties).
• Custom fields are automatically migrated to member custom properties.
  • customFieldExternalKey → fieldName (fieldName is automatically created if there is no customFieldExternalKey value.)
  • customFieldId → customPropertyId
  • customFieldName → displayName
• Parameters that do not exist in custom fields are created with default values in member custom properties.
  • multiValued: true
  • mandatory: false
  • readAccessType: ALL
  • writeAccessType: ADMIN

Member custom property {#user-custom-properties}

Member custom properties (user-custom-properties) can be additionally defined for a member. You can manage member custom properties using the following API operations.

You can add up to 50 member custom properties per domain. If multivalued for a custom property is true, you can add up to 10 values for the property. The types of a custom property include text, link, number, and date, where you can specify a list of options for the text type. You can specify whether it is mandatory, and the read and write permissions for each custom property. You can also specify whether each property can have a single value or multiple values.

You can set or get member custom properties using the customProperties field of the Members API.

{  "email": "user@example.com",  "customProperties": {    "field_string": "string",    "field_string_multiValued": [      "string"    ],    "field_string_option": "optionName1",    "field_string_multiValued_option": [      "optionName1"    ],    "field_date": "YYYY-MM-DD",    "field_date_multiValued": [      "YYYY-MM-DD"    ],    "field_integer": 123,    "field_integer_multiValued": [      123    ],    "field_link": {      "text": "string",      "link": "string"    },    "field_link_multiValued": [      {        "text": "string",        "link": "string"      }    ]  },  ...}

Caution

• When a new property is created using member custom properties (user-custom-properties):
  • It is accessible only if multiValued is true and propertyType is STRING or LINK in customFields of Members. Note that even if propertyType is STRING, the property is not accessible if there are options values.
  • If customFields and customProperties for Members are specified at the same time, customProperties takes priority over customFields.

Status (profile-statuses) {#profile-status}

A member's status is indicated by an icon in the organization chart, the profile, and the member list in a message room. You can manage statuses using the following API operations.

Statuses are managed by domain. The default values, BUSY, AWAY, LEAVE_OFFICE, and DELETE` cannot be changed or deleted. You can add up to 10 user status values, including the default values.
For more information, see Manage member statuses.

Update and get external keys {#externalkey-bulk-manage}

You can update or get external keys using the following API operations.

Organization sync {#org-sync}

Organization sync is the process of synchronizing the customer's team information with LINE WORKS's. The Directory API helps you perform organization sync.

Organization sync requires the following:

• Client app that covers the directory scope
• Service account
• Organization Sync settings in the Developer Console (optional)

Organization sync menus {#org-sync-menu}

The following settings are available under Organization Sync in the Developer Console.

Enable organization sync {#org-sync-setting}

Turn On the items to sync, such as Organization/Member, Level/Position, Group, User type, Language/Time Zone, and Sync Status. If you want to allow members to concurrently hold more than one position in different domains, you should also turn On the items to sync for the secondary domain. Depending on the Organization Sync settings, LINE WORKS features are limited as follows:

Restrictions in the LINE WORKS Admin {#admin-operation-dependent}

• If Setting for use of Organization Syncing is On, members who have the status of "Approval Pending" are deleted, and Invite member in the LINE WORKS Admin is automatically disabled.
• If Organization/Member is On, members and teams are read only in the LINE WORKS Admin. If the field for allowing the team features is selected, each of them can be enabled or disabled in the LINE WORKS Admin.
• If Level/Position is On, Member > Position/Level is not displayed in the LINE WORKS Admin.
• If Group is On, basic group information cannot be edited in the LINE WORKS Admin. If the field for allowing the group features is selected, each of them can be enabled or disabled in the LINE WORKS Admin.
• If User Type is On, Member > User Type is not displayed in the LINE WORKS Admin.

Restrictions on members {#user-operation-related}

• If Organization/Member is On, you can choose whether to allow members to edit their profile images.
• If Language is On, a member cannot set the language and time zone field.
• If Sync Status is On, a member cannot set the status field.

Access organization sync items {#org-sync-access}

You can identify and access each item of teams, members, groups, user types, levels, positions, and statuses in the following ways:

• Use a resource ID (recommended): To access these resources, use a resource ID that is automatically assigned when each item is created.
• Use external key mapping: You can additionally specify an ID that is mapped with each item of teams, members, groups, user types, levels, positions, and statuses to connect with the groupware information in use. An external key cannot contain the special characters, % and , and must be unique within a tenant or domain as shown below:
  • For teams, members, groups, and user types: It must be unique within a tenant.
  • For levels and positions: It must be unique within a domain.

The Directory API can use a resource ID or external key mapping to access resources.

External key mapping {#external-key-mapping}

You can download and edit the entire information for each item, and then upload it for mapping.

1. Select Organization Sync in the Developer Console.
2. Click DOWNLOAD on each External Key Mapping section.
3. Enter external keys in the downloaded CSV file and save it.
4. Click UPLOAD to upload the changed file.
5. Preview the uploaded file and correct any duplicate external keys.
6. Click Save.

Custom URL {#custom-url}

This menu opens the specified custom URL in the organization chart popup, email contacts and personal information popup. For popups, include a member name in the #SEARCHTEXT# parameter.

Note

• You can set a custom URL regardless of Organization Sync or API settings.

Order of sync batch processing {#org-sync-by-api}

After all preparations are completed, you can now use the Directory API.

• It is recommended to process the organization sync batch in the following order: Level/Position/User Type → Team → Member → Group. For example, a team must be set before members are added.

[Figure Organization sync batch]

• Please perform organization syncing as a daily batch.
• When a failure occurs during the batch process, you can handle it according to your company's rollback policy. We recommend you to carry on with the process if part of a stage, which means syncing part of an organization, fails, and to stop it if the entire stage fails.
• Make sure not to make 5 or more concurrent API calls, and the Directory API must be called in a single thread.
• When you update member or group information, integrate only the updated information to avoid any unnecessary work. Example) When only some teams need to be renamed
• You must implement logic to handle a failed API call.
• It is necessary to build a log management or monitoring system to detect an API call failure.