APIを利用する
■API概要
APIを活用することで、業務で利用しているサービスとBYARDのシステム間で連携することができます。システム間で連携することで、例えば以下の様なことができるようになります。
- 業務で利用しているシステム上で特定の操作をした際に、BYARD上でメンバーの招待を自動で行う
- 業務で利用しているシステム上で特定の操作をした際に、BYARD上でテンプレートから案件を自動で開始する
APIは「Standardプラン」「Expertプラン」のお客様のみ利用可能です。
■使用上の注意
- API連携を行うためには、 Standardプランのお客様のみ契約可能な「API連携オプション」のご契約が必要です。
Expertプランのお客様は、オプションではなく標準仕様として利用可能です。
- APIを使用するためには、専用のアカウントを一つ用意いただき、そのアカウントにAPIキーを取得できる機能を弊社にて付与いたします。そのため、APIを使用する際には、一度お問い合わせいただけますようお願いいたします。
- コードの記述方法等に関するサポートは対応致しかねますので、予めご了承くださいませ。
■APIリファレンス
以下のURLからリファレンスを確認することができます。
■エンドポイント
※httpsのみ有効
上記のURLに各機能のリソース（パス）を続けて記入いただくことで、機能を利用することが可能です。
例）メンバー招待する
※リクエスト、レスポンスともにJSON形式をサポートしています。
■認証
APIを使用する際は、APIキー認証により認証を行います。APIキーは以下の手順で取得が可能です。
- [個人設定]をクリックします。
- [API KEY]タブをクリックします。
API KEYの画面はAPI連携オプションをご契約後に、指定された特定のアカウント環境のみに表示されます。（画面の表示対応は弊社にて実施いたします。）
また、API KEYのタブは既に利用中のアカウントには表示することができず、API KEYを確認するための専用のアカウントを一つご用意頂く必要がございます。
- [API KEYをコピーする]をクリックすることで、API KEYの取得ができます。
APIキーの有効期限は半年となっています。有効期限が切れる前にAPIキーの更新が必要となります。
■各機能の詳細
メンバーを招待
リファレンス
基本情報
| 機能概要 | メンバーを招待します。 外部システムの処理をトリガーとしてBYARD内でメンバーの招待ができます。 |
| メソッド | POST |
| リソース | /v1/organizations/{organizationId}/invitations |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
Paramaters（body）
InviteMembersRequestModel 招待するメンバー情報
| キー名 | タイプ | 必須 | 説明 |
| emails | string | 必須 | メールアドレス |
| membershipType | string | 必須 | ユーザー種別 指定できるユーザー種別には以下の5つの値があります。 ユーザー種別の意味については「用語一覧」をご確認ください。 Enum：[ OWNER, ADMINISTRATOR, EDITOR, OPERATOR, GUEST ] OWNER：エディター（組織オーナー） ADMINISTRATOR：エディター（管理者） EDITOR：エディター OPERATOR：オペレーター GUEST：ゲスト |
サンプルコード
レスポンス
Code：201
| キー名 | タイプ | 説明 |
| emails | string | メールアドレス |
| membershipType | string | ユーザー種別 ユーザー種別には以下の5つの値があります。 ユーザー種別の意味については「用語一覧」をご確認ください。 Enum：[ OWNER, ADMINISTRATOR, EDITOR, OPERATOR, GUEST ] OWNER：エディター（組織オーナー） ADMINISTRATOR：エディター（管理者） EDITOR：エディター OPERATOR：オペレーター GUEST：ゲスト |
メンバー一覧を取得
リファレンス
基本情報
| 機能概要 | メンバー一覧の情報を取得します。 メンバーの情報をリストで取得することができます。 |
| メソッド | GET |
| リソース | /v1/organizations/{organizationId}/members |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
レスポンス
Code：200
| キー名 | タイプ | 説明 |
| displayName | string | メンバーの表示名 |
| bio | string | 所属 |
| active | boolean | メンバーの利用ステータス true：有効 false：無効 |
| membershipId | string | ユーザー種別のID Enum：[ 1, 2, 3, 4, 5 ] 1：エディター（組織オーナー） 2：エディター（管理者） 3：エディター 4：オペレーター 5：ゲスト |
| membership | ユーザー種別 以下の配列（type）があります。 | |
| └ type | string | Enum：[ owner, administrator, editor, operator, guest ] owner：エディター（組織オーナー） administrator：エディター（管理者） editor：エディター operator：オペレーター guest：ゲスト |
| organizationId | string | 組織ID |
| accountId | string | アカウントID BYARDでは作成した一つのアカウントで複数の組織に参加することが可能です。このアカウントIDは、最初に作成した一意のアカウントのIDを指します。 |
| createdAt | string($date-time) | 作成日 |
| name | string | ユーザーの名前 ※現在は使用しておおらず、すべてnullの状態で返ってきます。今後の機能拡張において、使用する可能性のあるキーとなります。 |
| id | string | メンバーID 組織に参加しているメンバーのIDです。一つのアカウントIDで複数の組織に参加している場合、同じアカウントであっても参加する組織ごとに異なるメンバーIDが割り当てられます。 |
| account | string | メンバー情報 以下の配列（email）があります。 |
| string | メールアドレス | |
| primary | boolean | アカウント新規作成後に初回ログインで使われたか否か true：この組織で初回ログインしたアカウント false：他の組織で初回ログインしたアカウント |
| updatedAt | string($date-time) | 最終更新日 |
メンバー情報の取得（ID単位）
リファレンス
基本情報
| 機能概要 | 指定したIDのメンバー情報を取得します。 |
| メソッド | GET |
| リソース | /v1/organizations/{organizationId}/members/{memberId} |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
memberId メンバーID
| タイプ | 必須 | 説明 |
| string | 必須 | メンバーIDを指定します。 メンバーIDは「メンバー一覧を取得」のエンドポイントより取得することができます。 |
レスポンス
Code：200
| キー名 | タイプ | 説明 |
| displayName | string | メンバーの表示名 |
| bio | string | 所属 |
| active | boolean | メンバーの利用ステータス true：有効 false：停止 |
| membershipId | string | ユーザー種別のID Enum：[ 1, 2, 3, 4, 5 ] 1：エディター（組織オーナー） 2：エディター（管理者） 3：エディター 4：オペレーター 5：ゲスト |
| membership | ユーザー種別 以下の配列（type）があります。 | |
| └ type | string | Enum：[ owner, administrator, editor, operator, guest ] owner：エディター（組織オーナー） administrator：エディター（管理者） editor：エディター operator：オペレーター guest：ゲスト |
| organizationId | string | 組織ID |
| accountId | string | アカウントID BYARDでは作成した一つのアカウントで複数の組織に参加することが可能です。このアカウントIDは、最初に作成した一意のアカウントのIDを指します。 |
| createdAt | string($date-time) | 作成日 |
| name | string | ユーザーの名前 ※現在は使用しておおらず、すべてnullの状態で返ってきます。今後の機能拡張において、使用する可能性のあるキーとなります。 |
| id | string | メンバーID 組織に参加しているメンバーのIDです。一つのアカウントIDで複数の組織に参加している場合、同じアカウントであっても参加する組織ごとに異なるメンバーIDが割り当てられます。 |
| account | メンバー情報 以下の配列（email）があります。 | |
| string | メールアドレス | |
| primary | boolean | アカウント新規作成後に初回ログインで使われたか否か true：この組織で初回ログインしたアカウント false：他の組織で初回ログインしたアカウント |
| updatedAt | string($date-time) | 最終更新日 |
メンバーステータスの変更
リファレンス
基本情報
| 機能概要 | メンバーのステータスを変更します。 現在はメンバーのステータスを停止にすることができます。 |
| メソッド | PUT |
| リソース | /v1/organizations/{organizationId}/members/{memberId}/status |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
memberId メンバーID
| タイプ | 必須 | 説明 |
| string | 必須 | メンバーIDを指定します。 メンバーIDは「メンバー一覧を取得」のエンドポイントより取得することができます。 |
Paramaters（body）
UpdateMemberStatusRequestModel メンバーステータス
| キー名 | タイプ | 必須 | 説明 |
| status | string | 必須 | ステータス ステータスには以下の値を指定することができます。 Enum：[ INACTIVE ] INACTIVE：停止 |
サンプルコード
レスポンス
Code：200
| キー名 | タイプ | 説明 |
| memberId | string | メンバーID |
| status | string | ステータス ステータスには以下の値があります。 Enum：[ INACTIVE ] INACTIVE：停止 |
テンプレート一覧を取得
リファレンス
基本情報
| 機能概要 | テンプレート一覧の情報を取得します。 テンプレートの情報をリストで取得することができます。 |
| メソッド | GET |
| リソース | /v1/organizations/{organizationId}/stream-templates |
Paramaters（query）
ownerMemberId オーナーのメンバーID
| タイプ | 必須 | 説明 |
| string | テンプレートのオーナーのメンバーIDを指定します。 指定したメンバーがオーナーとなっているテンプレートのリストを取得することができます。 メンバーIDは「メンバー一覧を取得」のエンドポイントより取得することができます。 |
collaboratorMemberId 共有者のメンバーID
| タイプ | 必須 | 説明 |
| string | テンプレートの共有者のメンバーIDを指定します。 指定したメンバーが共有者となっているテンプレートのリストを取得することができます。 メンバーIDは「メンバー一覧を取得」のエンドポイントより取得することができます。 |
name テンプレート名
| タイプ | 必須 | 説明 |
| string | テンプレート名を指定します。 指定した名前を含むテンプレートのリストを取得することができます。 |
archived アーカイブ
| タイプ | 必須 | 説明 |
| string | テンプレートのアーカイブを指定します。 アーカイブを指定する際は、以下の値を指定します。 true・false true：アーカイブされている false：アーカイブされていない |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
レスポンス
Code：200
| キー名 | タイプ | 説明 |
| archived | string | アーカイブ true：アーカイブされている false：アーカイブされていない |
| name | string | テンプレート名 |
| id | string | テンプレートID |
| confidential | boolean | コンフィデンシャルのステータス true：コンフィデンシャルが有効 false：コンフィデンシャルが無効 |
| tags | タグの情報 以下の配列（items）があります。 | |
| └ items | タグの情報 以下の配列（tag）があります。 | |
| └ tag | タグの詳細情報 以下の配列（name,id）があります。 | |
| └ name | string | タグ名 |
| └ id | string | タグID |
テンプレートから案件を作成
リファレンス
基本情報
| 機能概要 | テンプレートから案件を作成します。 外部システムの処理をトリガーとして指定のテンプレートから案件を開始することができます。 |
| メソッド | POST |
| リソース | /v1/organizations/{organizationId}/stream-templates/{streamTemplateId}/generate |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
streamTemplateId テンプレートID
| タイプ | 必須 | 説明 |
| string | 必須 | テンプレートIDを指定します。 テンプレートIDはBYARDのURL内のパラメータ（s=XX）が該当します。 https://app.byard.io/organization/streamTemplate/workgroupTemplate?o=組織ID&s=テンプレートID&wg=ワークグループID |
Paramaters（body）
CreateEntireStreamFromTemplateRequestModel 作成する案件の情報
| キー名 | タイプ | 必須 | 説明 |
| temporaryMemberIds | テンポラリユーザーの情報 以下の配列（id, memberId）があります。 | ||
| └ id | string | テンポラリユーザーのID ※「テンプレート情報の取得（ID単位）」のエンドポイントより取得できる予定です（エンドポイントは現在開発中です） | |
| └ memberId | string | メンバーID テンポラリユーザーに指定するメンバーのメンバーIDを指定します。 | |
| baseDate | string($date) | 必須 | 基準日 案件開始時の基準日を指定します。 |
| dueDate | string($date) | 必須 | 期限日 案件の期限日を指定します。 |
| streamName | string | 必須 | ストリーム名 作成する案件の名前を指定します。 |
| startDate | string($date) | 必須 | 開始日 案件の開始日を指定します。 |
サンプルコード
レスポンス
Code：201
| キー名 | タイプ | 説明 |
| streamId | string | ストリームID 作成された案件のIDです。 |
案件一覧を取得
リファレンス
基本情報
| 機能概要 | 案件一覧の情報を取得します。 案件の情報をリストで取得することができます。 |
| メソッド | GET |
| リソース | /v1/organizations/{organizationId}/streams |
| 留意点 | APIを実行するユーザーが関与していないコンフィデンシャル案件の情報は取得することができません。コンフィデンシャル案件の情報を取得したい場合は、APIを実行するユーザーをコンフィデンシャル案件のオーナーや共有者などに追加することで、関係者として扱われ情報を取得することが可能です。 |
Paramaters（query）
name 案件名
| タイプ | 必須 | 説明 |
| string | 案件名を指定します。 指定した名前を含む案件のリストを取得することができます。 |
stakeholderMemberId 関係者のメンバーID
| タイプ | 必須 | 説明 |
| string | メンバーIDを指定します。 指定したメンバーが関係する案件のリストを取得することができます。 メンバーIDは「メンバー一覧を取得」のエンドポイントより取得することができます。 |
status ステータス
| タイプ | 必須 | 説明 |
| string | 案件のステータスを指定します。 ステータスを指定する際は、以下の値を指定します。 EXECUTED・OPEN EXECUTED：完了 OPEN：未完了 |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
レスポンス
Code：200
| キー名 | タイプ | 説明 |
| template | 案件に紐づくテンプレート情報 以下の配列（displayType,name,id,confidential）があります。 | |
| └ displayType | テンプレートの閲覧制限のステータス Enum：[ ALLOWED, NOT_ALLOWED, FETCH_FAILED ] ALLOWED：閲覧可能 NOT_ALLOWED：閲覧不可 FETCH_FAILED：情報取得失敗 | |
| └ name | string | テンプレート名 |
| └ id | string | テンプレートID |
| └ confidential | boolean | コンフィデンシャルのステータス（テンプレート） true：コンフィデンシャルが有効 false：コンフィデンシャルが無効 |
| dueDate | string($date) | 期限日 |
| name | string | 案件名 |
| executionDate | string($date) | 完了日（実行日） |
| id | string | 案件ID |
| startDate | string($date) | 開始日 |
| confidential | boolean | コンフィデンシャルのステータス（案件） true：コンフィデンシャルが有効 false：コンフィデンシャルが無効 |
| status | string | ステータス
executed：完了 open：未完了 |
| tags | タグの情報 以下の配列（items）があります。 | |
| └ items | タグの情報 以下の配列（tag）があります。 | |
| └ tag | タグの詳細情報 以下の配列（name,id）があります。 | |
| └ name | string | タグ名 |
| └ id | string | タグID |
案件情報の取得（ID単位）
リファレンス
基本情報
| 機能概要 | 指定した案件IDの案件情報を取得します。 |
| メソッド | GET |
| リソース | /v1/organizations/{organizationId}/streams/{streamId} |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
streamId 案件ID
| タイプ | 必須 | 説明 |
| string | 必須 | 案件IDを指定します。 案件IDはBYARDのURL内のパラメータ（s=XX）が該当します。 https://app.byard.io/organization/streamTemplate/workgroupTemplate?o=組織ID&s=案件ID&wg=ワークグループID 案件IDは「案件一覧を取得」のエンドポイントより取得するも可能です。 |
レスポンス
Code：200
| キー名 | タイプ | 説明 |
| template | 案件に紐づくテンプレート情報 以下の配列（id）があります。 | |
| └ id | string | テンプレートID |
| dueDate | string($date) | 案件の期限日 |
| executionDate | string($date) | 案件の完了日 |
| description | string | 紐づくテンプレート側で設定されているテンプレートの説明文 |
| slackChannelIds | string | 案件と連携しているSlackチャンネルのID |
| owners | 案件のオーナー情報 以下の配列（items）があります。 | |
| └ items | 案件のオーナー情報 以下の配列（member）があります。 | |
| └ member | 案件のオーナーの詳細情報 以下の配列（id）があります。 | |
| └ id | string | メンバーID |
| createdType | string | 案件の作成方法 Enum：[ MANUAL, SCHEDULE, EXTERNAL ] MANUAL：通常の作成 SCHEDULE：自動作成機能による自動作成 EXTERNAL：APIによる自動作成 |
| tags | タグの情報 以下の配列（items）があります。 | |
| └ items | タグの情報 以下の配列（tag）があります。 | |
| └ tag | タグの詳細情報 以下の配列（name,id）があります。 | |
| └ name | string | タグ名 |
| └ id | string | タグID |
| organizationId | string | 組織ID |
| createdAt | string($date-time) | 案件の作成日 |
| executor | 案件の完了者 以下の配列（id）があります。 | |
| └ id | string | メンバーID 案件完了したメンバーのID |
| name | string | 案件名 |
| collaborators | 案件の共有者情報 以下の配列（items）があります。 | |
| └ items | 案件の共有者情報 以下の配列（member）があります。 | |
| └ member | 案件の共有者の詳細情報 以下の配列（id）があります。 | |
| └ id | string | メンバーID |
| id | string | 案件ID |
| strict | boolean | ストリクトモードのステータス true：ストリクトモードが有効 false：ストリクトモードが無効 |
| startDate | string($date) | 案件の開始日 |
| confidential | boolean | コンフィデンシャルのステータス true：コンフィデンシャルが有効 false：コンフィデンシャルが無効 |
| status | string | ステータス
executed：完了 open：未完了 |
| updatedAt | string($date) | 案件の更新日 |
案件ステータスの変更
リファレンス
基本情報
| 機能概要 | 案件のステータスを変更します。 案件のステータスを「未完了」「完了」のいずれかに変更することが可能です。 |
| メソッド | PUT |
| リソース | /v1/organizations/{organizationId}/streams/{streamId}/status |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
streamId 案件ID
| タイプ | 必須 | 説明 |
| string | 必須 | 案件IDを指定します。 案件IDはBYARDのURL内のパラメータ（s=XX）が該当します。 https://app.byard.io/organization/streamTemplate/workgroupTemplate?o=組織ID&s=案件ID&wg=ワークグループID 案件IDは「案件一覧を取得」のエンドポイントより取得するも可能です。 |
Paramaters（body）
UpdateStreamStatusRequestModel 案件ステータス
| キー名 | タイプ | 必須 | 説明 |
| force | boolean | 未完了のワークがある際に案件を完了にするか否かの確認 true：完了にする false：完了にしない trueの場合、案件が完了になると同時に、未完了のワークは自動的にスキップとなります。 falseの場合、400エラーが返り案件は完了されません。 | |
| status | string | 必須 | ステータス ステータスには以下の値を指定することができます。 Enum：[ OPEN, EXECUTED ] OPEN：未完了 EXECUTED：完了 |
サンプルコード
レスポンス
Code：200
| キー名 | タイプ | 説明 |
| streamId | string | 案件ID |
| status | string | ステータス ステータスには以下の値があります。 Enum：[ OPEN, EXECUTED ] OPEN：未完了 EXECUTED：完了 |
ワーク一覧を取得
リファレンス
基本情報
| 機能概要 | 案件内にあるワークの情報をリストで取得します。 |
| メソッド | GET |
| リソース | /v1/organizations/{organizationId}/works |
Paramaters（query）
streamId 案件ID
| タイプ | 必須 | 説明 |
| string | 必須 | 案件IDを指定します。 案件IDはBYARDのURL内のパラメータ（s=XX）が該当します。 https://app.byard.io/organization/streamTemplate/workgroupTemplate?o=組織ID&s=案件ID&wg=ワークグループID 案件IDは「案件一覧を取得」のエンドポイントより取得するも可能です。 |
Paramaters（path）
organizationId 組織ID
| タイプ | 必須 | 説明 |
| string | 必須 | 組織IDを指定します。 組織IDはBYARDのURL内のパラメータ（o=XX）が該当します。 https://app.byard.io/organization/member/work?o=組織ID |
レスポンス
Code：200
| キー名 | タイプ | 説明 |
| dueDate | string($date) | 期限日 |
| name | string | ワーク名 |
| executionDate | string($date) | 完了日（実行日） |
| links | 連携カードの情報 以下の配列（id,type）があります。 | |
| └ id | string | 連携カードID |
| └ type | string | ワークカードのタイプ Enum：[ STREAM ] STREAM：連携カード |
| id | string | ワークID |
| startDate | string($date) | 開始日 |
| status | string | ステータス
executed：完了
skip：スキップ open：未完了 |