APIリファレンスメンバーカード

メンバーカード

会社の人のメンバーカードと、その公開

エンドポイント

GET/v1/business-cards
POST/v1/business-cards
GET/v1/business-cards/{id}
PATCH/v1/business-cards/{id}
POST/v1/business-cards/{id}/publish
POST/v1/business-cards/{id}/unpublish

GET/v1/business-cards

名刺の一覧・検索

ワークスペースのデジタル名刺を返します（アーカイブしたものを除く）。持ち主の人（personId）で絞り込めます。

権限 business_cards:readnextCursor で続き

クエリ

personIdstring
持ち主の人で絞り込み
100文字まで
limitinteger
1回に返す件数（既定 50、最大 100）
1〜100
cursorstring
前の応答の nextCursor
100文字まで

返る項目data の中身 · 200

idstring
personIdstring | null
名刺の持ち主の人（GET /v1/people）
statusenum
draftpublishedunpublishedarchived
namestring | null
表示する氏名
jobTitlestring | null
departmentstring | null
emailstring | null
phonestring | null
biostring | null
自己紹介
imagestring | null
顔写真のURL
linksobject[]
公開するリンク（並び順どおり）
中の項目 3
- labelstring
- urlstring
- typeenum
  websitesocialemailphoneother
visibleFieldsenum[]
名刺に表示する項目。テンプレートが付いているときはテンプレートの設定が優先されます
pageIdstring
公開URLの末尾
publicUrlstring | null
公開ページのURL。status が published のときだけ開けます
publishedAtstring | null
createdAtstring
updatedAtstring

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

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

GET/v1/business-cards

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

レスポンス

