検索
CRM全体でオブジェクト、レコード、エンゲージメントの絞り込み、並べ替え、検索を行うには、CRM検索エンドポイントを使用します。例えば、これらのエンドポイントを使用して、アカウント内のコンタクトのリストや進行中の全取引のリストを取得できます。
アプリからこれらのエンドポイントを使用するには、CRMスコープが必要です。目的を達成するためにどれくらい詳細なスコープが必要であるかに関しては、使用可能なスコープのリストをご参照ください。
CRM内を検索するには、オブジェクトの検索エンドポイントにPOST
リクエストを送信します。CRM検索エンドポイントは、次の形式で記述されます。
/crm/v3/objects/{object}/search
たとえば以下のコードスニペットは、firstname
およびlastname
プロパティーが含まれるすべてのコンタクトのリストを取得します。
基本的な検索を行う(追加の絞り込みや並べ替えを行わずに既定のプロパティーのみを返す)には、リクエスト本文に空のオブジェクトのみを含めます。これは、内部フィールドのない(つまり{}
)JSON形式オブジェクトで指定されます。
以下の表は、オブジェクト検索エンドポイント、それらが参照するオブジェクト、および既定で返されるプロパティーを示しています。返されるプロパティーの指定について詳細をご確認ください。
検索エンドポイント | オブジェクト | 既定で返されるプロパティー |
---|---|---|
/crm/v3/objects/companies/search
| 会社 |
|
/crm/v3/objects/contacts/search
| コンタクト |
|
/crm/v3/objects/{objectType}/search
| カスタムオブジェクト |
|
/crm/v3/objects/deals/search
| 取引 |
|
/crm/v3/objects/feedback_submissions/search
| フィードバック送信 |
|
/crm/v3/objects/line_items/search
| 商品項目 |
|
/crm/v3/objects/products/search
| 製品 |
|
/crm/v3/objects/quotes/search
| 見積もり |
|
/crm/v3/objects/tickets/search
| チケット |
|
以下の表は、エンゲージメント検索エンドポイント、それらが参照するエンゲージメント、および既定で返されるプロパティーを示しています。返されるプロパティーの指定について詳細をご確認ください。
検索エンドポイント | エンゲージメント | 既定で返されるプロパティー |
---|---|---|
/crm/v3/objects/calls/search
| コール |
|
/crm/v3/objects/emails/search
| Eメール |
|
/crm/v3/objects/meetings/search
| ミーティング |
|
/crm/v3/objects/notes/search
| メモ |
|
/crm/v3/objects/tasks/search
| タスク |
|
プロパティー値が一致するレコードのみを結果に表示するには、リクエスト本文にフィルターを使用します。例えば、以下のリクエストでは、名が「Alice」である全てのコンタクトが検索されます。
複数のフィルター条件を指定するには、filterGroups
内でfilters
を次のようにグループ化できます。
- 「AND」ロジックを適用するには、1つの
filters
内に複数の条件リストをカンマで区切って並べます。 - 「OR」ロジックを適用するには、
filterGroup
内に複数のfilters
を含めます。
最大で3つのfilterGroups
を含めることができ、各グループに最大3つのfilters
を含めることができます。
例えば次のリクエストでは、名がAlice
で、かつ(AND)姓がSmith
以外であるか、または(OR)email
プロパティーに値が設定されていないコンタクトが検索されます。
フィルターで演算子を使用して、どのレコードを返すかを指定できます。フィルターの値では大文字と小文字が区別されません。ただし、IN
演算子とNOT_IN
演算子は例外で、小文字の値が必要です。フィルターでは以下の演算子を使用できます。
演算子 | 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
が含まれる全てのコンタクトが検索されます。
上記の方法によって既定で検索されるプロパティーを以下に示します。
検索エンドポイント | オブジェクト | 既定で検索可能なプロパティー |
---|---|---|
/crm/v3/objects/calls/search
| コール |
|
/crm/v3/objects/companies/search
| 会社 |
|
/crm/v3/objects/contacts/search
| コンタクト |
|
/crm/v3/objects/{objectType}/search
| カスタムオブジェクト | カスタム オブジェクト プロパティーは全て既定で検索可能です |
/crm/v3/objects/deals/search
| 取引 |
|
/crm/v3/objects/emails/search
| Eメール |
|
/crm/v3/objects/feedback_submissions/search
| フィードバック送信 |
|
/crm/v3/objects/meetings/search
| ミーティング |
|
/crm/v3/objects/notes/search
| メモ |
|
/crm/v3/objects/products/search
| 製品 |
|
/crm/v3/objects/quotes/search
| 見積もり |
|
/crm/v3/objects/tasks/search
| タスク |
|
/crm/v3/objects/tickets/search
| チケット |
|
/crm/v3/objects/line_items/search
| 商品項目 | 商品項目には既定で検索可能なプロパティーはありません |
リクエストしたオブジェクトの検索結果に返される既定のプロパティーは、リクエストごとに異なります。この動作は、リクエスト本文の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,000件を超える部分のページを取得しようとすると、エラー400が発生します。
- 電話番号の検索では、HubSpotは特殊な計算プロパティーを使用して形式を標準化します。このようなプロパティーは全て
hs_searchable_calculated_*
で始まります。この標準化の過程で、HubSpotは市外局番と市内番号のみを使用します。国コードは検索またはフィルター条件に含めないでください。
貴重なご意見をありがとうございました。