検索 

CRM全体でオブジェクト、レコード、エンゲージメントの絞り込み、並べ替え、検索を行うには、CRM検索エンドポイントを使用します。例えば、これらのエンドポイントを使用して、アカウント内のコンタクトのリストや進行中の全取引のリストを取得できます。

アプリからこれらのエンドポイントを使用するには、CRMスコープが必要です。目的を達成するためにどれくらい詳細なスコープが必要であるかに関しては、使用可能なスコープのリストをご参照ください。

検索リクエストの送信

CRM内を検索するには、オブジェクトの検索エンドポイントにPOSTリクエストを送信します。CRM検索エンドポイントは、次の形式で記述されます。

/crm/v3/objects/{object}/search

基本検索を行う（追加の絞り込みまたは並べ替えを行わずに既定のプロパティーのみを返す）には、リクエスト本文に空のオブジェクトのみを含めます。以下に例を示します。

// Example POST request to /crm/v3/objects/contacts/search {}

CRMオブジェクト

検索可能なCRMオブジェクト、その検索エンドポイント、および既定で返されるプロパティーを下の表に記載します。返されるプロパティーの指定については後述の詳細をご確認ください。

オブジェクト 検索エンドポイント 既定で返されるプロパティー

会社

/crm/v3/objects/companies/search

name,
domain,
createdate,
hs_lastmodifieddate,
hs_object_id

コンタクト

/crm/v3/objects/contacts/search

firstname,
lastname,
email,
lastmodifieddate,
hs_object_id,
createdate

カスタムオブジェクト

/crm/v3/objects/{objectType}/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

取引

/crm/v3/objects/deals/search

dealname, 
amount,
closedate,
pipeline,
dealstage,
createdate,
hs_lastmodifieddate, 
hs_object_id

フィードバック送信

/crm/v3/objects/feedback_submissions/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

製品

/crm/v3/objects/products/search

name,
description,
price,
createdate,
hs_lastmodifieddate,
hs_object_id

チケット

/crm/v3/objects/tickets/search

content,
hs_pipeline,
hs_pipeline_stage,
hs_ticket_category,
hs_ticket_priority,
subject,
createdate,
hs_lastmodifieddate,
hs_object_id

商品項目

/crm/v3/objects/line_items/search

quantity,
amount,
price,
createdate,
hs_lastmodifieddate,
hs_object_id

見積もり

/crm/v3/objects/quotes/search

hs_expiration_date,
hs_public_url_key,
hs_status,
hs_title,
hs_createdate,
hs_lastmodifieddate,
hs_object_id

エンゲージメント

検索可能なCRMエンゲージメント、その検索エンドポイント、および既定で返されるプロパティーを下記の表に示します。返されるプロパティーの指定については後述の詳細をご確認ください。

エンゲージメント 検索エンドポイント 既定で返されるプロパティー

コール

/crm/v3/objects/calls/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

Eメール

/crm/v3/objects/emails/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

ミーティング

/crm/v3/objects/meetings/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

メモ

/crm/v3/objects/notes/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

タスク

/crm/v3/objects/tasks/search

hs_createdate,
hs_lastmodifieddate,
hs_object_id

 

検索結果の絞り込み

プロパティー値が一致するレコードのみを結果に表示するには、リクエスト本文にフィルターを使用します。例えば、以下のリクエストでは、名が「Alice」である全てのコンタクトが検索されます。

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[ { "filters":[ { "propertyName": "firstname", "operator": "EQ", "value": "Alice" } ] } ] }'

複数のフィルター条件を指定する場合は、filterGroups内でフィルターをグループ化できます。

  • filterGroup内に複数のfilterがある場合は、「AND」論理演算子によって結合されます。
  • リクエスト本文に複数のfilterGroupが含まれる場合は、「OR」論理演算子によって結合されます。

最大3つのfilterGroupを含めることができ、各グループに最大3つのfilterを含めることができます。例えば以下のリクエストでは、名がAliceで、かつ（AND）姓がSmith以外であるか、または（OR）enumプロパティーに値が設定されている、全てのコンタクトが検索されます。 

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[{ "filters": [ { "propertyName": "firstname", "operator": "EQ", "value": "Alice" }], "filters":[ { "propertyName": "lastname", "operator": "NEQ", "value": "Smith" }], "filterGroups":[{ "filters": [ { "propertyName": "email", "operator": "HAS_PROPERTY" } ]} ] }] }'

別の例として、BETWEEN演算子を使用して、特定の期間内に最終の更新が加えられた全てのタスクを検索することもできます。

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[{ "filters":[ { "propertyName":"hs_lastmodifieddate", "operator":"BETWEEN", "highValue": "1642672800000", "value":"1579514400000" } ] } ]' }

フィルターでは以下の演算子を使用できます。

Use this table to describe parameters / fields
演算子Description
LT

次の値より小さい

LTE

次の値以下

GT

次の値より大きい

GTE

次の値以上

EQ

次の値に一致する

NEQ

次の値に一致しない

BETWEEN

指定の範囲内に含まれる。リクエストでは、キーと値のペアを使用してhighValueとvalueを設定します。上記の例を参照してください。

IN

指定のリストに含まれる。この演算子は大文字と小文字を区別するため、入力値は小文字でなければなりません。

NOT_IN

指定のリストに含まれない

HAS_PROPERTY

指定のプロパティーに値がある

NOT_HAS_PROPERTY

