AgencyHandy API：新しいリードをプログラムで作成する

リード作成エンドポイントを使用すると、外部のシステム（Webフォーム、CRM、マーケティングオートメーションプラットフォーム、またはカスタムスクリプト）からAgencyHandyワークスペースに新しいリードをプログラムで追加できます。このエンドポイントで作成されたリードは、手動で追加した場合と同様に、すぐにリードパイプラインに表示されます。

このエンドポイントを使用する前に、入門ガイドを完了してAPIキーと会社IDを取得してください。また、リード作成時に必要なクライアントロールIDの取得も必要です。

前提条件

✅ ワークスペース設定 → APIキーから生成されたAPIキー
✅ GET {{URL}}/accounts/companiesから取得した会社ID
✅ クライアントロールIDの取得（以下のステップ1を参照）

ステップ1：クライアントロールIDを取得する

リードを作成する前に、会社内のclientロールのロールIDが必要です。

エンドポイント

GET {{URL}}/roles?type=company

ヘッダー

ヘッダー	値
`x-api-key`	あなたのAPIキー
`companyid`	あなたの会社ID

リクエスト例

cURL

curl --request GET "https://api.agencyhandy.com/roles?type=company" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>"

レスポンス例

{
  "roles": [
    {
      "_id": "6525994184e9ddd798534535",
      "role": {
        "_id": "6525994184e9ddd79853451e",
        "responsibility": "",
        "name": "client"
      },
      "company": "6525994184e9ddd79853450e",
      "createdAt": "2023-10-10T18:34:41.567Z",
      "updatedAt": "2024-10-01T07:28:48.340Z",
      "__v": 0,
      "type": "company"
    }
  ]
}

roles[0].role.name === "client"のエントリを見つけ、外側の_id — つまりroles[0]._idを抽出します。roles[0].role._idではありません。

const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"

roles[0].role._id（ロール定義ID）ではなく、roles[0]._id（会社-ロールマッピングID）を使用してください。間違ったIDを使用するとリード作成リクエストが失敗します。

ステップ2：新しいリードを作成する

エンドポイント

POST {{URL}}/members/bulk-lead

ヘッダー

ヘッダー	値
`x-api-key`	あなたのAPIキー
`companyid`	あなたの会社ID
`Content-Type`	`application/json`

リクエストボディ

リクエストボディはJSON配列です — 1回の呼び出しで1つ以上のリードを作成できます。

firstName

string

必須

リードの名前。

lastName

string

必須

リードの姓。

string

必須

リードのメールアドレス。ワークスペース内で一意である必要があります。

role

string

必須

ステップ1で取得したクライアントロールID（つまりroles[0]._id）。

isConvertedClient

boolean

必須

リードを作成する際はfalseに設定する必要があります。リードを正式なクライアントに変換する場合のみtrueに設定します。

status

string

リードのパイプラインステータス。一般的な値：New、Contacted、Qualified。省略した場合はNewがデフォルト値となります。

contactNo

string

リードの電話番号。

source

string

このリードの獲得方法。値の例：website、referral、social。

positionInBoard

number

パイプラインボードの列内でのリードの位置（順序）。デフォルトは1。

リクエスト例

cURL

curl --request POST "https://api.agencyhandy.com/members/bulk-lead" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "role": "6525994184e9ddd798534535",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'

成功レスポンス

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}

message

string

確認文字列："Lead created successfully"。

createdMembers

array

作成されたリードオブジェクトの配列。

createdMembers[].\_id

string

新しく作成されたリードの一意ID。後続のAPI呼び出しでリードを参照する必要がある場合は保存してください。

createdMembers[].name

string

リードのフルネーム（firstName + lastName）。

createdMembers[].status

string

保存されたリードのパイプラインステータス。

createdMembers[].role

string

メンバーに割り当てられたロール名 — "client"になります。

配列に複数のリードオブジェクトを渡すことで、1回のAPI呼び出しで複数のリードを作成できます。各オブジェクトには必須フィールドと固有のメールアドレスが必要です。

​前提条件

​ステップ1：クライアントロールIDを取得する

​エンドポイント

​ヘッダー

​リクエスト例

​レスポンス例

​ステップ2：新しいリードを作成する

​エンドポイント

​ヘッダー

​リクエストボディ

​リクエスト例

​成功レスポンス

前提条件

ステップ1：クライアントロールIDを取得する

エンドポイント

ヘッダー

リクエスト例

レスポンス例

ステップ2：新しいリードを作成する

エンドポイント

ヘッダー

リクエストボディ

リクエスト例

成功レスポンス