ヘルプセンター統合

のために: 管理者

管理キーを持つケースとユーザーを検索

独自のソフトウェアから、テキスト、フィルターを使用して、ケース、人物、ケースメンバー、役割を検索し、行をインポートします。

この記事では6 セクション

始める前に

このページでは、GET https://prd-api-manage.caseactive.com/v1/<hub id>/searchについて説明しています。これは、テキストを基にして、ユーザーのハブ内で記録を検索する機能です。この機能は、ユーザーの自分のハブ内でのみ検索を行います。

パラメータ

パラメータその機能必須デフォルト
table探すべきもの:cases、host_users、case_users、host_roles、case_invoices、host_imports、またはimport_itemsはい。—
query探すべきテキストです。*は、フィルターによる検索だけで、すべての項目と一致します。はい。—
query_by調べるべきテキストフィールドの一覧です。各フィールドはコンマで区切られています。例:given_name,family_name,emailはい。—
filter_bycase_status:=1のような条件が1つあります。さらに多くの条件を追加するには、同じパラメータを繰り返す必要があります。すべての条件が正しく成立している必要があります。いいえ。なし
sort_by数の領域や方向を示すもの、例えば created_on:desc のようなものです。いいえ。最適なマッチング
pageどのページですか?いいえ。1
limit1ページに表示できる内容の数は、最大で250件です。いいえ。10
  • queryという文字列は、その始まりから一致します。つまり、1、2回のタイプミスがあっても問題ありません。したがって、janはJaneを検出できます。タグIDや名前、メールアドレス、電話番号、参照IDの場合も同様で、end-2026はrear-end-2026と一致します。
  • フィルターとは、フィールド、オペレータ、そして値のことです。例えば、「:=」は正しい値を表し、「:!=」は不正な値を表します。また、数値の場合には、「:>」「:<」「:>=」「:<=」といったフィルターが使われます。条件式には、「&&」「||」や括弧やコンマは含めることができません。その代わりに、複数の「filter_by」を指定する方が良いでしょう。値としては、「/」や「+」を含むことができます。例えば、「ref_id:=2026/rear-end」や「phone:=+15551234567」のようにです。アドレスでは、「+」を「%2B」として送信すると、スペースとして処理されます。
  • ソートできるのは数値型のフィールドだけです。結果に表示される日付は、Unix秒で表されています。
  • レコードが作成されたり変更された後、表示されるまでには、数分かかることがあります。
  • 質問内容は、キーを使って検索することはできません。

表

table検索とフィルタリングを行うためのテキストフィールド数値フィールド、フィルタリングとソートに使用
casescase_id, ref_id(タグのID)タグID ケースに付ける永続的なラベル。例えば、rear-end-2026 など。参照 ID としても表示され、インポート時に使用されます。, title, description, case_type, case_stage, users(メンバーのユーザーID)case_status (1は開いており、0は閉じている)、users_ct、date_opened、created_on、last_activity、updated_on
host_usersuser_id, given_name, family_name, email, phone, host_ref_id, title, company, address1, address2, locality, region, postal_code, country, gender, birthdate_md(月と日の形式で表されるもの、例:04-12)、locale, zoneinfo, host_user_type, host_granted_status, host_default_role, host_staff_designationhost_user_status (1 アクティブ、0 ディスエイブル)、host_cases_ct、email_verified、phone_verified、created_on、updated_on
case_userscase_id、user_id、case_ref_id、case_role_id、そしてケースのtitleとdescriptioncase_status, created_on, updated_on
host_rolesrole_id, name, role_type, permissions, case_read_fields, case_write_fieldsusers_ct, created_on, updated_on
case_invoicesinvoice_id, name, invoice_number, po_number, host_ref_id, description, notes, status (open, paid, void, uncollectibleまたはprocessing), status_reason, payment_gateway, case_id, user_id, participants_ids, refund_status (pending, succeeded, failedまたはcanceled), refund_reason, completed_on_daytotal, subtotal, discount, tax, refund_amount, payment_attempts_ct, due_date, completed_on, created_on, updated_on
host_importsimport_id, name, source, type, user_id, statustotal, passed, failed, created_on, updated_on
import_itemsimport_id, unique_id, type, status, error_msg, error_recordcreated_on, updated_on

