検索 

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

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

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?hapikey=YOUR_HUBSPOT_API_KEY \ --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）プロパティーenum1がある、全てのコンタクトが検索されます。 

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

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

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

次の値より小さい

LTE

次の値以下

GT

次の値より大きい

GTE

次の値以上

EQ

次の値に等しい

NEQ

次の値に等しくない

HAS_PROPERTY

指定されたプロパティーに値がある

NOT_HAS_PROPERTY

指定されたプロパティーに値がない

CONTAINS_TOKEN

トークンが含まれる

NOT_CONTAINS_TOKEN

トークンが含まれない

関連付けの検索

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

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

curl https://api.hubapi.com/crm/v3/objects/tickets/search?hapikey=YOUR_HUBSPOT_API_KEY \ --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

特定のカスタム オブジェクト レコードへの関連付けを検索するために、カスタムオブジェクトの「objectTypeId」とともに上記の疑似プロパティーを使用できます。これにより、カスタムオブジェクトのスキーマを介して関連付けを検索できます。例えば、associations.2-214573を使用します。

検索結果の並べ替え

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

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

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

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

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

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

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

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

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

コール

"hs_call_title",
"hs_body_preview"

会社

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

コンタクト

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

カスタムオブジェクト

“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?hapikey=YOUR_HUBSPOT_API_KEY \ --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?hapikey=YOUR_HUBSPOT_API_KEY \ --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?hapikey=YOUR_HUBSPOT_API_KEY \ --request POST \ --header "Content-Type: application/json" \ --data '{ "after": "20" }'

制限

  • 新規に作成または更新された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では市外局番と市内番号のみが使用されます。国コードは検索またはフィルター条件に含めないでください。
参考になりましたか？ *
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。