Directory API

Directory API では、ユーザー (メンバー) や組織、グループなど、管理者画面で「メンバー」メニューにまとめられている利用者や組織に関するリソースを取得・更新できます。Directory API で取り扱うことができるリソースは以下のとおりです。

• ユーザー (メンバー) (users)
• グループ (groups)
• 組織 (orgunits)
• 職級 (levels)
• 役職 (positions)
• 利用権限タイプ (user-types)
• カスタムフィールド (custom-fields) ※ 廃止予定
• ユーザーカスタムプロパティ (user-custom-properties)
• ステータス (profile-statuses)

注意
利用権限タイプは、employmentType から userType に変更されました。
利用権限タイプに関する API URL またはプロパティ名として、employment-type または employmentType に代えて、user-type または userType を使用してください。

directory Scope により、これらの情報のすべてを操作できます。

また、ユーザーのみを操作できる user Scope、 グループのみを操作できる group Scope、組織のみを操作できる orgunit Scope が用意されています。

User Account 認証または Service Account 認証 (JWT) で取得した Access Token で利用できます。

注意

• フリープランでは、user.read、group.read、orgunit.read、user.email.read、user.profile.read のみが利用できます。directory、directory.read、user、group、orgunit は利用できません。

注意

• Directory API を用いてドメインのリソースを管理する場合には、Service Account 認証による利用をおすすめします。
  • 最高管理者を除く管理者は、通常のユーザーと同様に、ユーザーとして与えられた権限に基づいて、自身の情報など限定的なリソースに限り参照・管理ができます。与えられた管理権限に基づいてドメイン内のすべてのリソースにアクセスできるわけではありません。
  • グループ会社環境では、ドメインの最高管理者であっても、原則としてテナント内の他ドメインのリソースを参照・管理できません。

