検索 

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

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

検索リクエストの送信

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

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

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

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

CRMオブジェクト

以下の表は、オブジェクト検索エンドポイント、それらが参照するオブジェクト、および既定で返されるプロパティーを示しています。返されるプロパティーの指定について詳細をご確認ください。

Use this table to describe parameters / fields
検索エンドポイントオブジェクト既定で返されるプロパティー
/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/line_items/search
商品項目

quantity、amount、price、createdate、hs_lastmodifieddate、hs_object_id

/crm/v3/objects/products/search
製品

name、description、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/v3/objects/tickets/search
チケット

content、hs_pipeline、hs_pipeline_stage、

hs_ticket_category、hs_ticket_priority、subject、

createdate、hs_lastmodifieddate、hs_object_id

エンゲージメント

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

Use this table to describe parameters / fields
検索エンドポイントエンゲージメント既定で返されるプロパティー
/crm/v3/objects/calls/search
コール

hs_createdate、
hs_lastmodifieddate、
hs_object_id

/crm/v3/objects/emails/search
Eメール

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内でfiltersを次のようにグループ化できます。

  • 「AND」ロジックを適用するには、1つのfilters内に複数の条件リストをカンマで区切って並べます。
  • 「OR」ロジックを適用するには、filterGroup内に複数のfiltersで分けて条件を並べます。

最大3つのfilterGroupを含めることができ、各グループに最大3つのfilterを含めることができます。

例えば次のリクエストでは、名がAliceで、かつ（AND）姓がSmith以外であるか、または（OR）emailプロパティーに値が設定されていないコンタクトが検索されます。 

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": "NOT_HAS_PROPERTY" } ] } ] }'

フィルターで演算子を使用して、どのレコードを返すかを指定できます。フィルターの値では大文字と小文字が区別されません。ただし、IN演算子とNOT_IN演算子は例外で、小文字の値が必要です。フィルターでは以下の演算子を使用できます。

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

次の値より小さい

LTE

次の値以下

GT

次の値より大きい

GTE

次の値以上

EQ

次の値に等しい

NEQ

次の値に等しくない

BETWEEN

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

IN

指定のリストに含まれる。リクエストでは、values配列にリスト値を含めます。入力される値は小文字でなければなりません。下記の例を参照してください。

NOT_IN

指定のリストに含まれない。リクエストでは、values配列にリスト値を含めます。入力される値は小文字でなければなりません。

HAS_PROPERTY

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

NOT_HAS_PROPERTY

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

CONTAINS_TOKEN

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

NOT_CONTAINS_TOKEN

トークンが含まれない

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

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

また、IN演算子を使用して、パイプラインの特定の段階にある全ての取引を検索することもできます。 

curl https://api.hubapi.com/crm/v3/objects/deals/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[{ "filters":[ { "propertyName":"dealstage", "operator":"IN", "values": ["appointmentscheduled", "contractsent", "qualifiedtobuy"] } ] } ] }'

関連付けの検索

他の特定のレコードに関連付けられているレコードを検索するには、疑似プロパティー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" }'

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

Use this table to describe parameters / fields
検索エンドポイントオブジェクト既定で検索可能なプロパティー
/crm/v3/objects/calls/search
コール

hs_call_title、hs_body_preview

/crm/v3/objects/companies/search
企業

website、phone、name、domain

/crm/v3/objects/contacts/search
［コンタクト］

firstname、lastname、email、phone、hs_additional_emails、fax、mobilephone、company、hs_marketable_until_renewal

/crm/v3/objects/{objectType}/search
カスタムオブジェクト

カスタム オブジェクト プロパティーは全て既定で検索可能です

/crm/v3/objects/deals/search
取引

dealname、pipeline、dealstage、description、dealtype

/crm/v3/objects/emails/search
Eメール

hs_email_subject

/crm/v3/objects/feedback_submissions/search
フィードバック送信

hs_submission_name、hs_content

/crm/v3/objects/meetings/search
ミーティング

hs_meeting_title、hs_meeting_body

/crm/v3/objects/notes/search
メモ

hs_note_body

/crm/v3/objects/products/search
製品

name、description、price、hs_sku

/crm/v3/objects/quotes/search
見積もり

hs_sender_firstname、hs_sender_lastname、 hs_proposal_slug、hs_title、hs_sender_company_name、hs_sender_email、hs_quote_number、hs_public_url_key

/crm/v3/objects/tasks/search
タスク

hs_task_body、hs_task_subject

/crm/v3/objects/tickets/search
チケット

subject、content、hs_pipeline_stage、hs_ticket_category、hs_ticket_id

/crm/v3/objects/line_items/search
商品項目

商品項目には既定で検索可能なプロパティーはありません

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

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