検索 

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

contactsスコープは、アプリからこれらのエンドポイントを利用する際に必須です。

検索リクエストの送信

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

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

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

※ エンゲージメントAPIは現在ベータ版であり、テストとフィードバックに基づいて変更されることがあります。これらのエンドポイントを使用することにより、HubSpotの開発者規約（英語）と開発者ベータ規約を遵守することに同意するものとします。また、不安定なAPIをテストすることに伴うリスクを認識し、理解するものとします。

 

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

コール

/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

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

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

検索結果の絞り込み

フィルターは、結果をプロパティー値がマッチするレコードに限定する場合に、リクエスト本文の中で使用します。例えば、次のリクエストでは、名が「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" }, { "propertyName": "lastname", "operator": "NEQ", "value": "Smith" }], "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

トークンが含まれる

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リクエストのレート制限が適用されます。
  • 検索エンドポイントには、1クエリーにつき合計結果数10,000件という上限があります。10,000件を超える部分のページを取得しようとすると、エラー400が発生します。
  • 電話番号の検索では、HubSpotは特殊な計算プロパティーを使用して形式を標準化します。このようなプロパティーは全てhs_searchable_calculated_*で始まります。この標準化の一環で、HubSpotでは市外局番と市内番号のみが使用されます。国コードを検索またはフィルター条件に含めないでください。
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。