連絡先・商談・ジャーニーの API

これらのエンドポイントを使うと、独自のコード、Zapier、n8n からアカウントを操作できます。連絡先の追加、商談の作成と移動、ジャーニーへの連絡先の登録、そしてそれらの呼び出しに必要な ID の取得ができます。送信 API と同じ API キーを使います。

Authorization: Bearer mia_live_...

エンドポイントのグループごとに、キーあたり1分間に60リクエストまでです。超えると 429 が返ります。エラーは 4xx のステータスで {"error": "…"} として返ります。すべてのレスポンス形式を含む完全な仕様は OpenAPI 仕様にあります。

連絡先

作成または更新

POST /api/v1/contacts は、連絡先リストにアドレスを追加します。すでにあれば更新します。

{
  "listId": "list_abc123",
  "email": "[email protected]",
  "fields": { "first_name": "Ada", "company": "Analytical Engines" }
}

新しい連絡先なら 201、更新なら 200 で、保存された連絡先が返ります。一度に最大500件送るには、{"listId": "…", "contacts": [{"email": "…", "first_name": "…"}, …]} を使います。この場合は件数が返ります。

すべてのアドレスは保存時に確認されます。API が同意の答えを記録することはないため、これらの連絡先はこれまでどおり送信対象になります。1件の連絡先でプランの連絡先上限を超える場合は 409 が返ります。

検索

GET /api/v1/[email protected] は、そのアドレスの連絡先をすべてのリストから新しい順に返します。&listId= を付けると1つのリストだけを検索します。検索は、ダッシュボードで連絡先を表示したときと同様に、アカウントの個人データアクセスログに記録されます。

商談

作成

POST /api/v1/deals：

{
  "email": "[email protected]",
  "title": "Annual plan",
  "value": 120000,
  "currency": "JPY"
}

連絡先は email、または listId と rowId で指定します。メールアドレスだけの場合、そのアドレスを含むリストのうち最近更新されたリストに商談が作られます。pipelineId と stageId がなければ、既定のパイプラインの最初の進行中ステージに入ります。currency の既定は USD です。

Idempotency-Key ヘッダー（注文番号など）を送ると、再試行を安全に行えます。同じキーで繰り返すと、2件目の商談は作られず、"created": false とともに 200 が返ります。

更新または移動

PATCH /api/v1/deals/{id} は title、value、currency、stageId を受け付けます。成約または失注のステージに移すと、商談は完了します。ボディ全体を先に検証するため、存在しないステージを指定しても何も変わりません。移動すると、ボードで移動したときと同じく、ジャーニーのトリガー 商談のステージ変更 と Webhook deal.stage_changed が発生します。

パイプライン

GET /api/v1/pipelines は、既定のパイプラインを先頭に、各パイプラインとそのステージ（id、name、kind）を返します。商談の移動先の stageId を調べるのに使います。

ジャーニー

GET /api/v1/journeys は、ジャーニーの ID、名前、トリガー、オン・オフの状態を一覧で返します。?trigger=api を付けると、コードから連絡先を登録できるジャーニーだけを返します。

POST /api/v1/journeys/{id}/trigger に {"email": "…", "listId": "…"} を送ると、トリガーが API 呼び出し のジャーニーに連絡先を登録します。ジャーニーを参照してください。

サンプルイベント

GET /api/v1/events/sample?type=deal.stage_changed は、その種類の Webhook のエンベロープのサンプルを {"events": [ … ]} として返します。type を省くと、すべての種類のサンプルを1件ずつ返します。自動化ツールは、実際のイベントが届く前にフィールドを見せるためにこれを使います。

Webhook

GET・POST /api/v1/webhooks と DELETE /api/v1/webhooks/{id} で、イベントの購読を管理します。Webhook とイベントを参照してください。