host_usersには、ユーザーのハブにあるバーチャルアシスタントバーチャルアシスタント 会社への歓迎メッセージ、チェックイン、ステージングに関する投稿を行う自動化されたチームメンバー。その投稿にはバーチャルアシスタントのバッジが付いています。が含まれています。そのhost_user_typeの値はbotです。case_usersには何も記載されていません。その人物をhost_usersで探し出し、case_usersをuser_idでフィルタリングします。case_invoicesには、発行された請求書のみが含まれています。その金額はセント単位で表示されます。また、taxとdiscountは分数です。返金された請求書の場合、status paidの値は保持されます。返金の金額はrefund_statusで表示されます。

例

タグIDによるケース:

curl -G https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "table=cases" \
  --data-urlencode "query=*" \
  --data-urlencode "query_by=ref_id" \
  --data-urlencode "filter_by=ref_id:=rear-end-2026"

名前やメールアドレスの先頭がjaneで始まる人々の中から、最新の情報を表示します。

curl -G https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "table=host_users" \
  --data-urlencode "query=jane" \
  --data-urlencode "query_by=given_name,family_name,email" \
  --data-urlencode "filter_by=host_user_status:=1" \
  --data-urlencode "sort_by=created_on:desc"

一つのケースを開いてみましょう。 ステージステージ 案件が進む段階の一つで、例えば「受付」や「請求書送付」などがあり、企業が名称と説明を付け、案件ページに表示されます。, 使用する stage_id から GET /stages: table=cases&query=*&query_by=title&filter_by=case_status:=1&filter_by=case_stage:=stage::20260927120000_8c1f0e2d3b4a59.

2026年10月8日午前0時以降に請求書が変更されました。最も古い変更内容から表示されます:table=case_invoices&query=*&query_by=name&filter_by=updated_on:>1791417600&sort_by=updated_on:asc

結果

{
  "data": {
    "found": 1,
    "page": 1,
    "hits": [
      {
        "document": {
          "case_id": "cc-1a2b3c4d5e6f70",
          "host_id": "ca-7e6d5c4b3a2f10",
          "ref_id": "rear-end-2026",
          "title": "Jane Sample auto accident",
          "case_type": "general",
          "case_status": 1,
          "users": ["cu-4f1c2a9e8b7d60", "cu-9d8c7b6a5f4e30"],
          "users_ct": 2,
          "date_opened": 1790899200,
          "created_on": 1790949909,
          "updated_on": 1790949909
        }
      }
    ]
  }
}

foundとは、どれだけのレコードが一致するかを示します。各ヒットに対してのdocumentは、そのレコードの情報です。また、ヒット情報には、検索エンジン独自のスコアフィールドも含まれていますが、これらは無視しても問題ありません。nextLinkというフィールドは存在しません。次のpageを求めるまで、foundまでの結果を待ちます。

単語検索では、似ている値も一致することがあります。したがって、IDによってレコードを検索する際には、得られるdocumentの値も確認する必要があります。

電話が拒否された場合

状態messageなぜ
400SchemaFieldsExceptiontable、query、またはquery_byが欠落しているか、不明です。また、filter_byには、その文字を含むことができない文字が含まれています。(FieldSearchFilterTypeException、filter_by.0の場合)
400SearchParameterException検索エンジンは、そのデータを認識できませんでした。不明なフィールドであり、エンジンが読み取れないフィルターだったからです。また、sort_by内にあるテキストフィールドや、limit内のテキストも、250文字以上でした。reasonには、検索エンジン自身のメッセージが記録されていました。
403BotSearchTableNotAllowedExceptionあなたはhost_inquiriesを要求しましたが、キーではそのようなものを検索することはできません。
500InternalError検索エンジンが利用できません。後で再試行してください。

関連記事

管理キーを使用してケースを作成および更新します。ハブのケースを、ステージやカスタムフィールドを含め、独自のソフトウェアから一覧表示、作成、閲覧、更新、削除できます。統合管理キーを使用してユーザーを追加および更新します。ハブのメンバー一覧を表示したり、クライアントを追加したり、個々のユーザーの詳細情報や案件を閲覧したり、アクセス権を無効化または有効化したりできます。統合