> ## 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. # ユーザーを一覧取得 > API キーの組織に所属するユーザーを返す。`properties.owner_id` に指定する record_id を引くために使う。read-only(作成・更新・削除は提供しない)。 担当者のメールアドレスが分かっている場合は `?email=` で 1 往復で解決できる。 ただし**メールアドレスは識別子ではない**。解決した `id`(record_id)を保存し、 以降の参照にはそれを使うこと。 ## OpenAPI ````yaml /openapi/v1.yaml get /v1/users/ 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/users/: get: tags: - Users summary: ユーザーを一覧取得 description: | API キーの組織に所属するユーザーを返す。`properties.owner_id` に指定する record_id を引くために使う。read-only(作成・更新・削除は提供しない)。 担当者のメールアドレスが分かっている場合は `?email=` で 1 往復で解決できる。 ただし**メールアドレスは識別子ではない**。解決した `id`(record_id)を保存し、 以降の参照にはそれを使うこと。 parameters: - $ref: '#/components/parameters/UserEmail' - $ref: '#/components/parameters/UpdatedAfter' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': description: 一覧取得成功 content: application/json: schema: $ref: '#/components/schemas/UserListResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' security: - BearerApiKey: [] components: parameters: UserEmail: name: email in: query required: false schema: type: string format: email description: | メールアドレスの完全一致(大文字小文字は区別しない)で絞り込む。 `properties.owner_id` に入れる record_id を、担当者のメールアドレスから 1 往復で 引くための**発見用フィルタ**。識別子そのものではないため、解決した record_id を 保存して以降の参照に使うこと(メールアドレスは変更され得る)。 該当なしの場合は空の `results` を返す(404 ではない)。 UpdatedAfter: name: updated_after in: query schema: type: string format: date-time description: 指定日時以降に更新されたレコードのみを返す Limit: name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 100 description: 1 ページあたりの最大件数 Cursor: name: after in: query schema: type: string description: 次ページ取得用カーソル。前回レスポンスの `paging.next.after` をそのまま渡す schemas: UserListResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/User' paging: $ref: '#/components/schemas/Paging' required: - results - paging User: type: object description: | Stockwork ユーザー(担当者)。read-only。 `properties.owner_id` 等が参照する先で、API キーの組織に所属するユーザーのみが見える。 公開するのは連携に必要な最小限の属性だけで、権限フラグや認証情報は含まない。 properties: id: type: string description: Stockwork record_id(18 文字) example: Us7XkQpYz3Lh9vMs2N email: type: string format: email description: メールアドレス(Stockwork 全体で一意) name: type: string description: 表示名(姓 + 名)。未設定の場合は空文字列 is_active: type: boolean description: 当該組織における所属が有効か required: - id - email - name - is_active example: id: Us7XkQpYz3Lh9vMs2N email: yamada@example.co.jp name: 山田 太郎 is_active: true Paging: type: object description: ページネーション情報 properties: next: type: object nullable: true description: 次ページが無いときは null properties: after: type: string description: 次ページ取得用カーソル link: type: string format: uri description: 次ページの完全 URL required: - after - link 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: この項目は必須です。 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 responses: BadRequest: description: バリデーション失敗 content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: 認証失敗(キー欠落・不正・失効・IP 拒否) content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: スコープ不足 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 参照)。 ````