リソースの指定について {#designate-resource}

API を利用してユーザー、グループ、組織、職級、役職、利用権限タイプ、カスタムフィールド、ユーザーカスタムプロパティのリソースにアクセスする際には、以下の方法でリソースを指定・識別できます。

1. リソース ID {#resource-id}

リソース ID は、各リソースを作成した際にシステムが割り当てる一意の ID です。 リソース ID には以下の特徴があることから、API を利用してリソースを指定・識別する場合には、リソース ID の利用をおすすめします。

• 各リソースは、かならずリソース ID を持つ
• リソース ID は、リソースに対して永続的な値となる
• リソース ID は、一意であることが保証されている
• API がリソースを返す場合には、かならずリソース ID が含まれる

2. External Key {#external-key}

External Key は、LINE WORKS の各リソースに対して API 利用者、または管理者が割り当てることのできる任意の値です。

LINE WORKS のリソースの External Key として、社内システムなどの対応するオブジェクトが持つ ID を割り当てることで、LINE WORKS と社内システムなどで同じ ID を利用してアクセスできます。

External Key は、API または Developer Console > 組織連携 を利用して割り当てます。
API を用いた External Key の一括登録は External Key の一括登録と一覧 を参照してください。

External Key を使用してリソースを指定する場合には、以下の形式で記載します。

externalKey:ExternalKeyの値

External Key の制限 {#external-key-limitation}

リソースタイプにより、External Key に使用できる文字や、値を一意なるように割り当てが必要な範囲 (重複できない範囲) があります。

それぞれの制限は以下の表の通りです。

3. ログイン ID {#login-id}

ユーザーリソースは、ユーザーのログイン ID で指定できます。

ユーザー (メンバー) (users) {#user}

ユーザーは、LINE WORKS におけるメンバーに対応したオブジェクトです。

注意
API によるプロパティの取得・設定についても、管理項目 設定などのサービスによる制約に従います。

参考
メンバーには、awaiting（待機中）、pending（登録待ち）、using（使用中）、suspended（一時停止）、deleted（削除）の 6 つの状態があります。 メンバーの状態は、ユーザー一覧の取得 または ユーザーの取得 API より確認できます。

状態	Parameter	Description
awaiting	isAwaiting	待機中。利用開始日 (activationDate) 前の状態。 利用開始日に pending (SSO 連携を構成している場合には using) に変更される。
pending	isPending	登録待ち。 管理者により追加されたユーザーが、最初のログインをしていない状態を意味する。
using	n/a	使用中。
suspended	isSuspended	一時停止。 ログインはできないが、ユーザーのデータは削除されずに維持される。
deleted	isDeleted	削除。 ユーザーの削除から 7 日間、削除状態で維持され、7 日経過するとデータが削除される。

ユーザーの登録・編集 {#add-update-user}

ユーザーの登録 (追加) や編集を行います。
パスワードは、ユーザーの登録時にのみ指定できます。

ユーザー一覧の取得 {#get-user-list}

ドメイン内のユーザーの一覧を取得します。ソートやフィルタを行うことも可能です。

ユーザー情報の取得 {#get-user-information}

ユーザー情報の取得では、利用ケースに応じて、限定されたフィールドのみを含むレスポンスが取得できます。

ユーザー情報の取得には以下の3種類のパターンがあります。全て同じエンドポイントを利用しますが、Access Token を取得した際に指定した Scope によって取得される情報が異なります。

ユーザーの削除 {#delete-user}

ユーザーの削除には、通常の削除と、即時削除があります。通常の削除を行ったユーザーは、削除後 7 日以内であれば、削除を取り消すことができます。削除後 7 日が経過した、または即時削除を行ったユーザーは復元できません。

ユーザーの写真の管理 {#manage-user-photo}

ユーザーの写真は、以下の API で管理します。

ファイルのアップロード・ダウンロード方法の詳細は ファイルアップロード / ダウンロード を参照します。

ユーザーステータスの管理 {#manage-user-status}

ユーザーのステータスは以下の API で管理します。
ドメインでのステータスの管理は、ステータス (profile-statuses) を参照します。

ユーザーには、現在のステータスと、予約されたステータスが登録できます。

{    "userProfileStatuses": [        {            "profileStatusId": "AWAY",            "statusMessage": "外出しています。",            "startTime": "2023-05-11T09:00:00+09:00",            "endTime": "2023-05-11T12:00:00+09:00",            ...        }    ]}

外部ユーザーとのトーク権限の管理 {#manage-link-to-externaluser}

外部の LINE WORKS ユーザー、または LINE ユーザーとのトーク権限を管理できます。

外部 LINE WORKS ユーザーとのトーク権限管理は以下の API を利用します。

外部 LINE ユーザーとのトーク権限管理は以下の API を利用します。

外部トーク連携の招待用リンクは以下の API で管理します。

注意
これらの API は、user scope で利用します。directory scope では利用できません。

ユーザーの一時停止と休職 {#user-suspend-leaveofabsence}

休職者が出た場合には、ユーザーを休職・一時停止に設定できます。
休職に設定されたユーザーは、プロフィールと組織図に休職情報が表示されます。また、API で取得したユーザー情報では leaveOfAbsence として示されます。
一時停止されたユーザーは、LINE WORKS にログオンできなくなります。API で取得したユーザー情報では isSuspended として示されます。

ユーザーの管理 {#manage-user}

グループ (groups) {#group}

プロジェクトや社内サークル活動など、コミュニケーションのためのグループ groups を作成できます。
グループは以下の API で管理します。

グループでは、トークやノート、予定、タスク、フォルダなどの機能を利用できます。
グループはドメインで管理します。
グループには、グループを管理するグループマスターを 1 人以上指定します。
グループのメンバーには、ユーザー、組織、または他のグループを追加できます。

{    "groupName": "検証",    "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        }    ],...}

組織 (orgunits) {#orgunit}

会社の組織情報に合わせて、LINE WORKSに組織 orgunits を登録できます。プロジェクトや社内サークルなどは、組織ではなく グループ を利用します。
組織は、以下の API で管理します。

組織では、トークやノート、予定、タスク、フォルダなどの機能を利用できます。
組織はドメインで管理します。
ユーザーが属する組織は、組織リスト orgUnits で確認・構成できます。

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

組織図の閲覧制限 {#orgunit-access-restrict}

組織図には、閲覧の制限設定を行うことができます。
ユーザーの組織図閲覧制限の設定は以下の API を利用します。

利用権限タイプの組織図閲覧制限の設定は以下の API を利用します。

組織の組織図閲覧制限の設定は以下の API を利用します。

閲覧制限は、ユーザー、利用権限タイプ、組織 の順に適用されます。
組織図の閲覧が制限されたユーザー、制限された利用権限タイプが割り当てられたユーザー、制限された組織に属するユーザーは、制限に従い、組織図を参照できない、自身が所属する組織のみ、または自身が所属する組織と許可された組織のみを参照できます。

職級 (levels) {#level}

職級 levels は、ユーザーに付与された職務上のレベルです。
職級は以下の API で管理します。

職級は、ドメインで構成します。
ユーザーの職級は、職級 ID levelId で指定・取得できます。

{   "email": "user@example.com",   "organizations": [      {         "domainId": 12345678,         "organizationName": "サンプル商店",         "levelId": "level-1999-4212-7979-1234567890ab",         "levelName": "役員"...

役職 (positions) {#position}

役職 positions は、ユーザーに付与された職務上の責任の単位です。
役職は、以下の API で管理します。

役職は、ドメインで構成します。
ユーザーは、複数の組織 orgUnits に所属でき、所属する組織ごとに役職 positions を割り当てられます。

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

利用権限タイプ (user-types) {#user-type}

利用権限タイプ user-types は、サービスの利用や、組織図の閲覧制限、ドライブ・掲示板における共有範囲の例外管理など、主に権限の管理に用いられる、ユーザーの属性です。

注意
利用権限タイプは、employmentType から userType に変更されました。
利用権限タイプに関する API URL またはプロパティ名として、employment-type または employmentType に代えて、user-type または userType を使用してください。

利用権限タイプは、以下の API で管理します。

利用権限タイプは、ドメインで構成します。
ユーザーの利用権限タイプは、利用権限タイプ ID userTypeId で指定・取得できます。

{   "email": "user@example.com",   "userTypeId": "usertype-75b9-48dd-917a-1234567890ab",   "userTypeName": "社員"

カスタムフィールド (custom-fields) {#custom-field}

カスタムフィールド custom-fields は、ユーザーに追加で割り当てることができる文字列又はリンク情報です。
カスタムフィールドは、以下の API で管理します。

{    "email": "user@example.com",    "customFields": [        {            "customFieldId": "customfield-36fe-4b1a-af0e-1234567890ab",            "value": "働き方改革",            "link": null,            "customFieldExternalKey": "CustomFldProject"        },        {            "customFieldId": "customfield-36fe-4b1a-af0e-1234567890ab",            "value": "DX推進",            "link": null,            "customFieldExternalKey": "CustomFldProject"        }    ],    ...}

注意
カスタムフィールド API は、2026年7月下旬を目処に廃止を予定しています。
今後は、ユーザーカスタムプロパティ API を利用してください。

• カスタムフィールド API では、ユーザーカスタムプロパティ API でのみ提供される一部の機能の設定・参照ができません。
• カスタムフィールドは、ユーザーカスタムプロパティに自動的に移行されます。
• その際に、以下の Property は設定が引き継がれます。
  • customFieldExternalKey -> fieldName
    • externalKey が指定されていない場合には、fieldName は自動的に割り当てられます
  • customFieldId -> customPropertyId
  • customFieldName -> displayName
• ユーザーカスタムプロパティでの新たな property は、以下の既定値で設定されます。
  • multiValued: true
  • mandatory: false
  • readAccessType: ALL
  • writeAccessType: ADMIN

ユーザーカスタムプロパティ (user-custom-properties) {#user-custom-properties}

ユーザーカスタムプロパティ user-custom-properties は、ユーザーに追加で割り当てることができるカスタム項目です。
ユーザーカスタムプロパティは、以下の API で管理します。

ユーザーカスタムプロパティは、ドメイン単位で最大 50 個まで登録できます。multiValued のユーザーカスタムプロパティには、最大 10 個の値を指定できます。
ユーザーカスタムプロパティのタイプには、テキスト STRING、リンク LINK、数値 INTEGER、日付 DATE があり、テキストに対してはオプションリスト options を指定することもできます。
ユーザーカスタムプロパティには、必須/任意 mandatory、読み取り権限 readAccessType、および書き込み権限 writeAccessType を設定できます。 また、複数値の許容 multiValued も設定できます。

ユーザーカスタムプロパティは、ユーザー (メンバー) (users) API の customProperties プロパティにより、設定・参照することができます。

{  "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"      }    ]  },  ...}

注意

• メンバーカスタムフィールドを新規作成した場合、multiValued = true で、propertyType = STRING または LINK のフィールドについてのみ、user の customField で取り扱うことができます。ただし、propertyType = STRING であっても、options が設定されている場合には customField で取り扱うことはできません。
• user オブジェクトで customFields と customProperties の両方を指定した場合には、customProperties が優先されます。

ステータス (profile-statuses) {#profile-status}

ステータスを設定すると、組織図、プロフィールやトークルームのメンバーリストに、ステータスに応じたアイコンが表示されます。
ステータスは以下の API で管理します。

ステータスはドメインで管理します。既定で用意されている BUSY、AWAY、LEAVE_OFFICE、ABSENCE は、変更・削除できません。カスタムのステータスを、6 個まで構成できます。
ユーザーのステータス管理は ユーザーステータスの管理 を参照して下さい。

External Key の一括登録と一覧 {#externalkey-bulk-manage}

External Key を一括登録する際は以下の API を利用します。

Directory API を使った組織連携について {#org-sync-by-api}

組織連携バッチの流れです。

• 組織連携は日 (day) 単位でバッチ処理することを推奨します。
• 各段階で失敗した際のロールバックはクライアントの社内ポリシーに従って適用してください。

注意

• 同一リソースに対する書き込みリクエスト (POST/PUT/PATCH/DELETE) は同時に行わないでください。