検索
CRM全体でオブジェクト、レコード、エンゲージメントの絞り込み、並べ替え、検索を行うには、CRM検索エンドポイントを使用します。例えば、これらのエンドポイントを使用して、アカウント内のコンタクトのリストや、進行中の全取引のリストを取得します。
contacts
スコープは、アプリからこれらのエンドポイントを利用する際に必須です。
CRM内を検索するには、オブジェクトの検索エンドポイントにPOST
リクエストを送信します。CRM検索エンドポイントは、次の形式で記述されます。
/crm/v3/objects/{object}/search
検索可能なCRMオブジェクト、その検索エンドポイント、および既定で返されるプロパティーを下記の表に示します。返されるプロパティーの指定について詳細をご確認ください。
オブジェクト | 検索エンドポイント | 既定で返されるプロパティー |
会社 |
/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/products/search |
|
チケット |
/crm/v3/objects/tickets/search |
|
商品項目 |
/crm/v3/objects/line_items/search |
|
見積もり |
/crm/v3/objects/quotes/search |
|
検索可能なCRMエンゲージメント、その検索エンドポイント、および既定で返されるプロパティーを下記の表に示します。返されるプロパティーの指定について詳細をご確認ください。
Please note: the engagements API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer Terms& Developer Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API.
エンゲージメント | 検索エンドポイント | 既定で返されるプロパティー |
コール |
/crm/v3/objects/calls/search |
|
Eメール |
/crm/v3/objects/emails/search |
|
ミーティング |
/crm/v3/objects/meetings/search |
|
コメント |
/crm/v3/objects/notes/search |
|
タスク |
/crm/v3/objects/tasks/search |
|
(追加の絞り込みまたは並べ替えを行わずに既定のプロパティーのみを返す)基本検索を行うには、リクエスト本文に空のオブジェクトのみを含めます。例:
フィルターは、結果をプロパティー値がマッチするレコードに限定する場合に、リクエスト本文の中で使用します。
例えば、次のリクエストでは、名が「Alice」である全てのコンタクトが検索されます。
複数のフィルター条件を指定する場合は、filterGroups
内でフィルターをグループ化できます。
filterGroup
内に複数のfilter
がある場合は、「AND」論理演算子によって結合されます。- リクエスト本文に複数の
filterGroup
が含まれる場合は、「OR」論理演算子によって結合されます。
最大3つのfilterGroup
を含めることができ、各グループに最大3つのfilter
を含めることができます。
例えば、次のリクエストでは、名がAlice
で、かつ(AND)姓がSmith
以外、または(OR)プロパティーenum1
がある、全てのコンタクトが検索されます。
フィルターでは以下の演算子を使用できます。
演算子 | Description |
---|---|
LT
| 次の値より小さい |
LTE
| 次の値以下 |
GT
| 次の値より大きい |
GTE
| 次の値以上 |
EQ
| 次の値に等しい |
NEQ
| 次の値に等しくない |
HAS_PROPERTY
| 指定されたプロパティーに値がある |
NOT_HAS_PROPERTY
| 指定されたプロパティーに値がない |
CONTAINS_TOKEN
| トークンが含まれる |
NOT_CONTAINS_TOKEN
| トークンが含まれない |
他の特定のレコードに関連付けられているレコードを検索するには、疑似プロパティーassociations.{objectType}
を使用します。
例えば、次のリクエストでは、コンタクトIDが123
のコンタクトに関連付けられている全てのチケットが検索されます。
以下の疑似プロパティー値を使用して、関連付けを検索できます。
associations.company
associations.contact
associations.ticket
associations.deal
associations.quote
特定のカスタム オブジェクト レコードへの関連付けを検索するために、カスタムオブジェクトの「objectTypeId」とともに上記の疑似プロパティーを使用できます。これにより、カスタムオブジェクトのスキーマを介して関連付けを検索できます。例えば、associations.2-214573
を使用します。
並べ替え規則は、結果を昇順または降順で表示するために、リクエスト本文の中で使用します。1回の検索に適用できる並べ替え規則は1つに限られます。
例えば次のリクエストでは、返されたコンタクトを作成日時が新しい順にリスト表示します。
指定した文字列を含む値が含まれる全てのレコードを見つけるには、指定したオブジェクトのレコードにある全ての既定のテキストプロパティーを検索します。既定では、結果はオブジェクト作成順(古い順)で返されますが、この動作は並べ替えにより変更できます。
例えば次のリクエストでは、既定のテキストプロパティー値に文字X
が含まれる全てのコンタクトが検索されます。
上記の方法によって既定で検索されるプロパティーを以下に示します。
オブジェクト/エンゲージメント | 既定で検索可能なプロパティー |
---|---|
コール |
|
会社 |
|
コンタクト |
|
カスタムオブジェクト |
|
取引 |
|
Eメール |
|
フィードバック送信 |
|
ミーティング |
|
備考 |
|
製品 |
|
タスク |
|
チケット |
|
商品項目 |
該当なし |
見積もり |
|
リクエストしたオブジェクトの検索結果に返される既定のプロパティーは、リクエストごとに異なります。この動作は、リクエスト本文のproperties
パラメーターに特定のプロパティー名の配列を指定することによって変更できます。
例えば、次のリクエストでは、全てのコンタクトが検索され、それらのEメールアドレスと状態が返されます。
結果ページの処理
既定では、結果エンドポイントは1回につき10個のレコードが含まれるページを返します。これはlimit
パラメーターをリクエスト本文に指定して変更できます。1ページあたりに指定できるオブジェクトの最大数は100です。
例えば次のリクエストでは、結果を20件ずつ含むページが返されます。
結果の次ページを取得するには、前のレスポンスのpaging.next.after
プロパティーで提供されたafter
パラメーターを渡す必要があります。paging.next.after
プロパティーがない場合、それ以上表示される結果はありません。after
パラメーターの値は、文字列の形式で指定する必要があります。
例えば次のリクエストでは、結果の次ページが返されます。
- 新規に作成または更新されたCRMオブジェクトが検索結果に表示されるまでには、若干時間がかかることがあります。
- アーカイブ済みのCRMオブジェクトは検索結果に表示されません。
- これらの検索エンドポイントには1つの認証トークンにつき1秒間に4回のリクエストというレート制限があり、当社の標準的なレート制限よりも厳しくなっています。HubSpotでは、
X-HubSpot-RateLimit-Daily
ヘッダーとX-HubSpot-RateLimit-Daily-Remaining
ヘッダーのみが返されます。 - 検索エンドポイントには、1クエリーにつき合計結果数10,000件という上限があります。10,000件を超える部分のページを取得しようとすると、エラー400が発生します。
- 電話番号の検索では、HubSpotは特殊な計算プロパティーを使用して形式を標準化します。このようなプロパティーは全て
hs_searchable_calculated_*
で始まります。この標準化の一環で、HubSpotでは市外局番と市内番号のみが使用されます。国コードは検索またはフィルター条件に含めないでください。
貴重なご意見をありがとうございました。