顧客 - Comdesk ヘルプ

ベース URL：https://xxxx.comdesk.com/api/v1

メソッド	パス	スコープ
`POST`	`/customers`	`customers:write`
`POST`	`/customers/bulk`	`customers:write`
`GET`	`/customers/bulk/{batchId}`	`customers:write`
`GET`	`/customers`	`customers:read`
`GET`	`/customers/{customerId}`	`customers:read`
`PUT`	`/customers/{customerId}`	`customers:write`

顧客オブジェクト

integer

Comdesk が割り当てる ID。

string

自社システムの ID。プロジェクト内で一意。未設定の場合は null。

string

フリガナ（カナ読み）。

string

object

プロパティ名をキーとするカスタムプロパティの値。

integer

string

オフセット付き ISO 8601。

string

オフセット付き ISO 8601。

フィールドのルール

tel1 / tel2 — 最大 30 文字。E.164 形式（+819012345678）、または 0 で始まる国内番号（0312345678、10〜11 桁）のいずれか。区切りとしてハイフンまたはスペースを使用できます。それ以外は 422 を返します。
custom_fields — 最大 100 件。各値は最大 255 文字の文字列。各キーは、テナントに既に存在する顧客プロパティの名前または数値 ID と完全に一致（大文字小文字を区別）する必要があります。未知のキーがあると 422 を返し、何も保存されません。
project_id — 自テナント内のプロジェクトである必要があります。それ以外は 422。

顧客を登録する

POST /customers

ボディ

integer

required

顧客が属するプロジェクト。

string

required

顧客名、最大 255 文字。

string

自社レコード ID、最大 255。プロジェクト内で一意 — 重複時は 409 duplicate_external_id を返します。

string

最大 255 文字。

string

上記「フィールドのルール」を参照。

string

上記「フィールドのルール」を参照。

string

最大 255 文字。

string

最大 255 文字。

string

最大 255 文字。

string

最大 255 文字。

object

上記「フィールドのルール」を参照。

登録に成功すると、customer.created Webhook イベントも発生します。

curl -X POST https://xxxx.comdesk.com/api/v1/customers \
  -H "Authorization: Bearer $COMDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 456,
    "external_id": "SF-LEAD-00100",
    "name": "Test Corp",
    "tel1": "0337778888"
  }'

{
  "data": {
    "customer_id": 90123,
    "external_id": "SF-LEAD-00100",
    "name": "Test Corp",
    "project_id": 456,
    "created_at": "2026-06-02T17:30:00+09:00"
  }
}

一括登録

POST /customers/bulk 1〜500 件の顧客を登録キューに入れ、202 Accepted と batch_id を即座に返します。レスポンスが届いた時点ではレコードはまだ作成されていません — 結果は下記「一括登録ステータスの取得」（GET /customers/bulk/{batchId}）をポーリングして確認してください。

ボディ

array

required

1〜500 件の顧客オブジェクトの配列。各要素は単一登録のボディと同じフィールドとルールを使用します。いずれかのレコードがスキーマバリデーションに失敗した場合（例：tel1 の形式が不正）、リクエスト全体が 422 で拒否され、何もキューに入りません。

curl -X POST https://xxxx.comdesk.com/api/v1/customers/bulk \
  -H "Authorization: Bearer $COMDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      { "project_id": 456, "external_id": "SF-LEAD-00100", "name": "Test Corp", "tel1": "0337778888" },
      { "project_id": 456, "external_id": "SF-LEAD-00101", "name": "Tanaka Taro", "tel1": "+819012345678" }
    ]
  }'

{
  "data": {
    "batch_id": "b3f1c2a0-9d7e-4c11-88a2-1f0b5c6de9d4",
    "status": "pending",
    "total": 2
  }
}

一括登録ステータスの取得

