API docs by Redocly

Jolt External API (1.0.0)

Download OpenAPI specification:

Jolt の外部 API。

認証スキーマ

エンドポイントごとに異なります。

グループ 認証方式 ヘッダ / フィールド
Referral / ReferralTransaction / ReferralCustomFieldValue / ReferralActivityLog API キー X-Jolt-API-Key
Tag パブリックトークン (リクエストボディ内) program_token: "pub_..."
StripeWebhook Stripe 署名 Stripe-Signature (Stripe Dashboard で設定する Webhook の署名シークレットで検証)

Referral

リード関連の操作

Lead ステータス更新

Referral Lead のステータスを更新する。 Lead の特定には lead_id または custom_field_id + custom_field_value のいずれか一方を指定する。 Vendor / VendorProgram の整合性が取れない場合は 404 を返す。

Authorizations:
apiKeyAuth
header Parameters
X-Dry-Run
string
Value: "true"
Example: true

true を指定すると、認証およびリクエストバリデーションのみ実行し、 DB操作をスキップして 200 OK を返す。疎通確認用。

Request Body schema: application/json
required
lead_id
string

Referral Lead ID（Jolt 内部 ID）

custom_field_id
string

カスタムフィールド ID（ULID）

custom_field_value
string

カスタムフィールドの値

status
required
string
Enum: "qualified" "unqualified" "won" "lost"

Lead ステータス。 qualified: 適格 unqualified: 不適格 won: 取引成立 lost: 取引不成立

status_detail
string or null

ステータス詳細。 unqualified / lost の場合のみ指定可能。

Responses

Request samples

Content type
application/json
Example
{
  • "lead_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "status": "qualified"
}

Response samples

Content type
application/json
Example
{ }

ReferralTransaction

取引レコードの操作

取引レコード作成

紹介された顧客に対する取引レコードを作成する。 顧客の特定には customer_id または custom_field_id + custom_field_value のいずれか一方を指定する。 作成後、顧客向け報酬作成メッセージを非同期で送信する。

Authorizations:
apiKeyAuth
header Parameters
X-Dry-Run
string
Value: "true"
Example: true

true を指定すると、認証およびリクエストバリデーションのみ実行し、 DB操作をスキップして 200 OK を返す。疎通確認用。

Request Body schema: application/json
required
customer_id
string

Referral Customer ID（Jolt 内部 ID）

custom_field_id
string

カスタムフィールド ID（ULID）

custom_field_value
string

カスタムフィールドの値

sales_amount
required
integer <int32> >= 0

紹介売り上げ金額

Responses

Request samples

Content type
application/json
Example
{
  • "customer_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "sales_amount": 50000
}

Response samples

Content type
application/json
Example
{ }

ReferralCustomFieldValue

カスタムフィールド値の操作

カスタムフィールド値更新

指定した Referral のカスタムフィールド値を更新する。 部分更新をサポートし、指定されたフィールドのみ更新される。 存在しない値は新規作成、既存の値は上書きされる。

Authorizations:
apiKeyAuth
header Parameters
X-Dry-Run
string
Value: "true"
Example: true

true を指定すると、認証およびリクエストバリデーションのみ実行し、 DB操作をスキップして 200 OK を返す。疎通確認用。

Request Body schema: application/json
required
referral_id
required
string

Referral ID（ULID）

required
Array of objects

更新するカスタムフィールド値の配列

Responses

Request samples

Content type
application/json
{
  • "referral_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "custom_field_values": [
    ]
}

Response samples

Content type
application/json
Example
{ }

ReferralActivityLog

活動ログの操作

活動ログ作成

紹介に対する活動ログを作成する。 Vendor / VendorProgram の整合性が取れない場合は 404 を返す。

Authorizations:
apiKeyAuth
header Parameters
X-Dry-Run
string
Value: "true"
Example: true

true を指定すると、認証およびリクエストバリデーションのみ実行し、 DB操作をスキップして 200 OK を返す。疎通確認用。

Request Body schema: application/json
required
referral_id
required
string

Referral ID（ULID）

title
required
string

活動ログのタイトル

content
string