{
  "data": [
    {
      "id": "clx8k2m0a0001",
      "personId": "clx8k2m0a0001",
      "status": "draft",
      "name": "山田 太郎",
      "jobTitle": "…",
      "department": "…",
      "email": "…",
      "phone": "…",
      "bio": "…",
      "image": "…",
      "links": [
        {
          "label": "…",
          "url": "https://tooon.app/…",
          "type": "website"
        }
      ],
      "visibleFields": [
        "name"
      ],
      "pageId": "clx8k2m0a0001",
      "publicUrl": "https://tooon.app/…",
      "publishedAt": "2026-11-01T09:00:00.000Z",
      "createdAt": "2026-11-01T09:00:00.000Z",
      "updatedAt": "2026-11-01T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}

POST/v1/business-cards

人の名刺を作る（あれば上書き）

人（personId）の名刺を下書きで作ります。氏名・メール・肩書き・所属は、本文で省くと人の登録内容から写します。作った名刺はTooonの名刺一覧にも出て、画面から直せます。

1人につき名刺は1枚です。すでにあれば、本文に含めた項目だけを書き換えます。公開するには POST /v1/business-cards/{id}/publish を呼んでください。

人は POST /v1/people で登録し、GET /v1/people?externalRef= で探せます。

権限 business_cards:writeIdempotency-Key

送る項目JSON · 14項目

namestring | null
表示する氏名。null ならメンバーの名前を使います
80文字まで
jobTitlestring | null
80文字まで
departmentstring | null
部署。画面で部署ごとのテンプレートを決めていれば、そのデザインになります
80文字まで
emailstring (email) | null
320文字まで
phonestring | null
64文字まで
biostring | null
自己紹介
5,000文字まで
imagestring | null
顔写真のURL（https）
2,048文字まで
linksobject[]
公開するリンク。送ると、今のリンクをすべてこの並びに置き換えます
20以下件
中の項目 3
- labelstring必須
  80文字まで
- urlstring必須
  2,048文字まで
- typeenum
  既定 website
  websitesocialemailphoneother
visibleFieldsenum[]
名刺に表示する項目。name を含めないと公開できません
1以上件
pageIdstring
公開URLの末尾（カスタムURL）。半角英小文字・数字・ハイフンで3〜40文字。前のURLは新しいURLへ移ります
80文字まで
personIdstring必須
名刺の持ち主の人
100文字まで

返る項目data の中身 · 200

idstring
personIdstring | null
名刺の持ち主の人（GET /v1/people）
statusenum
draftpublishedunpublishedarchived
namestring | null
表示する氏名
jobTitlestring | null
departmentstring | null
emailstring | null
phonestring | null
biostring | null
自己紹介
imagestring | null
顔写真のURL
linksobject[]
公開するリンク（並び順どおり）
中の項目 3
- labelstring
- urlstring
- typeenum
  websitesocialemailphoneother
visibleFieldsenum[]
名刺に表示する項目。テンプレートが付いているときはテンプレートの設定が優先されます
pageIdstring
公開URLの末尾
publicUrlstring | null
公開ページのURL。status が published のときだけ開けます
publishedAtstring | null
createdAtstring
updatedAtstring

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

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

POST/v1/business-cards

curl -X POST https://tooon.app/api/v1/business-cards \
  -H "Authorization: Bearer $TOOON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "personId": "clx8k2m0a0001"
}'

レスポンス

{
  "data": {
    "id": "clx8k2m0a0001",
    "personId": "clx8k2m0a0001",
    "status": "draft",
    "name": "山田 太郎",
    "jobTitle": "…",
    "department": "…",
    "email": "…",
    "phone": "…",
    "bio": "…",
    "image": "…",
    "links": [
      {
        "label": "…",
        "url": "https://tooon.app/…",
        "type": "website"
      }
    ],
    "visibleFields": [
      "name"
    ],
    "pageId": "clx8k2m0a0001",
    "publicUrl": "https://tooon.app/…",
    "publishedAt": "2026-11-01T09:00:00.000Z",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

GET/v1/business-cards/{id}

名刺を取得する

権限 business_cards:read

パスの値

idstring必須
名刺のID
100文字まで

返る項目data の中身 · 200

idstring
personIdstring | null
名刺の持ち主の人（GET /v1/people）
statusenum
draftpublishedunpublishedarchived
namestring | null
表示する氏名
jobTitlestring | null
departmentstring | null
emailstring | null
phonestring | null
biostring | null
自己紹介
imagestring | null
顔写真のURL
linksobject[]
公開するリンク（並び順どおり）
中の項目 3
- labelstring
- urlstring
- typeenum
  websitesocialemailphoneother
visibleFieldsenum[]
名刺に表示する項目。テンプレートが付いているときはテンプレートの設定が優先されます
pageIdstring
公開URLの末尾
publicUrlstring | null
公開ページのURL。status が published のときだけ開けます
publishedAtstring | null
createdAtstring
updatedAtstring

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

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

GET/v1/business-cards/{id}

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

レスポンス

{
  "data": {
    "id": "clx8k2m0a0001",
    "personId": "clx8k2m0a0001",
    "status": "draft",
    "name": "山田 太郎",
    "jobTitle": "…",
    "department": "…",
    "email": "…",
    "phone": "…",
    "bio": "…",
    "image": "…",
    "links": [
      {
        "label": "…",
        "url": "https://tooon.app/…",
        "type": "website"
      }
    ],
    "visibleFields": [
      "name"
    ],
    "pageId": "clx8k2m0a0001",
    "publicUrl": "https://tooon.app/…",
    "publishedAt": "2026-11-01T09:00:00.000Z",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

PATCH/v1/business-cards/{id}

名刺を更新する

本文に含めた項目だけを書き換えます。null を送るとその項目を空にします。公開中の名刺は、公開し直すまで公開ページは変わりません。

権限 business_cards:writeIdempotency-Key

パスの値

idstring必須
名刺のID
100文字まで

送る項目JSON · 13項目

namestring | null
表示する氏名。null ならメンバーの名前を使います
80文字まで
jobTitlestring | null
80文字まで
departmentstring | null
部署。画面で部署ごとのテンプレートを決めていれば、そのデザインになります
80文字まで
emailstring (email) | null
320文字まで
phonestring | null
64文字まで
biostring | null
自己紹介
5,000文字まで
imagestring | null
顔写真のURL（https）
2,048文字まで
linksobject[]
公開するリンク。送ると、今のリンクをすべてこの並びに置き換えます
20以下件
中の項目 3
- labelstring必須
  80文字まで
- urlstring必須
  2,048文字まで
- typeenum
  既定 website
  websitesocialemailphoneother
visibleFieldsenum[]
名刺に表示する項目。name を含めないと公開できません
1以上件
pageIdstring
公開URLの末尾（カスタムURL）。半角英小文字・数字・ハイフンで3〜40文字。前のURLは新しいURLへ移ります
80文字まで

返る項目data の中身 · 200

idstring
personIdstring | null
名刺の持ち主の人（GET /v1/people）
statusenum
draftpublishedunpublishedarchived
namestring | null
表示する氏名
jobTitlestring | null
departmentstring | null
emailstring | null
phonestring | null
biostring | null
自己紹介
imagestring | null
顔写真のURL
linksobject[]
公開するリンク（並び順どおり）
中の項目 3
- labelstring
- urlstring
- typeenum
  websitesocialemailphoneother
visibleFieldsenum[]
名刺に表示する項目。テンプレートが付いているときはテンプレートの設定が優先されます
pageIdstring
公開URLの末尾
publicUrlstring | null
公開ページのURL。status が published のときだけ開けます
publishedAtstring | null
createdAtstring
updatedAtstring

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

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

PATCH/v1/business-cards/{id}

curl -X PATCH https://tooon.app/api/v1/business-cards/clx8k2m0a0001 \
  -H "Authorization: Bearer $TOOON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "山田 太郎",
  "jobTitle": "…",
  "department": "…"
}'

レスポンス

{
  "data": {
    "id": "clx8k2m0a0001",
    "personId": "clx8k2m0a0001",
    "status": "draft",
    "name": "山田 太郎",
    "jobTitle": "…",
    "department": "…",
    "email": "…",
    "phone": "…",
    "bio": "…",
    "image": "…",
    "links": [
      {
        "label": "…",
        "url": "https://tooon.app/…",
        "type": "website"
      }
    ],
    "visibleFields": [
      "name"
    ],
    "pageId": "clx8k2m0a0001",
    "publicUrl": "https://tooon.app/…",
    "publishedAt": "2026-11-01T09:00:00.000Z",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

POST/v1/business-cards/{id}/publish

名刺を公開する

今の中身で名刺を公開します（公開中なら、今の中身で公開し直します）。公開すると publicUrl が開けるようになります。氏名を表示項目に含めていないと公開できません。

権限 business_cards:writeIdempotency-Key

パスの値

idstring必須
名刺のID
100文字まで

返る項目data の中身 · 200

idstring
personIdstring | null
名刺の持ち主の人（GET /v1/people）
statusenum
draftpublishedunpublishedarchived
namestring | null
表示する氏名
jobTitlestring | null
departmentstring | null
emailstring | null
phonestring | null
biostring | null
自己紹介
imagestring | null
顔写真のURL
linksobject[]
公開するリンク（並び順どおり）
中の項目 3
- labelstring
- urlstring
- typeenum
  websitesocialemailphoneother
visibleFieldsenum[]
名刺に表示する項目。テンプレートが付いているときはテンプレートの設定が優先されます
pageIdstring
公開URLの末尾
publicUrlstring | null
公開ページのURL。status が published のときだけ開けます
publishedAtstring | null
createdAtstring
updatedAtstring

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

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

POST/v1/…/{id}/publish

curl -X POST https://tooon.app/api/v1/business-cards/clx8k2m0a0001/publish \
  -H "Authorization: Bearer $TOOON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

レスポンス

{
  "data": {
    "id": "clx8k2m0a0001",
    "personId": "clx8k2m0a0001",
    "status": "draft",
    "name": "山田 太郎",
    "jobTitle": "…",
    "department": "…",
    "email": "…",
    "phone": "…",
    "bio": "…",
    "image": "…",
    "links": [
      {
        "label": "…",
        "url": "https://tooon.app/…",
        "type": "website"
      }
    ],
    "visibleFields": [
      "name"
    ],
    "pageId": "clx8k2m0a0001",
    "publicUrl": "https://tooon.app/…",
    "publishedAt": "2026-11-01T09:00:00.000Z",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

POST/v1/business-cards/{id}/unpublish

名刺を非公開にする

公開ページを閉じます。中身は残るので、もう一度公開できます。

権限 business_cards:writeIdempotency-Key

パスの値

idstring必須
名刺のID
100文字まで

返る項目data の中身 · 200

idstring
personIdstring | null
名刺の持ち主の人（GET /v1/people）
statusenum
draftpublishedunpublishedarchived
namestring | null
表示する氏名
jobTitlestring | null
departmentstring | null
emailstring | null
phonestring | null
biostring | null
自己紹介
imagestring | null
顔写真のURL
linksobject[]
公開するリンク（並び順どおり）
中の項目 3
- labelstring
- urlstring
- typeenum
  websitesocialemailphoneother
visibleFieldsenum[]
名刺に表示する項目。テンプレートが付いているときはテンプレートの設定が優先されます
pageIdstring
公開URLの末尾
publicUrlstring | null
公開ページのURL。status が published のときだけ開けます
publishedAtstring | null
createdAtstring
updatedAtstring

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

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

POST/v1/…/{id}/unpublish

curl -X POST https://tooon.app/api/v1/business-cards/clx8k2m0a0001/unpublish \
  -H "Authorization: Bearer $TOOON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

レスポンス

{
  "data": {
    "id": "clx8k2m0a0001",
    "personId": "clx8k2m0a0001",
    "status": "draft",
    "name": "山田 太郎",
    "jobTitle": "…",
    "department": "…",
    "email": "…",
    "phone": "…",
    "bio": "…",
    "image": "…",
    "links": [
      {
        "label": "…",
        "url": "https://tooon.app/…",
        "type": "website"
      }
    ],
    "visibleFields": [
      "name"
    ],
    "pageId": "clx8k2m0a0001",
    "publicUrl": "https://tooon.app/…",
    "publishedAt": "2026-11-01T09:00:00.000Z",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}