GET /customers/bulk/{batchId} バッチの進捗とレコードごとの結果を返します。数秒ごとにポーリングしてください。1 レコードあたり約 80 ms が目安です。未知のバッチ、または他テナントに属するバッチの場合は 404 を返します。

string

pending（キュー投入済み）→ processing → completed または failed。pending のまま長時間経過したバッチは failure_reason 付きで failed として報告されるため、ポーリングは必ず終了状態に到達します。

integer

送信したレコード数。

integer

array

作成されたレコードごとに 1 エントリ：index（送信した配列内の位置）、status（created）、customer_id、external_id。バッチが完了するまでは空です。

array

失敗したレコードごとに 1 エントリ：index、code（例：duplicate_external_id、validation_error）、message。バッチが完了するまでは空です。

string

バッチ全体が失敗した理由。status が failed の場合のみ設定されます。

string

処理が開始されるまでは null。

string

バッチが終了するまでは null。

{
  "data": {
    "batch_id": "b3f1c2a0-9d7e-4c11-88a2-1f0b5c6de9d4",
    "status": "completed",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      { "index": 0, "status": "created", "customer_id": 90123, "external_id": "SF-LEAD-00100" }
    ],
    "errors": [
      { "index": 1, "code": "duplicate_external_id", "message": "Duplicate external_id within the same project." }
    ],
    "failure_reason": null,
    "created_at": "2026-08-11T18:47:14+09:00",
    "started_at": "2026-08-11T18:47:15+09:00",
    "completed_at": "2026-08-11T18:47:16+09:00"
  }
}

作成された各レコードについても、customer.created Webhook イベントが発生します。

顧客一覧

GET /customers 条件に一致した各顧客について、完全な顧客オブジェクト（上記「顧客オブジェクト」を参照）をページネーション付きで返します。

integer

required

一覧を取得するプロジェクト。自テナント内のプロジェクトである必要があります。

string

自社システムの ID の完全一致（0 件または 1 件を返します）。

string

名前または電話番号の部分一致、最大 255 文字。

string

name、created_at、または updated_at。

string

asc または desc。

integer

default:"1"

integer

default:"50"

最大 100。

curl "https://xxxx.comdesk.com/api/v1/customers?project_id=456&external_id=SF-LEAD-00100" \
  -H "Authorization: Bearer $COMDESK_API_KEY"

{
  "data": [
    {
      "customer_id": 90123,
      "external_id": "SF-LEAD-00100",
      "name": "Test Corp",
      "name_kana": null,
      "tel1": "0337778888",
      "tel2": null,
      "prefecture": null,
      "address1": null,
      "industry": null,
      "employee_scale": null,
      "custom_fields": {},
      "project_id": 456,
      "created_at": "2026-06-02T17:30:00+09:00",
      "updated_at": "2026-06-02T17:30:00+09:00"
    }
  ],
  "pagination": { "current_page": 1, "per_page": 50, "total": 1, "last_page": 1 }
}

顧客の取得

GET /customers/{customerId} 完全な顧客オブジェクト（上記「顧客オブジェクト」を参照）を返します。自テナント内に存在しない場合は 404 resource_not_found を返します。

顧客の更新

PUT /customers/{customerId} 部分更新 — 変更したいフィールドのみ送信します。省略したフィールドはそのまま維持されます。null 許容のフィールドをクリアするには null を送信します。更新後の完全な顧客オブジェクト（上記「顧客オブジェクト」を参照）を返し、customer.updated Webhook イベントが発生します。受け付けるフィールド：name、name_kana、tel1、tel2、prefecture、address1、industry、employee_scale、custom_fields（登録と同じルール）、および remarks（自由記述、最大 65,535 文字）。

external_id と project_id は作成時に固定されます。いずれか（または id、customer_id、tenant_id）を送信すると 422 を返します。

curl -X PUT https://xxxx.comdesk.com/api/v1/customers/90123 \
  -H "Authorization: Bearer $COMDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tel2": "09012345678", "custom_fields": { "Rank": "A" } }'