APIリファレンスメンバー

メンバー

社員・役員・業務委託のスタッフなど会社の人

エンドポイント

GET/v1/people
POST/v1/people
GET/v1/people/{id}
PATCH/v1/people/{id}

GET/v1/people

メンバー（会社の人）の一覧・検索

ワークスペースに登録された会社の人（社員・役員・業務委託のスタッフなど）を返します。Tooonにログインする利用者とは別です。email は大文字小文字を区別せずに完全一致で絞り込みます。

権限 people:readnextCursor で続き

クエリ

emailstring
メールアドレスで絞り込み（完全一致）
320文字まで
externalRefstring
呼び出し元システムでの識別子で絞り込み
200文字まで
partnerIdstring
つながっているパートナーで絞り込み
100文字まで
limitinteger
1回に返す件数（既定 50、最大 100）
1〜100
cursorstring
前の応答の nextCursor
100文字まで

返る項目data の中身 · 200

idstring
externalRefstring | null
namestring
emailstring | null
phonestring | null
jobTitlestring | null
departmentstring | null
kindenum
corporate＝コーポレートメンバー（社員・役員・家族など事業主の内側の人）、partner＝パートナーメンバー（業務委託など）
corporatepartner
statusenum
activeinactive
partnerIdstring | null
業務委託などでお金の約束があるとき、その相手のパートナー
businessCardIdstring | null
この人のデジタル名刺。まだ無ければ null
createdAtstring
updatedAtstring

起こりうるエラー共通のエラー

400invalid_request
送った値が正しくない。message にどこが違うかが入ります
403insufficient_scope
キーにこの入口の権限（scope）が付いていない。requiredScopes に必要な権限が入ります

GET/v1/people

curl https://tooon.app/api/v1/people \
  -H "Authorization: Bearer $TOOON_API_KEY"

レスポンス

