> ## Documentation Index > Fetch the complete documentation index at: https://docs.stockwork.ai/llms.txt > Use this file to discover all available pages before exploring further. # コンタクト活動を取得(要約を入れ子で同梱) > コンタクト活動を単体取得する。応答には紐づく要約(`summaries`)が入れ子で含まれる。 ## OpenAPI ````yaml /openapi/v1.yaml get /v1/contact-activities/{record_id}/ openapi: 3.0.3 info: title: Stockwork Public API version: 1.0.0 description: > Stockwork の取引(Deal)・会社(Account)・コンタクト(Contact)・商談ログ(Meeting Log)・ コンタクト活動(Contact Activity)を外部システムから操作する公開 API。 ## 認証 `Authorization: Bearer sk_` 形式の API キーを送る。 キーは Stockwork 管理画面で発行し、発行時のみ平文が 1 回だけ返却される(以降は再表示不可)。 ## 識別子 Stockwork が発行する `id`(record_id、18 文字)が**全レコードの唯一の identity**。 クライアントはこの `id` を保存し、以降の取得・更新に使用する。 レコード間の参照もすべて record_id で行う。`properties.account_id`(Contact → Account)、 `properties.deal_id`(Meeting Log → Deal)、`properties.contact_id`(Contact Activity → Contact)、`properties.owner_id`(Deal → User)。担当ユーザーの氏名・メールアドレスは `GET /v1/users/` で解決する。 メールアドレスから担当者の record_id を引きたい場合は `GET /v1/users/?email=...` を使う。 ただしこれは**発見用のフィルタであって識別子ではない**。メールアドレスは変更され得るため、 解決した record_id を保存して以降の参照に使うこと(HubSpot / Salesforce と同じ作法)。 ## エラー 全てのエラーは次の封筒で返る。`error.code` は機械可読な enum、`error.message` は人間向けの 説明文(日本語)。バリデーション失敗時のみ `error.fields` にフィールド単位の詳細が入る。 ```json { "error": { "code": "validation_error", "message": "リクエストの検証に失敗しました。", "fields": [ {"name": "properties.name", "code": "required", "message": "この項目は必須です。"} ] } } ``` ## ロール API キー発行時に付与する **role** で操作範囲を制限する。Stockwork 既存の組織ロールと 同じ概念を流用(リソース単位の細かいスコープ分割は提供しない): - `read` — 読み取りのみ - `analyst` — 読み取り + 分析(本 API では read 相当) - `write` — 読み取り + 書き込み - `admin` — 全権限 ### エンドポイントと必要 role の対応 | メソッド + パス | 必要 role | |---|---| | `GET /v1/deals/` / `/v1/deals/{record_id}/` / `/v1/deals/properties/` | `read` | | `POST /v1/deals/search/` | `read` | | `POST /v1/deals/` / `PATCH /v1/deals/{record_id}/` | `write` | | `GET /v1/companies/` / `/v1/companies/{record_id}/` / `/v1/companies/properties/` | `read` | | `POST /v1/companies/search/` | `read` | | `POST /v1/companies/` / `PATCH /v1/companies/{record_id}/` | `write` | | `GET /v1/contacts/` / `/v1/contacts/{record_id}/` / `/v1/contacts/properties/` | `read` | | `POST /v1/contacts/search/` | `read` | | `POST /v1/contacts/` / `PATCH /v1/contacts/{record_id}/` | `write` | | `GET /v1/meeting-logs/` / `/v1/meeting-logs/{record_id}/` / `/v1/meeting-logs/properties/` | `read` | | `POST /v1/meeting-logs/search/` | `read` | | `POST /v1/meeting-logs/` / `PATCH /v1/meeting-logs/{record_id}/` | `write` | | `GET /v1/contact-activities/` / `/v1/contact-activities/{record_id}/` / `/v1/contact-activities/properties/` | `read` | | `POST /v1/contact-activities/search/` | `read` | | `POST /v1/contact-activities/` / `PATCH /v1/contact-activities/{record_id}/` | `write` | | `GET /v1/users/` / `/v1/users/{record_id}/` | `read` | 上位 role は下位 role を内包する(`write` キーは `read` 操作も可)。 ## 検索(プロパティ値による絞り込み) GUI 一覧画面と同等の表現力でレコードを検索できる `POST /v1//search/` を提供する。クエリ文字列ではなく POST body にフィルタを含めるため、WAF / 中間機器の URL 長制限の影響を受けない。 - **2 階層構造**: グループ間 OR / グループ内 AND(GUI と同じ。最大 10 グループ) - **対象フィールド**: コアフィールド(`name` / `amount` / `stage` 等)+ カスタム プロパティ(`PropertyDefinition.api_name` で指定) - **operator**: text / number / date / select / boolean のそれぞれに必要な集合を提供 (詳細は `FilterOperator` schema) - **select 値の解決**: ラベルではなく**内部値の完全一致**のみ(fuzzy match なし) - **`is_null` / `is_empty` の意味論**: 該当プロパティの値レコードが存在しない場合も 含める(GUI と同じ) - **ページネーション**: 検索はページ番号型(`page` / `page_size`)。任意の複合ソート (`sort_by` / `sort_order`)を許すため、カーソル型とは両立しない。 `page * page_size` は **10,000 を超えられない**(超過時は `400`)。 全件走査には `GET /v1//?updated_after=...` のカーソルページネーションを使う。 ## `updated_at` と差分取得 `updated_at` は**レコードの値が最後に変わった日時**で、行への書き込み日時ではない。 コアフィールド・カスタムプロパティ・アクティビティ件数などの集計値のいずれかが実際に 変わったときに進む。商談ログやメールを記録した場合も、それが集計値を動かすため進む。 同じ値での再保存（SFA 同期が同一値を書き戻した場合を含む）、他レコードとの紐付け変更、 日次バッチが再計算する予測値（受注確率・ヘルススコア）では進まない。 `updated_after` を差分同期のウォーターマークに使う場合、活動の記録でも親レコードが 再取得対象になる点に注意する。 ## レート制限 - API キー単位: `1000 / 分` - 組織合算: `5000 / 分` 全レスポンス(成功・失敗を問わず)に次のヘッダを付与する。クライアントは残量を見て 事前に減速できる。 - `X-RateLimit-Limit` — 現在の窓の上限回数(API キー単位) - `X-RateLimit-Remaining` — 現在の窓の残り回数 - `X-RateLimit-Reset` — 窓がリセットされる Unix 時刻(秒) 超過時は `429 Too Many Requests` + `Retry-After` ヘッダ。 contact: name: Stockwork Public API Support servers: - url: https://api.strixai.jp description: Production - url: https://api-dev.strixai.jp description: Development(検証環境) security: - BearerApiKey: [] tags: - name: Deals description: 取引リソース - name: Companies description: 会社(Account)リソース - name: Contacts description: コンタクトリソース - name: Meeting Logs description: 商談ログ(Deal 配下の活動)リソース - name: Contact Activities description: コンタクト活動(Contact 配下の活動)リソース - name: Users description: Stockwork ユーザー(担当者)リソース。read-only paths: /v1/contact-activities/{record_id}/: parameters: - $ref: '#/components/parameters/RecordId' get: tags: - Contact Activities summary: コンタクト活動を取得(要約を入れ子で同梱) description: | コンタクト活動を単体取得する。応答には紐づく要約(`summaries`)が入れ子で含まれる。 responses: '200': description: 取得成功 content: application/json: schema: $ref: '#/components/schemas/ContactActivityDetail' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' security: - BearerApiKey: [] components: parameters: RecordId: name: record_id in: path required: true schema: type: string pattern: ^[A-Za-z0-9]{18}$ description: Stockwork record_id(18 文字英数字) schemas: ContactActivityDetail: description: | コンタクト活動の単一レコード表現。`ContactActivity` に要約(`summaries`)を加えたもの。 取得 / 作成 / 更新の応答で返る(一覧・検索では返らない)。 allOf: - $ref: '#/components/schemas/ContactActivity' - type: object properties: summaries: type: array description: 紐づく要約。read-only。未生成時は空配列。 items: $ref: '#/components/schemas/ActivitySummary' required: - summaries example: id: Ca7XkQpYz3Lh9vMs2N properties: contact_id: Co7XkQpYz3Lh9vMs2N subject: 問い合わせフォーム送信 occurred_at: '2026-06-12T05:00:00Z' genre: inbound content: 資料請求フォームから問い合わせ。予算検討中との記載あり。 summaries: - summary_type: 問い合わせ要約 result_type: text text: |- ## 関心 - 価格と導入期間 ## 温度感 - 中(予算検討中) selections: [] reason: '' status: completed updated_at: '2026-06-12T05:30:00Z' created_at: '2026-06-12T05:10:00Z' updated_at: '2026-06-12T05:30:00Z' ContactActivity: type: object description: | コンタクト活動(Contact Activity)。1 つのコンタクト(Contact)配下に蓄積される 活動レコードで、商談ログ(Meeting Log)と対称な構造を持つ。 親コンタクトへは `properties.contact_id` で紐づく。 この schema は一覧・検索の要素(`summaries` を含まない軽量表現)。 properties: id: type: string description: Stockwork record_id(18 文字) example: Ca7XkQpYz3Lh9vMs2N properties: allOf: - $ref: '#/components/schemas/PropertiesMap' description: | 活動のプロパティ集合。`contact_id`(親コンタクト)・`occurred_at`・`content` を中心に、 `subject` / `genre` 等のコアフィールドとカスタムプロパティが同じ namespace。 created_at: type: string format: date-time updated_at: type: string format: date-time description: >- レコードの値が最後に変わった日時。コアフィールド・カスタムプロパティ・アクティビティ件数などの集計値のいずれかが実際に変わったときに進む。商談ログやメールなどの活動を記録した場合も、それが集計値を動かすためこの日時が進む。同じ値での再保存や、他レコードとの紐付け変更では進まない。 required: - id - properties - created_at - updated_at example: id: Ca7XkQpYz3Lh9vMs2N properties: contact_id: Co7XkQpYz3Lh9vMs2N subject: 問い合わせフォーム送信 occurred_at: '2026-06-12T05:00:00Z' genre: inbound content: 資料請求フォームから問い合わせ。予算検討中との記載あり。 created_at: '2026-06-12T05:10:00Z' updated_at: '2026-06-12T05:30:00Z' ActivitySummary: type: object description: | 活動(Activity)に紐づく要約。外部システム連携における「ヒアリングシート」に相当。 Stockwork の分析が生成する派生データで、`record_id` を持たず**読み取り専用**。 単一レコード表現(取得 / 作成 / 更新の応答)にのみ入れ子で含まれ、 一覧・検索の応答には含まれない(コレクションは軽量表現を返す)。 MeetingSummary / ContactSummary を共通の形で表す。 要約タイプには**本文型(`text`)**と**選択肢型(`select`)**の 2 種類がある。 `result_type` で分岐し、本文型は `text` に、選択肢型は `selections` に値が入る。 両者を 1 つのフィールドに混ぜないため、クライアントは `result_type` を見て処理する。 properties: summary_type: type: string description: 要約タイプ名(観点)。例 ヒアリングシート result_type: type: string enum: - text - select description: 要約の結果形式。`text` なら `text`、`select` なら `selections` に値が入る。 text: type: string nullable: true description: | 要約本文。**マークダウン形式**。`result_type` が `text` のときのみ非 null。 selections: type: array description: | 選択結果。`result_type` が `select` のときのみ非空。`level` 昇順に並ぶ (親 → 子)。本文型のときは空配列。 items: $ref: '#/components/schemas/SummarySelection' reason: type: string description: | 選択理由。`result_type` が `select` のとき、Stockwork の分析が選択根拠を残していれば入る。 本文型のときは空文字列。 status: type: string enum: - pending - processing - completed - failed description: 分析ステータス。`completed` が Webhook 完了通知のトリガー。 updated_at: type: string format: date-time required: - summary_type - result_type - text - selections - reason - status - updated_at example: summary_type: ヒアリングシート result_type: text text: |- ## 課題 - 既存システムの運用コストが高い ## 予算 - 500万円規模 ## 決裁フロー - 部長承認 → 役員決裁 selections: [] reason: '' status: completed updated_at: '2026-06-12T05:40:00Z' Error: type: object description: | 全エラーレスポンスの共通封筒。 properties: error: type: object properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: 人間向けの説明文(日本語) fields: type: array description: | `code` が `validation_error` のときのみ存在。フィールド単位の詳細。 items: $ref: '#/components/schemas/FieldError' required: - code - message required: - error example: error: code: validation_error message: リクエストの検証に失敗しました。 fields: - name: properties.name code: required message: この項目は必須です。 PropertiesMap: type: object description: | プロパティの集合。キーは `api_name`、値は `PropertyValue`。 コアフィールドと組織別カスタムプロパティが同じ namespace に並ぶ。 利用可能なキーと型は `GET /v1//properties/` で取得する。 additionalProperties: $ref: '#/components/schemas/PropertyValue' SummarySelection: type: object description: | SELECT 型要約の選択結果。1 つの選択は階層パス(最大 3 階層)として表現され、 `level` 昇順で親から子へ並ぶ。 properties: value: type: string description: 選択肢の値 level: type: integer minimum: 0 maximum: 2 description: 階層レベル(0 が最上位) order: type: integer description: 同一階層内の並び順 required: - value - level - order ErrorCode: type: string description: | 機械可読なエラー種別。HTTP ステータスと 1 対 1 ではない(`400` は `validation_error` と `invalid_request` の両方を取り得る)ため、 クライアントは**このコードで分岐する**こと。 今後の追加に備え、未知のコードは汎用エラーとして扱うこと。 enum: - invalid_request - validation_error - unauthorized - forbidden - not_found - rate_limited - internal_error FieldError: type: object description: バリデーション失敗時のフィールド単位の詳細 properties: name: type: string description: 対象フィールドのパス。`properties` 配下は `properties.` で表す example: properties.name code: type: string description: > フィールド単位のエラー種別。 `required` / `invalid_type` / `invalid_value` / `not_found` / `unknown_property` / `too_long` / `out_of_range` のいずれか。 example: required message: type: string description: 人間向けの説明文(日本語) example: この項目は必須です。 required: - name - code - message PropertyValue: description: | プロパティの値。文字列・数値・真偽値・null のいずれか。 - **キーを送らない** = そのプロパティは変更しない(PATCH は部分更新) - **明示的に `null` を送る** = そのプロパティの値をクリアする 作成(`POST`)時の `null` は「値なしで作成」と同義。 必須プロパティに `null` を送った場合は `400`。 (OpenAPI 3.0 では union に null 型を直接書けないため、`anyOf` の各分岐に `nullable: true` を付けて表現している。`oneOf` にすると null が全分岐にマッチして 「ちょうど 1 つ」の条件を満たせない。) anyOf: - type: string nullable: true - type: number nullable: true - type: boolean nullable: true responses: Unauthorized: description: 認証失敗(キー欠落・不正・失効・IP 拒否) content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: スコープ不足 content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: | リソース無し。他組織のレコードを指定した場合も、存在の有無を漏らさないため `403` ではなく `404` を返す。 content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: レート制限超過(`Retry-After` ヘッダあり) headers: Retry-After: schema: type: integer description: 次のリクエストまでの待機秒数 content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerApiKey: type: http scheme: bearer bearerFormat: sk_* description: | Stockwork が発行する API キー(`sk_` プレフィックス、base62 ランダム ≥ 40 文字)。 キーには 1 つの role(`read` / `analyst` / `write` / `admin`)が紐付き、 各エンドポイントの必要 role 以上であることが要求される(対応表は info.description 参照)。 ````