指定のプロパティーに値がない

CONTAINS_TOKEN

トークンが含まれる。リクエストにワイルドカード（*）を使用して部分検索を実行できます。例えば、HubSpotのEメールアドレスを持つコンタクトを検索するには、*@hubspot.comという値を使用します。

NOT_CONTAINS_TOKEN

トークンが含まれない

関連付けの検索

他の特定のレコードに関連付けられているレコードを検索するには、疑似プロパティーassociations.{objectType}を使用します。

例えば、以下のリクエストでは、コンタクトIDが123のコンタクトに関連付けられている全てのチケットが検索されます。

curl https://api.hubapi.com/crm/v3/objects/tickets/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filters": [ { "propertyName": "associations.contact", "operator": "EQ", "value": "123" } ] }'

以下の疑似プロパティー値を使用して、関連付けを検索できます。

  • associations.company
  • associations.contact
  • associations.ticket
  • associations.deal
  • associations.quote

注：現在のところ、カスタムオブジェクトの関連付けを検索するオプションは、検索エンドポイントではサポートされていません。カスタムオブジェクトの関連付けを検索するには、関連付けAPIを使用します。

検索結果の並べ替え

結果を昇順または降順で表示するには、リクエスト本文に並べ替え規則を使用します。1回の検索に適用できる並べ替え規則は1つのみです。

例えば、以下のリクエストでは、返されたコンタクトを作成日時が新しい順にリスト表示します。

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "sorts": [ { "propertyName": "createdate", "direction": "DESCENDING" } ] }'

既定で検索可能なプロパティーの検索

指定した文字列を含む値が含まれる全てのレコードを見つけるには、指定したオブジェクトのレコードにある全ての既定のテキストプロパティーを検索します。既定では、結果はオブジェクト作成順（古い順）で返されますが、この動作は前述の並べ替えにより変更できます。

例えば、以下のリクエストでは、既定のテキストプロパティー値に文字Xが含まれる全てのコンタクトが検索されます。

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "query": "x" }'

上記の方法によって既定で検索されるプロパティーを以下に示します。

オブジェクト／エンゲージメント 既定で検索可能なプロパティー

コール

"hs_call_title",
"hs_body_preview"

会社

"website",
"phone",
"domain",
"name"

コンタクト

"firstname",
"hs_additional_emails",
"phone",
"fax",
"mobilephone",
"company",
"email",
"lastname"

カスタムオブジェクト

“pipeline",
"dealname",
"dealstage",
"dealtype",
"description"

取引

"hs_ticket_category",
"hs_ticket_id",
"subject",
"hs_pipeline_stage",
"content"

Eメール

"hs_email_subject"

フィードバック送信

"hs_sender_firstname",
"hs_title",
"hs_sender_company_name",
"hs_sender_email",
"hs_quote_number",
"hs_sender_lastname",
"hs_public_url_key"

ミーティング

"hs_meeting_body"

メモ

"hs_note_body"

製品

"price",
"name",
"description"

タスク

"hs_task_body",
"hs_task_subject"

チケット

"hs_content",
"hs_submission_name"

商品項目

 該当なし

見積もり

"hs_sender_firstname",
"hs_proposal_slug",
"hs_title",
"hs_sender_company_name",
"hs_sender_email",
"hs_quote_number",
"hs_sender_lastname",
"hs_public_url_key"

返されるプロパティーの指定

リクエストしたオブジェクトの検索結果に返される既定のプロパティーは、リクエストごとに異なります。この動作は、リクエスト本文のpropertiesパラメーターに特定のプロパティー名の配列を指定することによって変更できます。 

例えば、以下のリクエストでは、全てのコンタクトが検索され、それらのEメールアドレスと都道府県が返されます。

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "properties": [ "email", "state" ] }'

結果ページの処理

既定では、結果エンドポイントは1回につき10個のレコードが含まれるページを返します。これはlimitパラメーターをリクエスト本文に指定して変更できます。1ページ当たりに指定できるオブジェクトの最大数は100です。

例えば、以下のリクエストでは結果を20件ずつ含むページが返されます。

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "limit": 20 }

結果の次ページを取得するには、前のレスポンスのpaging.next.afterプロパティーで提供されたafterパラメーターを渡す必要があります。paging.next.afterプロパティーが提供されていない場合、それ以上表示される結果はありません。afterパラメーターの値は、文字列の形式で指定する必要があります。

例えば、以下のリクエストでは結果の次ページが返されます。

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "after": "20" }'

制限事項

  • 新規に作成または更新されたCRMオブジェクトが検索結果に表示されるまでには、若干時間がかかることがあります。
  • アーカイブ済みのCRMオブジェクトは検索結果に表示されません。
  • 検索エンドポイントへのリクエストには、1秒当たり4回のレート制限が適用されます。
  • クエリーは最大3,000文字まで入力できます。リクエストの本文が3,000文字を超えている場合は、400エラーが返されます。
  • 検索エンドポイントには、1回のクエリーにつき合計結果数10,000件という上限があります。10,001件以降の結果のページを取得しようとすると、400エラーが発生します。
  • 電話番号の検索では、HubSpotは特殊な計算プロパティーを使用して形式を標準化します。このようなプロパティーは全てhs_searchable_calculated_*で始まります。この標準化の過程で、HubSpotは市外局番と市内番号のみを使用します。国コードは検索またはフィルター条件に含めないでください。
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。