{
  "data": [
    {
      "id": "clx8k2m0a0001",
      "externalRef": "staff-0001",
      "name": "山田 太郎",
      "email": "…",
      "phone": "…",
      "jobTitle": "…",
      "department": "…",
      "kind": "corporate",
      "status": "active",
      "partnerId": "clx8k2m0a0001",
      "businessCardId": "clx8k2m0a0001",
      "createdAt": "2026-11-01T09:00:00.000Z",
      "updatedAt": "2026-11-01T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}

POST/v1/people

メンバー（会社の人）を登録する（externalRef で上書き）

会社の人（社員・役員・業務委託のスタッフなど）を登録します。Tooonにログインする必要はありません。登録した人はTooonの「メンバー」にも出て、画面から直せます。

externalRef を付けると、同じ値で何度呼んでも1人です。2回目からは、本文に含めた項目だけを書き換えます。

業務委託の人は、パートナー（POST /v1/partners）を登録してから partnerId でつなぐと、請求書作成依頼と名刺が同じ人にまとまります。

権限 people:writeIdempotency-Key

送る項目JSON · 9項目

emailstring (email) | null
320文字まで
phonestring | null
64文字まで
jobTitlestring | null
肩書き
80文字まで
departmentstring | null
所属・部署（表示用）
80文字まで
kindenum
既定 corporate。業務委託などは partner
corporatepartner
statusenum
既定 active。辞めた人は inactive
activeinactive
partnerIdstring | null
業務委託などでお金の約束がある相手のパートナーとつなぐ。null で外します
100文字まで
externalRefstring
呼び出し元システムでの識別子。同じ値なら同じ人として扱います
200文字まで
namestring必須
氏名
200文字まで

返る項目data の中身 · 200

idstring
externalRefstring | null
namestring
emailstring | null
phonestring | null
jobTitlestring | null
departmentstring | null
kindenum
corporate＝コーポレートメンバー（社員・役員・家族など事業主の内側の人）、partner＝パートナーメンバー（業務委託など）
corporatepartner
statusenum
activeinactive
partnerIdstring | null
業務委託などでお金の約束があるとき、その相手のパートナー
businessCardIdstring | null
この人のデジタル名刺。まだ無ければ null
createdAtstring
updatedAtstring

起こりうるエラー共通のエラー

400invalid_request
送った値が正しくない。message にどこが違うかが入ります
403insufficient_scope
キーにこの入口の権限（scope）が付いていない。requiredScopes に必要な権限が入ります

POST/v1/people

curl -X POST https://tooon.app/api/v1/people \
  -H "Authorization: Bearer $TOOON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "externalRef": "staff-0001",
  "name": "山田 太郎"
}'

レスポンス

{
  "data": {
    "id": "clx8k2m0a0001",
    "externalRef": "staff-0001",
    "name": "山田 太郎",
    "email": "…",
    "phone": "…",
    "jobTitle": "…",
    "department": "…",
    "kind": "corporate",
    "status": "active",
    "partnerId": "clx8k2m0a0001",
    "businessCardId": "clx8k2m0a0001",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

GET/v1/people/{id}

メンバー（会社の人）を取得する

権限 people:read

パスの値

idstring必須
メンバー（人）のID
100文字まで

返る項目data の中身 · 200

idstring
externalRefstring | null
namestring
emailstring | null
phonestring | null
jobTitlestring | null
departmentstring | null
kindenum
corporate＝コーポレートメンバー（社員・役員・家族など事業主の内側の人）、partner＝パートナーメンバー（業務委託など）
corporatepartner
statusenum
activeinactive
partnerIdstring | null
業務委託などでお金の約束があるとき、その相手のパートナー
businessCardIdstring | null
この人のデジタル名刺。まだ無ければ null
createdAtstring
updatedAtstring

起こりうるエラー共通のエラー

403insufficient_scope
キーにこの入口の権限（scope）が付いていない。requiredScopes に必要な権限が入ります
404not_found
対象がない、またはこのワークスペースのものではない

GET/v1/people/{id}

curl https://tooon.app/api/v1/people/clx8k2m0a0001 \
  -H "Authorization: Bearer $TOOON_API_KEY"

レスポンス

{
  "data": {
    "id": "clx8k2m0a0001",
    "externalRef": "staff-0001",
    "name": "山田 太郎",
    "email": "…",
    "phone": "…",
    "jobTitle": "…",
    "department": "…",
    "kind": "corporate",
    "status": "active",
    "partnerId": "clx8k2m0a0001",
    "businessCardId": "clx8k2m0a0001",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

PATCH/v1/people/{id}

メンバー（会社の人）を更新する

本文に含めた項目だけを書き換えます。null を送るとその項目を空にします。

権限 people:writeIdempotency-Key

パスの値

idstring必須
メンバー（人）のID
100文字まで

送る項目JSON · 9項目

emailstring (email) | null
320文字まで
phonestring | null
64文字まで
jobTitlestring | null
肩書き
80文字まで
departmentstring | null
所属・部署（表示用）
80文字まで
kindenum
既定 corporate。業務委託などは partner
corporatepartner
statusenum
既定 active。辞めた人は inactive
activeinactive
partnerIdstring | null
業務委託などでお金の約束がある相手のパートナーとつなぐ。null で外します
100文字まで
externalRefstring | null
呼び出し元システムでの識別子。null で外します
200文字まで
namestring
氏名
200文字まで

返る項目data の中身 · 200

idstring
externalRefstring | null
namestring
emailstring | null
phonestring | null
jobTitlestring | null
departmentstring | null
kindenum
corporate＝コーポレートメンバー（社員・役員・家族など事業主の内側の人）、partner＝パートナーメンバー（業務委託など）
corporatepartner
statusenum
activeinactive
partnerIdstring | null
業務委託などでお金の約束があるとき、その相手のパートナー
businessCardIdstring | null
この人のデジタル名刺。まだ無ければ null
createdAtstring
updatedAtstring

起こりうるエラー共通のエラー

400invalid_request
送った値が正しくない。message にどこが違うかが入ります
403insufficient_scope
キーにこの入口の権限（scope）が付いていない。requiredScopes に必要な権限が入ります
404not_found
対象がない、またはこのワークスペースのものではない

PATCH/v1/people/{id}

curl -X PATCH https://tooon.app/api/v1/people/clx8k2m0a0001 \
  -H "Authorization: Bearer $TOOON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "externalRef": "staff-0001"
}'

レスポンス

{
  "data": {
    "id": "clx8k2m0a0001",
    "externalRef": "staff-0001",
    "name": "山田 太郎",
    "email": "…",
    "phone": "…",
    "jobTitle": "…",
    "department": "…",
    "kind": "corporate",
    "status": "active",
    "partnerId": "clx8k2m0a0001",
    "businessCardId": "clx8k2m0a0001",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}