検索
CRM全体でオブジェクト、レコード、エンゲージメントの絞り込み、並べ替え、検索を行うには、CRM検索エンドポイントを使用します。例えば、これらのエンドポイントを使用して、アカウント内のコンタクトのリストや進行中の全取引のリストを取得できます。
アプリからこれらのエンドポイントを使用するには、CRMスコープが必要です。目的を達成するためにどれくらい詳細なスコープが必要であるかに関しては、使用可能なスコープのリストをご参照ください。
CRM内を検索するには、オブジェクトの検索エンドポイントにPOST
リクエストを送信します。CRM検索エンドポイントは、次の形式で記述されます。
/crm/v3/objects/{object}/search
基本検索を行う(追加の絞り込みまたは並べ替えを行わずに既定のプロパティーのみを返す)には、リクエスト本文に空のオブジェクトのみを含めます。以下に例を示します。
CRMオブジェクト
検索可能なCRMオブジェクト、その検索エンドポイント、および既定で返されるプロパティーを下の表に記載します。返されるプロパティーの指定については後述の詳細をご確認ください。
オブジェクト | 検索エンドポイント | 既定で返されるプロパティー |
---|---|---|
会社 |
|
|
コンタクト |
|
|
カスタムオブジェクト |
|
|
取引 |
|
|
フィードバック送信 |
|
|
製品 |
|
|
チケット |
|
|
商品項目 |
|
|
見積もり |
|
|
エンゲージメント
検索可能なCRMエンゲージメント、その検索エンドポイント、および既定で返されるプロパティーを下記の表に示します。返されるプロパティーの指定については後述の詳細をご確認ください。
エンゲージメント | 検索エンドポイント | 既定で返されるプロパティー |
---|---|---|
コール |
|
|
Eメール |
|
|
ミーティング |
|
|
メモ |
|
|
タスク |
|
|
プロパティー値が一致するレコードのみを結果に表示するには、リクエスト本文にフィルターを使用します。例えば、以下のリクエストでは、名が「Alice」である全てのコンタクトが検索されます。
複数のフィルター条件を指定する場合は、filterGroups
内でフィルターをグループ化できます。
filterGroup
内に複数のfilter
がある場合は、「AND」論理演算子によって結合されます。- リクエスト本文に複数の
filterGroup
が含まれる場合は、「OR」論理演算子によって結合されます。
最大3つのfilterGroup
を含めることができ、各グループに最大3つのfilter
を含めることができます。例えば以下のリクエストでは、名がAlice
で、かつ(AND)姓がSmith
以外であるか、または(OR)enum
プロパティーに値が設定されている、全てのコンタクトが検索されます。
別の例として、BETWEEN
演算子を使用して、特定の期間内に最終の更新が加えられた全てのタスクを検索することもできます。
フィルターでは以下の演算子を使用できます。
演算子 | Description |
---|---|
LT
| 次の値より小さい |
LTE
| 次の値以下 |
GT
| 次の値より大きい |
GTE
| 次の値以上 |
EQ
| 次の値に一致する |
NEQ
| 次の値に一致しない |
BETWEEN
| 指定の範囲内に含まれる。リクエストでは、キーと値のペアを使用して |
IN
| 指定のリストに含まれる。この演算子は大文字と小文字を区別するため、入力値は小文字でなければなりません。 |
NOT_IN
| 指定のリストに含まれない |
HAS_PROPERTY
| 指定のプロパティーに値がある |
NOT_HAS_PROPERTY
| 指定のプロパティーに値がない |
CONTAINS_TOKEN
| トークンが含まれる。リクエストにワイルドカード(*)を使用して部分検索を実行できます。例えば、HubSpotのEメールアドレスを持つコンタクトを検索するには、 |
NOT_CONTAINS_TOKEN
| トークンが含まれない |
他の特定のレコードに関連付けられているレコードを検索するには、疑似プロパティーassociations.{objectType}
を使用します。
例えば、以下のリクエストでは、コンタクトIDが123
のコンタクトに関連付けられている全てのチケットが検索されます。
以下の疑似プロパティー値を使用して、関連付けを検索できます。
associations.company
associations.contact
associations.ticket
associations.deal
associations.quote
注:現在のところ、カスタムオブジェクトの関連付けを検索するオプションは、検索エンドポイントではサポートされていません。カスタムオブジェクトの関連付けを検索するには、関連付けAPIを使用します。
結果を昇順または降順で表示するには、リクエスト本文に並べ替え規則を使用します。1回の検索に適用できる並べ替え規則は1つのみです。
例えば、以下のリクエストでは、返されたコンタクトを作成日時が新しい順にリスト表示します。
指定した文字列を含む値が含まれる全てのレコードを見つけるには、指定したオブジェクトのレコードにある全ての既定のテキストプロパティーを検索します。既定では、結果はオブジェクト作成順(古い順)で返されますが、この動作は前述の並べ替えにより変更できます。
例えば、以下のリクエストでは、既定のテキストプロパティー値に文字X
が含まれる全てのコンタクトが検索されます。
上記の方法によって既定で検索されるプロパティーを以下に示します。
オブジェクト/エンゲージメント | 既定で検索可能なプロパティー |
---|---|
コール |
|
会社 |
|
コンタクト |
|
カスタムオブジェクト |
|
取引 |
|
Eメール |
|
フィードバック送信 |
|
ミーティング |
|
メモ |
|
製品 |
|
タスク |
|
チケット |
|
商品項目 |
該当なし |
見積もり |
|
リクエストしたオブジェクトの検索結果に返される既定のプロパティーは、リクエストごとに異なります。この動作は、リクエスト本文のproperties
パラメーターに特定のプロパティー名の配列を指定することによって変更できます。
例えば、以下のリクエストでは、全てのコンタクトが検索され、それらのEメールアドレスと都道府県が返されます。
結果ページの処理
既定では、結果エンドポイントは1回につき10個のレコードが含まれるページを返します。これはlimit
パラメーターをリクエスト本文に指定して変更できます。1ページ当たりに指定できるオブジェクトの最大数は100です。
例えば、以下のリクエストでは結果を20件ずつ含むページが返されます。
結果の次ページを取得するには、前のレスポンスのpaging.next.after
プロパティーで提供されたafter
パラメーターを渡す必要があります。paging.next.after
プロパティーが提供されていない場合、それ以上表示される結果はありません。after
パラメーターの値は、文字列の形式で指定する必要があります。
例えば、以下のリクエストでは結果の次ページが返されます。
- 新規に作成または更新されたCRMオブジェクトが検索結果に表示されるまでには、若干時間がかかることがあります。
- アーカイブ済みのCRMオブジェクトは検索結果に表示されません。
- 検索エンドポイントへのリクエストには、1秒当たり4回のレート制限が適用されます。
- クエリーは最大3,000文字まで入力できます。リクエストの本文が3,000文字を超えている場合は、400エラーが返されます。
- 検索エンドポイントには、1回のクエリーにつき合計結果数10,000件という上限があります。10,001件以降の結果のページを取得しようとすると、400エラーが発生します。
- 電話番号の検索では、HubSpotは特殊な計算プロパティーを使用して形式を標準化します。このようなプロパティーは全て
hs_searchable_calculated_*
で始まります。この標準化の過程で、HubSpotは市外局番と市内番号のみを使用します。国コードは検索またはフィルター条件に含めないでください。
貴重なご意見をありがとうございました。