REST API リファレンス

概要

LeadHub には完全な REST API が含まれており、外部ツールがデータ（リード、パイプライン、オートメーション、フォームなど）を読み書きできます。Zapier との統合、カスタムダッシュボードの構築、ウェブサイトの接続、あらゆる自動化にご利用ください。

ベース URL

すべての API リクエストの送信先：

https://yourdomain.com/api/v1

yourdomain.com を実際の LeadHub ドメインに置き換えてください。

認証

すべてのリクエスト（health check を除く）には API キーが必要です。

API キーは管理パネルの 設定 → API キー で作成します。手順については設定ページをご覧ください。

すべてのリクエストの Authorization ヘッダーに Bearer トークンとして API キーを含めてください：

Authorization: Bearer lh_your_api_key_here

API キーなし、または無効なキーでリクエストを送信すると、401 Unauthorized レスポンスが返されます。

レート制限

各 API キーはデフォルトで 1 時間あたり 1,000 リクエスト に制限されています（キーごとに設定可能）。この制限を超えると 429 Too Many Requests レスポンスが返されます。

すべてのレスポンスには使用状況を追跡するためのヘッダーが含まれます：

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711580400

X-RateLimit-Reset は制限がリセットされる Unix タイムスタンプです。

ページネーション

レコードのリストを返すエンドポイントはページネーションに対応しています。以下のクエリパラメータを追加してください：

パラメータ	デフォルト	最大
`page`	`1`	—
`per_page`	`15`	`100`

例：GET /api/v1/leads?page=2&per_page=25

レスポンス形式

成功レスポンス

{
  "data": { ... },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73,
    "from": 1,
    "to": 15
  },
  "links": {
    "first": "https://yourdomain.com/api/v1/leads?page=1",
    "last": "https://yourdomain.com/api/v1/leads?page=5",
    "prev": null,
    "next": "https://yourdomain.com/api/v1/leads?page=2",
    "self": "https://yourdomain.com/api/v1/leads?page=1"
  }
}

単一レコードのレスポンス（show、create、update）では data にレコードオブジェクトが含まれ、meta は省略されます。

エラーレスポンス

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

一般的なエラーコード：

コード	HTTP ステータス	意味
`UNAUTHORIZED`	401	API キーが欠落または無効
`FORBIDDEN`	403	API キーに必要なスコープがない
`NOT_FOUND`	404	レコードが存在しない
`VALIDATION_FAILED`	422	リクエストデータの検証に失敗
`RATE_LIMITED`	429	リクエストが多すぎる
`SERVER_ERROR`	500	予期しないサーバーエラー

ヘルスチェック

認証不要。

GET /api/v1/health

レスポンス：

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-28T09:15:00+00:00"
}

他のリクエストを行う前に LeadHub インスタンスにアクセスできるか確認するのに使用します。

リード（Leads）

必要なスコープ： 取得には read:leads、作成/更新には write:leads、削除には delete:leads。

リードの一覧取得

GET /api/v1/leads

フィルタリング用クエリパラメータ：

パラメータ	説明
`source`	ソースでフィルタ（例：`facebook`、`website`）
`status`	ステータスでフィルタ（例：`new`、`contacted`、`qualified`）
`pipeline_id`	パイプライン ID でフィルタ
`stage_id`	パイプラインステージ ID でフィルタ
`assigned_user_id`	担当ユーザー ID でフィルタ
`tag`	タグ名でフィルタ
`search`	名前、メール、電話で検索
`created_after`	ISO 8601 日付 — この日付以降に作成されたリードのみ
`created_before`	ISO 8601 日付 — この日付以前に作成されたリードのみ
`starred`	`true` でスター付きのリードのみ表示
`sort`	ソートフィールド：`created_at`、`updated_at`、`lead_score`、`first_name`、`last_name`、`email`
`direction`	`asc` または `desc`（デフォルト：`desc`）

リードの取得

GET /api/v1/leads/{id}

リードの作成

POST /api/v1/leads

リクエストボディ（JSON）：

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "[email protected]",
  "phone": "+14155551234",
  "source": "website",
  "status": "new",
  "pipeline_id": 1,
  "pipeline_stage_id": 2,
  "assigned_user_id": 5,
  "notes": "Interested in the enterprise plan.",
  "custom_fields": {
    "budget": "10000"
  },
  "tags": ["hot-lead", "enterprise"]
}

first_name は必須です。その他のフィールドはすべて任意です。

リードの更新

PUT /api/v1/leads/{id}
PATCH /api/v1/leads/{id}

更新したいフィールドのみ送信してください。作成と同じフィールドです。

リードの削除

DELETE /api/v1/leads/{id}

リードへのタグ追加

POST /api/v1/leads/{id}/tags

ボディ：{ "tag": "vip-client" }

リードからのタグ削除

DELETE /api/v1/leads/{id}/tags/{tag}

パイプライン（Pipelines）

必要なスコープ： read:pipelines または write:pipelines

GET    /api/v1/pipelines
POST   /api/v1/pipelines
GET    /api/v1/pipelines/{id}
PUT    /api/v1/pipelines/{id}
PATCH  /api/v1/pipelines/{id}
DELETE /api/v1/pipelines/{id}

