パートナー

発注先・業務委託先と、その事業者情報

エンドポイント

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

GET/v1/partners

パートナーの一覧・検索

ワークスペースに登録されたパートナー（発注先）を返します。email を指定すると、大文字小文字を区別せずにメールアドレスが一致する人だけを返します。各パートナーには事業者情報（住所・登録番号・振込先など）と業務委託契約（partnerOrders）が付きます。内部メモは返しません。

権限 partners:readnextCursor で続き

クエリ

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

返る項目data の中身 · 200

idstring
externalRefstring | null
namestring
companyNamestring | null
contactNamestring | null
emailstring | null
phoneNumberstring | null
addressstring | null
住所（請求書の請求元に載せる）
taxRegistrationNumberstring | null
適格請求書発行事業者の登録番号
bankAccountstring | null
振込先
statusenum
activeinactive
partnerOrdersobject[]
このパートナーとの業務委託契約（発注）。新しい順に最大50件
中の項目 8
- idstring
- titlestring
- statusenum
  draftactivecompletedcanceled
- amountinteger
- currencystring
- isIncludingTaxboolean
- startDatestring | null
- endDatestring | null
createdAtstring
updatedAtstring

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

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

GET/v1/partners

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

レスポンス

{
  "data": [
    {
      "id": "clx8k2m0a0001",
      "externalRef": "staff-0001",
      "name": "山田 太郎",
      "companyName": "山田デザイン事務所",
      "contactName": "山田 太郎",
      "email": "…",
      "phoneNumber": "090-1234-5678",
      "address": "東京都渋谷区神南1-2-3",
      "taxRegistrationNumber": "T1234567890123",
      "bankAccount": "○○銀行 渋谷支店 普通 1234567",
      "status": "active",
      "partnerOrders": [
        {
          "id": "clx8k2m0a0001",
          "title": "Webサイト制作の業務委託",
          "status": "draft",
          "amount": 100000,
          "currency": "JPY",
          "isIncludingTax": false,
          "startDate": "2026-11-30",
          "endDate": "2026-11-30"
        }
      ],
      "createdAt": "2026-11-01T09:00:00.000Z",
      "updatedAt": "2026-11-01T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}

POST/v1/partners

パートナーを登録する（externalRef で上書き）

パートナー（発注先・業務委託先）を登録します。登録したパートナーはTooonの画面にも出て、画面から直せます。

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

すでに画面で登録したパートナーを呼び出し元のシステムとつなぐときは、GET /v1/partners?email= で探してから PATCH /v1/partners/{id} で externalRef を付けてください。

権限 partners:writeIdempotency-Key

送る項目JSON · 10項目

companyNamestring | null
屋号・法人名
200文字まで
contactNamestring | null
担当者名
200文字まで
emailstring (email) | null
メールアドレス
320文字まで
phoneNumberstring | null
50文字まで
addressstring | null
住所（請求書の請求元に載せる）
500文字まで
taxRegistrationNumberstring | null
適格請求書発行事業者の登録番号
50文字まで
bankAccountstring | null
振込先
500文字まで
statusenum
既定 active
activeinactive
externalRefstring
呼び出し元システムでの識別子。同じ値なら同じパートナーとして扱います
200文字まで
namestring必須
表示名
200文字まで

返る項目data の中身 · 200

idstring
externalRefstring | null
namestring
companyNamestring | null
contactNamestring | null
emailstring | null
phoneNumberstring | null
addressstring | null
住所（請求書の請求元に載せる）
taxRegistrationNumberstring | null
適格請求書発行事業者の登録番号
bankAccountstring | null
振込先
statusenum
activeinactive
partnerOrdersobject[]
このパートナーとの業務委託契約（発注）。新しい順に最大50件
中の項目 8
- idstring
- titlestring
- statusenum
  draftactivecompletedcanceled
- amountinteger
- currencystring
- isIncludingTaxboolean
- startDatestring | null
- endDatestring | null
createdAtstring
updatedAtstring

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

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

POST/v1/partners

curl -X POST https://tooon.app/api/v1/partners \
  -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": "山田 太郎",
    "companyName": "山田デザイン事務所",
    "contactName": "山田 太郎",
    "email": "…",
    "phoneNumber": "090-1234-5678",
    "address": "東京都渋谷区神南1-2-3",
    "taxRegistrationNumber": "T1234567890123",
    "bankAccount": "○○銀行 渋谷支店 普通 1234567",
    "status": "active",
    "partnerOrders": [
      {
        "id": "clx8k2m0a0001",
        "title": "Webサイト制作の業務委託",
        "status": "draft",
        "amount": 100000,
        "currency": "JPY",
        "isIncludingTax": false,
        "startDate": "2026-11-30",
        "endDate": "2026-11-30"
      }
    ],
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

GET/v1/partners/{id}

パートナーを取得する

権限 partners:read

パスの値

idstring必須
パートナーのID
100文字まで

返る項目data の中身 · 200

idstring
externalRefstring | null
namestring
companyNamestring | null
contactNamestring | null
emailstring | null
phoneNumberstring | null
addressstring | null
住所（請求書の請求元に載せる）
taxRegistrationNumberstring | null
適格請求書発行事業者の登録番号
bankAccountstring | null
振込先
statusenum
activeinactive
partnerOrdersobject[]
このパートナーとの業務委託契約（発注）。新しい順に最大50件
中の項目 8
- idstring
- titlestring
- statusenum
  draftactivecompletedcanceled
- amountinteger
- currencystring
- isIncludingTaxboolean
- startDatestring | null
- endDatestring | null
createdAtstring
updatedAtstring

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

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

GET/v1/partners/{id}

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

レスポンス

{
  "data": {
    "id": "clx8k2m0a0001",
    "externalRef": "staff-0001",
    "name": "山田 太郎",
    "companyName": "山田デザイン事務所",
    "contactName": "山田 太郎",
    "email": "…",
    "phoneNumber": "090-1234-5678",
    "address": "東京都渋谷区神南1-2-3",
    "taxRegistrationNumber": "T1234567890123",
    "bankAccount": "○○銀行 渋谷支店 普通 1234567",
    "status": "active",
    "partnerOrders": [
      {
        "id": "clx8k2m0a0001",
        "title": "Webサイト制作の業務委託",
        "status": "draft",
        "amount": 100000,
        "currency": "JPY",
        "isIncludingTax": false,
        "startDate": "2026-11-30",
        "endDate": "2026-11-30"
      }
    ],
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

PATCH/v1/partners/{id}

パートナーを更新する

本文に含めた項目だけを書き換えます。null を送るとその項目を空にします。externalRef を付けると、画面で登録したパートナーを呼び出し元のシステムとつなげられます。

権限 partners:writeIdempotency-Key

パスの値

idstring必須
パートナーのID
100文字まで

送る項目JSON · 10項目

companyNamestring | null
屋号・法人名
200文字まで
contactNamestring | null
担当者名
200文字まで
emailstring (email) | null
メールアドレス
320文字まで
phoneNumberstring | null
50文字まで
addressstring | null
住所（請求書の請求元に載せる）
500文字まで
taxRegistrationNumberstring | null
適格請求書発行事業者の登録番号
50文字まで
bankAccountstring | null
振込先
500文字まで
statusenum
既定 active
activeinactive
externalRefstring | null
呼び出し元システムでの識別子。null で外します
200文字まで
namestring
表示名
200文字まで

返る項目data の中身 · 200

idstring
externalRefstring | null
namestring
companyNamestring | null
contactNamestring | null
emailstring | null
phoneNumberstring | null
addressstring | null
住所（請求書の請求元に載せる）
taxRegistrationNumberstring | null
適格請求書発行事業者の登録番号
bankAccountstring | null
振込先
statusenum
activeinactive
partnerOrdersobject[]
このパートナーとの業務委託契約（発注）。新しい順に最大50件
中の項目 8
- idstring
- titlestring
- statusenum
  draftactivecompletedcanceled
- amountinteger
- currencystring
- isIncludingTaxboolean
- startDatestring | null
- endDatestring | null
createdAtstring
updatedAtstring

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

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

PATCH/v1/partners/{id}

curl -X PATCH https://tooon.app/api/v1/partners/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": "山田 太郎",
    "companyName": "山田デザイン事務所",
    "contactName": "山田 太郎",
    "email": "…",
    "phoneNumber": "090-1234-5678",
    "address": "東京都渋谷区神南1-2-3",
    "taxRegistrationNumber": "T1234567890123",
    "bankAccount": "○○銀行 渋谷支店 普通 1234567",
    "status": "active",
    "partnerOrders": [
      {
        "id": "clx8k2m0a0001",
        "title": "Webサイト制作の業務委託",
        "status": "draft",
        "amount": 100000,
        "currency": "JPY",
        "isIncludingTax": false,
        "startDate": "2026-11-30",
        "endDate": "2026-11-30"
      }
    ],
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}