のために: 管理者
管理キーを持つケースとユーザーを検索
独自のソフトウェアから、テキスト、フィルターを使用して、ケース、人物、ケースメンバー、役割を検索し、行をインポートします。
この記事では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_by | case_status:=1のような条件が1つあります。さらに多くの条件を追加するには、同じパラメータを繰り返す必要があります。すべての条件が正しく成立している必要があります。 | いいえ。 | なし |
sort_by | 数の領域や方向を示すもの、例えば created_on:desc のようなものです。 | いいえ。 | 最適なマッチング |
page | どのページですか? | いいえ。 | 1 |
limit | 1ページに表示できる内容の数は、最大で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 | 検索とフィルタリングを行うためのテキストフィールド | 数値フィールド、フィルタリングとソートに使用 |
|---|---|---|
cases | case_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_users | user_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_designation | host_user_status (1 アクティブ、0 ディスエイブル)、host_cases_ct、email_verified、phone_verified、created_on、updated_on |
case_users | case_id、user_id、case_ref_id、case_role_id、そしてケースのtitleとdescription | case_status, created_on, updated_on |
host_roles | role_id, name, role_type, permissions, case_read_fields, case_write_fields | users_ct, created_on, updated_on |
case_invoices | invoice_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_day | total, subtotal, discount, tax, refund_amount, payment_attempts_ct, due_date, completed_on, created_on, updated_on |
host_imports | import_id, name, source, type, user_id, status | total, passed, failed, created_on, updated_on |
import_items | import_id, unique_id, type, status, error_msg, error_record | created_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 | なぜ |
|---|---|---|
| 400 | SchemaFieldsException | table、query、またはquery_byが欠落しているか、不明です。また、filter_byには、その文字を含むことができない文字が含まれています。(FieldSearchFilterTypeException、filter_by.0の場合) |
| 400 | SearchParameterException | 検索エンジンは、そのデータを認識できませんでした。不明なフィールドであり、エンジンが読み取れないフィルターだったからです。また、sort_by内にあるテキストフィールドや、limit内のテキストも、250文字以上でした。reasonには、検索エンジン自身のメッセージが記録されていました。 |
| 403 | BotSearchTableNotAllowedException | あなたはhost_inquiriesを要求しましたが、キーではそのようなものを検索することはできません。 |
| 500 | InternalError | 検索エンジンが利用できません。後で再試行してください。 |