パイプラインステージ

GET    /api/v1/pipelines/{pipeline_id}/stages
POST   /api/v1/pipelines/{pipeline_id}/stages
GET    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PUT    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PATCH  /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
DELETE /api/v1/pipelines/{pipeline_id}/stages/{stage_id}

タグ（Tags）

必要なスコープ： read:tags または write:tags

GET    /api/v1/tags
POST   /api/v1/tags
GET    /api/v1/tags/{id}
PUT    /api/v1/tags/{id}
PATCH  /api/v1/tags/{id}
DELETE /api/v1/tags/{id}

ユーザー（Users）

必要なスコープ： read:users、write:users または delete:users

GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/{id}
PUT    /api/v1/users/{id}
PATCH  /api/v1/users/{id}
DELETE /api/v1/users/{id}

フォーム（Forms）

必要なスコープ： read:forms、write:forms または delete:forms

GET    /api/v1/forms
POST   /api/v1/forms
GET    /api/v1/forms/{id}
PUT    /api/v1/forms/{id}
PATCH  /api/v1/forms/{id}
DELETE /api/v1/forms/{id}

フォームの送信

POST /api/v1/forms/{id}/submissions

ボディ：フォームフィールドの値をキーと値のペアで指定します。

オートメーション（Automations）

必要なスコープ： read:automations、write:automations または delete:automations

GET    /api/v1/automations
POST   /api/v1/automations
GET    /api/v1/automations/{id}
PUT    /api/v1/automations/{id}
PATCH  /api/v1/automations/{id}
DELETE /api/v1/automations/{id}

インテグレーション（Integrations）

必要なスコープ： read:integrations または write:integrations

GET    /api/v1/integrations/types
GET    /api/v1/integrations
POST   /api/v1/integrations
GET    /api/v1/integrations/{id}
PUT    /api/v1/integrations/{id}
PATCH  /api/v1/integrations/{id}
DELETE /api/v1/integrations/{id}

GET /api/v1/integrations/types は利用可能なインテグレーションタイプの一覧を返します（Facebook、Google Ads、Mailgun など）。

インバウンドリード受信

外部ソース、webhook、または Zapier や Make などのノーコードツールからリードを作成するための簡易エンドポイントです。

POST /api/inbound/leads?tenant={workspace-slug}

Authorization: Bearer {api_key} で認証し、クエリパラメータとしてワークスペースの slug を渡してください。

リクエストボディ：

{
  "email": "[email protected]",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "phone": "+14155551234",
  "company": "Tech Corp",
  "source": "zapier",
  "notes": "Came from newsletter signup",
  "tags": ["newsletter"],
  "custom_fields": {
    "utm_campaign": "spring-promo"
  }
}

email は必須です。その他のフィールドはすべて任意です。

成功レスポンス（201）：

{
  "status": "created",
  "lead_id": 1842,
  "is_duplicate": false
}

リードがすでに存在する場合（メールまたは電話で一致）、is_duplicate は true となり、既存リードの ID が返されます。

コード例

cURL

curl -X GET "https://yourdomain.com/api/v1/leads?status=new&per_page=25" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Accept: application/json"

curl -X POST "https://yourdomain.com/api/v1/leads" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Sarah","email":"[email protected]","source":"api"}'

PHP

$apiKey = 'lh_your_api_key_here';
$baseUrl = 'https://yourdomain.com/api/v1';

// List leads
$response = file_get_contents($baseUrl . '/leads', false, stream_context_create([
    'http' => [
        'header' => "Authorization: Bearer {$apiKey}\r\nAccept: application/json\r\n",
    ],
]));
$leads = json_decode($response, true);

// Create a lead
$ch = curl_init($baseUrl . '/leads');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$apiKey}",
    "Content-Type: application/json",
    "Accept: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'first_name' => 'Sarah',
    'email'      => '[email protected]',
    'source'     => 'api',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript (fetch)

const apiKey = 'lh_your_api_key_here';
const baseUrl = 'https://yourdomain.com/api/v1';

// List leads
const response = await fetch(`${baseUrl}/leads?status=new`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Accept': 'application/json',
  },
});
const { data, meta } = await response.json();

// Create a lead
const createResponse = await fetch(`${baseUrl}/leads`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Sarah',
    email: '[email protected]',
    source: 'website',
  }),
});
const newLead = await createResponse.json();

概要​

ベース URL​

認証​

レート制限​

ページネーション​

レスポンス形式​

成功レスポンス​

エラーレスポンス​

ヘルスチェック​

リード（Leads）​

リードの一覧取得​

リードの取得​

リードの作成​

リードの更新​

リードの削除​

リードへのタグ追加​

リードからのタグ削除​

パイプライン（Pipelines）​

パイプラインステージ​

タグ（Tags）​

ユーザー（Users）​

フォーム（Forms）​

フォームの送信​

オートメーション（Automations）​

インテグレーション（Integrations）​

インバウンドリード受信​

コード例​

cURL​

PHP​

JavaScript (fetch)​

概要