活動ログの内容

activity_date
required
string <date>

活動日（YYYY-MM-DD）

Responses

Request samples

Content type
application/json
{
  • "referral_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "title": "初回訪問",
  • "content": "初回訪問を実施し、サービス概要を説明しました。",
  • "activity_date": "2025-06-15"
}

Response samples

Content type
application/json
Example
{ }

Tag

クライアントサイトに埋め込む JS タグ (https://tag.jolt.me/v1/tag.js) から呼ばれる公開エンドポイント。 program_token (パブリックトークン) でベンダープログラムを識別する。書き込み専用権限。

タグ経由のリードステータス更新

クライアントサイトに埋め込んだ Jolt タグ (tag.js) から呼ばれる公開エンドポイント。 無料サインアップ完了 → qualified、有料化完了 → won のステータスを更新する。

認証

APIキー不要。ボディの program_token (パブリックトークン pub_... 48文字) でベンダープログラムを識別する。 書き込み専用なので漏洩時の被害は当該プログラムのリードステータス変更に限定される。

仕様

  • 更新のみ: 既存の Referral / ReferralLead がない場合は 200 を返してサイレント終了（突合キーの存在確認には使えない設計）。
  • 突合キー: organization_id または email のいずれか必須。両方未指定なら 400。
    • 一次キー: organization_id (system-managed カスタムフィールド「組織ID」と照合)
    • フォールバック: organization_id 不一致 or 未指定なら email (Referral.contact_email) で再検索
    • 推奨運用: BtoB SaaS では無料サインアップ操作者と有料化操作者が別人になり得るため、organization_id を常時送信し、email 単独で運用しない
  • 冪等: 同じステータス再送 / won 後の qualified 等は backend 側で握り潰す（200 {} を返す）。
  • organization_id: 外部サービスの組織 ID。リードの突合 (上記) に使われる。Stripe 連携を併用する場合は同じ値を Stripe metadata の jolt_organization_id キーにも送ること (キー名はレイヤで分離: Jolt API 内では organization_id、Stripe 共有名前空間では jolt_ プレフィックス付き)。won 後の不正遷移時もこのフィールドのみ upsert される（タグの冪等性のため）。
  • 任意フィールド (company_name / last_name / first_name): 値が空でなければ Referral 上書き。

CORS

クロスドメインから呼ばれるためプリフライト OPTIONS を許可。credentials: omit でアクセスする想定。

Request Body schema: application/json
required
Any of
program_token
required
string^pub_[a-f0-9]{48}$

ベンダープログラムのパブリックトークン。 形式: pub_ プレフィックス + 48文字の小文字 16進数 (24-byte ランダム値の hex)。 ベンダーダッシュボード → プログラム設定 → 基本設定 → 「パブリックトークン」で確認できる。

organization_id
required
string non-empty

外部サービスの組織 ID。リードの突合一次キー (system-managed カスタムフィールド「組織ID」と照合)。 BtoB SaaS で人事異動・退職に対しても安定した識別子であり、サインアップ操作者と有料化操作者が別人になるケースでも won 遷移を取りこぼさないために強く推奨。 Stripe 連携の Webhook 1段目照合 (metadata.jolt_organization_id) と同じ値を送ること。 キー名はレイヤで分離: Jolt API 内では organization_id、Stripe 共有名前空間では jolt_ プレフィックス付き。 タグの冪等性のため、ステータス遷移が不正な場合でもこのフィールドのみ upsert される。 organization_id または email のいずれか必須 (空文字は未指定扱い、両方空なら 400)。

email
string <email> [ 1 .. 254 ] characters

ユーザーのメールアドレス。突合キーのフォールバック (既存リードの contact_email と一致するもの)。 organization_id が指定されていれば一次キーとしてはそちらが優先される。 organization_id または email のいずれか必須 (空文字は未指定扱い、両方空なら 400)。

status
required
string
Enum: "qualified" "won"

タグから設定可能なリードステータス。

  • qualified: サインアップ完了（適格 / 進行中）
  • won: 有料化完了（取引成立）。新規顧客レコードを自動作成

その他の値（new / unqualified / lost）はタグからは指定不可（400）。

company_name
string

会社名（任意 / 既存値を上書き）

last_name
string

担当者姓（任意 / 既存値を上書き）

first_name
string

担当者名（任意 / 既存値を上書き）

Responses

Request samples

Content type
application/json
Example
{
  • "program_token": "pub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "organization_id": "org_12345",
  • "email": "user@example.com",
  • "status": "qualified",
  • "company_name": "株式会社サンプル",
  • "last_name": "山田",
  • "first_name": "太郎"
}

Response samples

Content type
application/json
{ }

タグ経由のコンバージョンイベント発火（ブラウザ）

BtoC モード用のブラウザタグ公開エンドポイント。jolt-tag JS の jolt('track', '<event_name>', { amount }) から cross-origin POST で発火し、 Cookie (jolt_referral) の帰属情報を元に Referral / ConversionEvent を作成する。

旧仕様の /v1/tag/events/{signup,purchase,renewal} は廃止され、単一エンドポイントへ統合された。 イベント種別はパスではなく event_name（ベンダーが作成したコンバージョンイベント定義の slug）で指定する。

認証

APIキー不要。Cookie ベースの帰属解決のみ。vendor_program_id をボディに含める。

帰属解決と早期終了 (200)

以下のいずれかに該当する場合は ConversionEvent を作成せず、200 {success:true, status:"not_attributed"} でサイレント終了する (クロステナント誤帰属防止):

  • Cookie jolt_referral 未設定 (紹介経由でない直接アクセス)
  • Cookie の referrer_id / click_id / program_id のいずれかが空
  • Cookie の program_id がリクエスト vendor_program_id と一致しない

仕様

  • vendor_program_id / event_name / customer_contact_email 必須。
  • event_name は当該プログラムに存在するコンバージョンイベント定義の slug。未存在なら 404。
  • 帰属解決成功時は Referral を作成 (既存があれば再利用) し ConversionEvent を作成する。
  • 冪等性は external_source + external_source_id で担保（同一なら同一 ConversionEvent を返し status=idempotent_skip）。
  • 設定された Flow に応じてリファラー報酬を発火する。
  • 200 レスポンスの status は not_attributed / created / idempotent_skip のいずれか。

CORS

クロスドメインから呼ばれるためプリフライト OPTIONS を許可。credentials: include で Cookie を送ること。

Request Body schema: application/json
required
vendor_program_id
required
string

ベンダープログラムID (ULID)

event_name
required
string

コンバージョンイベント定義の slug（例 signup / purchase / renewal / 任意のカスタム slug）

customer_contact_email
required
string <email>

顧客連絡先メールアドレス

customer_name
string

顧客名

customer_contact_last_name
string

顧客担当者 姓

customer_contact_first_name
string

顧客担当者 名

amount
integer <int32> >= 0

購入金額等。パーセンテージ報酬の計算に使われる（0 / 未指定だと計算結果が 0 になり報酬は発火しない）。

external_source
string

ベンダー側ソース識別子（例 app / stripe）。external_source_id と合わせて冪等性に使う。

external_source_id
string

ベンダー側冪等 ID（例 order_12345）

metadata
string

任意の追加メタデータ。有効な JSON 文字列として送信する必要がある（例 '{"plan":"pro"}'）。 実装側で JSON としてバリデーションされ、不正な場合は 400 となる。

Responses

Request samples

Content type
application/json
Example
{
  • "vendor_program_id": "01JCK1S3TSZ4KMW6TR84KF6PR1",
  • "event_name": "signup",
  • "customer_contact_email": "customer@example.com"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "status": "created",
  • "referral_id": "01JCK1S3TSZ4KMW6TR84KF6R01",
  • "conversion_event_id": "01JCK1S3TSZ4KMW6TR84KF6CE1",
  • "conversion_event_definition_id": "01JCK1S3TSZ4KMW6TR84KF6D01"
}

サーバー経由のコンバージョンイベント発火（API キー認証）

サーバーサイド呼び出し専用エンドポイント (Stripe Webhook 等)。Cookie を使わず customer_contact_email で既存紹介を解決する。任意の external_source / external_source_id で ConversionEvent を作成できるため API キー認証 (X-Jolt-API-Key) を必須化し、 リクエストの vendor_program_id が API キーの所属プログラムと一致することをサーバー側で再検証する。

認証

X-Jolt-API-Key 必須。キーの所属 vendor_program_id とリクエストの vendor_program_id が 一致しない場合は 403。

仕様

  • vendor_program_id / event_name / customer_contact_email / external_source / external_source_id 必須。
  • customer_contact_email で既存紹介 (Referral) を解決する。該当が無い場合は未帰属として status=not_attributed。
  • 冪等性は external_source + external_source_id で担保（status=idempotent_skip）。
Authorizations:
apiKeyAuth
Request Body schema: application/json
required
vendor_program_id
required
string
event_name
required
string

コンバージョンイベント定義の slug

customer_contact_email
required
string <email>

既存紹介との突合キー

amount
integer <int32> >= 0

継続課金額等。0 以上のみ受け付ける。

external_source
required
string

必須。ベンダー側ソース識別子（例 stripe）

external_source_id
required
string

必須。ベンダー側冪等 ID（例 in_xxx）

metadata
string

任意の追加メタデータ。有効な JSON 文字列として送信する必要がある。 実装側で JSON としてバリデーションされ、不正な場合は 400 となる。

Responses

Request samples

Content type
application/json
{
  • "vendor_program_id": "01JCK1S3TSZ4KMW6TR84KF6PR1",
  • "event_name": "renewal",
  • "customer_contact_email": "customer@example.com",
  • "amount": 5000,
  • "external_source": "stripe",
  • "external_source_id": "in_xxxxxxxxxxxx",
  • "metadata": "{\"cycle\":\"monthly\"}"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "status": "created",
  • "referral_id": "01JCK1S3TSZ4KMW6TR84KF6R01",
  • "conversion_event_id": "01JCK1S3TSZ4KMW6TR84KF6CE1",
  • "conversion_event_definition_id": "01JCK1S3TSZ4KMW6TR84KF6D01"
}

StripeWebhook

Stripe Dashboard で登録する Webhook 受信先。決済成功・返金イベントを受けて取引レコード／報酬実績を作成する。

購読するイベント

Jolt が処理するのは以下の 2 つのみ。Stripe Dashboard でもこの 2 つだけを選択する。

イベント 用途
payment_intent.succeeded 一回払い・サブスク両方の決済成功 → 取引レコード作成
charge.refunded 返金 → 全額返金は論理削除、部分返金は残金額で再作成

紹介レコードの照合（3段階フォールバック）

Webhook 受信時、Jolt は以下の優先順位で紹介レコードを特定する：

  1. metadata.jolt_organization_id — クライアントサービスの組織 ID。Stripe metadata は他サービス共有名前空間のため jolt_ プレフィックスで衝突回避
  2. customer (Stripe顧客ID) — 既存クライアントとの後方互換
  3. billing_details.email — 最終フォールバック (payment_intent.succeeded イベントには含まれないため、実質サブスクでは効かない)

クライアント実装での metadata 付与

重要：Stripe の Customer.metadata は PaymentIntent に自動伝播しない。 Customer のみに metadata を付与しても、payment_intent.succeeded イベントの metadata フィールドは空となり 1段目の照合が機能しない。

確実に 1段目で照合するには、PaymentIntent 作成時にも metadata を設定する：

// Customer 作成時 (任意 — 監査用)
const customer = await stripe.customers.create({
  email: 'user@example.com',
  metadata: { jolt_organization_id: organization_id }
});

// 一回払い: PaymentIntent に必ず付与
await stripe.paymentIntents.create({
  amount, currency, customer: customer.id,
  metadata: { jolt_organization_id: organization_id }   // ← 必須
});

// サブスク (Checkout 経由): payment_intent_data.metadata に付与
// (Stripe は内部で各請求サイクル毎に PaymentIntent を作成し、その metadata がイベントに載る)
await stripe.checkout.sessions.create({
  mode: 'subscription',
  customer: customer.id,
  line_items: [...],
  payment_intent_data: {
    metadata: { jolt_organization_id: organization_id } // ← 必須
  }
});

※ Stripe metadata に乗せる値は、タグ API (POST /api/tracking/lead-status) の organization_id と 同じ値を送ること。両者は同じ「クライアントサービスの組織 ID」を表し、それぞれのレイヤで名前空間を分けるためにキー名だけ異なる:

  • タグ API リクエストパラメータ: organization_id (Jolt API 内なので Jolt は自明)
  • Stripe metadata キー: jolt_organization_id (他サービスと共有名前空間のため Jolt プレフィックス)

署名検証

Stripe Dashboard でこの Webhook 受信先を登録時に発行される署名シークレット（whsec_...）を、Jolt 管理画面の Stripe 連携設定にも登録する必要がある。 ステージング環境のみ、STRIPE_WEBHOOK_SKIP_SIGNATURE_VERIFICATION=true で署名検証をスキップ可能（playground 検証用）。本番環境では絶対に有効化されない。

Stripe Webhook 受信

Stripe Dashboard で登録する Webhook 受信先。 決済成功・返金イベントを受信して、紹介レコードに紐付く取引レコードと報酬実績を自動作成する。

設定手順

  1. Stripe Dashboard → Developers → Webhooks → Add endpoint
  2. URL に https://external-api.jolt.me/integrations/stripe/webhook/<vendor_program_id> を設定
  3. 「Listen to events on your account」で payment_intent.succeeded と charge.refunded の 2 つだけ を選択
  4. 発行された署名シークレット (whsec_...) を Jolt 管理画面の Stripe 連携設定に登録

処理対象イベント

  • payment_intent.succeeded: 一回払い・サブスクの決済成功 → 取引レコード作成 + 報酬実績作成
  • charge.refunded (全額返金): 取引レコード + 報酬実績を論理削除
  • charge.refunded (部分返金): 取引レコード + 報酬実績を論理削除し、残金額で再作成

紹介レコードの特定（3段階フォールバック）

詳細は StripeWebhook タグの説明を参照。要約：

  1. metadata.jolt_organization_id → 1段目（Stripe metadata は他サービス共有名前空間のため Jolt プレフィックス付き）
  2. customer (Stripe顧客ID) → 2段目（既存クライアント後方互換）
  3. billing_details.email → 3段目（最終フォールバック、payment_intent.succeeded には含まれない）

レスポンス

Stripe のリトライ抑止のため、内部処理が失敗しても基本的に 200 を返す（イベントは stripe_events テーブルに記録される）。

path Parameters
vendor_program_id
required
string
Example: 01K9YHPWKGF330PR9222K49J31

ベンダープログラムID (ULID)。Stripe 連携設定の宛先プログラムを特定する。

header Parameters
Stripe-Signature
required
string

Stripe が付与する署名ヘッダ。whsec_... シークレットで検証される。 staging 環境で STRIPE_WEBHOOK_SKIP_SIGNATURE_VERIFICATION=true の場合のみ省略可（playground 用、本番では不可）。

Request Body schema: application/json
required

Stripe が送信するイベントオブジェクト（Event object）。 Jolt 側では data.object.metadata.jolt_organization_id などを参照するが、エンベロープ全体は Stripe 仕様に従う。

id
string

Stripe イベント ID

type
string
Enum: "payment_intent.succeeded" "charge.refunded"

イベントタイプ

livemode
boolean

本番モードかどうか

object

イベント本体（data.object に Stripe オブジェクトが入る）

Responses

Request samples

Content type
application/json
{
  • "id": "evt_1Abc...",
  • "type": "payment_intent.succeeded",
  • "livemode": true,
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

WebhookEvents

登録された Webhook URL に送信されるイベントペイロード。 各イベントは共通の Envelope 構造でラップされ、type フィールドでイベント種別を識別できます。 Webhook 受信側は HTTP 200 を返却してください。

リード作成イベント

新しいリード（紹介案件）が作成された際に送信されるイベント。 type: "lead.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "lead.created"

イベント種別: lead.created(新規リード作成時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (LeadCreatedData)

リード作成イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "lead.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リードステータス更新イベント

リードのステータスが更新された際に送信されるイベント。 type: "lead.status"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "lead.status"

イベント種別: lead.status(リードステータス更新時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (LeadStatusData)

リードステータス更新イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "lead.status",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

報酬作成イベント

新しい報酬レコードが作成された際に送信されるイベント。 type: "reward.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "reward.created"

イベント種別: reward.created(新規報酬作成時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (RewardCreatedData)

報酬作成イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "reward.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

報酬ステータス更新イベント

報酬のステータスが更新された際に送信されるイベント。 type: "reward.status"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "reward.status"

イベント種別: reward.status(報酬ステータス更新時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (RewardStatusData)

報酬ステータス更新イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "reward.status",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

パートナープログラム申請イベント

パートナーがベンダープログラムに申請した際に送信されるイベント。 type: "vendor_program.partner.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "vendor_program.partner.created"

イベント種別: vendor_program.partner.created(プログラムにパートナーが申請時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (VendorProgramPartnerCreatedData)

パートナープログラム申請イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "vendor_program.partner.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

パートナーステータス更新イベント

パートナーのプログラム参加ステータスが更新された際に送信されるイベント。 type: "vendor_program.partner.status"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "vendor_program.partner.status"

イベント種別: vendor_program.partner.status(プログラム参加中パートナーステータス更新時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (VendorProgramPartnerStatusData)

パートナーステータス更新イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "vendor_program.partner.status",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

活動ログ作成イベント

新しい活動ログが作成された際に送信されるイベント。 type: "referral_activity_log.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referral_activity_log.created"

イベント種別: referral_activity_log.created(新規活動ログ作成時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ActivityLogCreatedData)

活動ログ作成イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referral_activity_log.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラー リード作成イベント

リファラー経由のリンクから新しいリードが作成された際に送信されるイベント。 パートナー経由の lead.created とは別イベントとして発火するため、リファラー経由のリードだけを別ルートに流せる。 type: "referrer.lead.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.lead.created"

イベント種別: referrer.lead.created(リファラー経由のリンクからリード作成時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerLeadCreatedData)

リファラー リード作成イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.lead.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラー登録イベント

リファラー（紹介者）が新規登録された際に送信されるイベント。 type: "referrer.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.created"

イベント種別: referrer.created(リファラー新規登録時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerCreatedData)

リファラー登録イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラー認証完了イベント

リファラーがマジックリンク認証を完了した際に送信されるイベント。 type: "referrer.verified"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.verified"

イベント種別: referrer.verified(リファラーがマジックリンク認証を完了した時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerVerifiedData)

リファラー認証完了イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.verified",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラーブロックイベント

リファラーがベンダーによってブロックされた際に送信されるイベント。 type: "referrer.blocked"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.blocked"

イベント種別: referrer.blocked(リファラーがブロックされた時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerStatusData)

リファラーステータス更新イベントのデータ（blocked / unblocked 共通）

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.blocked",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラーブロック解除イベント

リファラーのブロックが解除された際に送信されるイベント。 type: "referrer.unblocked"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.unblocked"

イベント種別: referrer.unblocked(リファラーのブロック解除時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerStatusData)

リファラーステータス更新イベントのデータ（blocked / unblocked 共通）

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.unblocked",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

コンバージョンイベント作成

ベンダー (BtoC) でコンバージョンイベントが作成された際に送信されるイベント。 signup / purchase / custom / renewal のいずれも conversion_event.created 単一イベントとして発火し、サブタイプは data.event_type で識別する。 type: "conversion_event.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "conversion_event.created"

イベント種別: conversion_event.created

sent_at
required
string <date-time>

送信日時 (JST)。実装は time.Now().In(JST) で生成するため、Z ではなく +09:00 オフセット付きで出力される。

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ConversionEventCreatedData)

コンバージョンイベント作成のデータ。signup / purchase / custom / renewal で共通フィールド構造。

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "conversion_event.created",
  • "sent_at": "2025-01-15T18:30:00+09:00",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}