検索 

CRMオブジェクトの絞り込み、並べ替え、検索

CRM検索エンドポイントを使用すると、開発者はコンタクト、取引、会社、チケットなどのCRMオブジェクトタイプ間での絞り込み、並べ替え、検索を実行して効率的にデータを取得できます。 contacts スコープは、アプリからこれらのエンドポイントを利用する際に必須です。

使用例：

  • 特定のHubSpotアカウント上のコンタクトのリストを取得する
  • 進行中のすべての取引のリストを取得する
  • カスタムプロパティーによりオブジェクト（コンタクトや会社など）を検索する

サポートされるオブジェクトタイプとプロパティー

これらのエンドポイントでは、下記の表に示されているCRMオブジェクトへのアクセスが提供され、プロパティー名と値のマッピングが返されます。既定のプロパティーはオブジェクトタイプごとに異なりますが、CRMオブジェクトプロパティーのエンドポイントを使用して確認できます。レスポンスにおいて返されるプロパティーは変更できます。そのためには、 properties 配列をリクエスト本文で使用します。

オブジェクトタイプ

既定で返されるプロパティー

companies（会社）

name、 domain

contacts（コンタクト）

firstname、 lastname、 email

deals（取引）

dealname、 amount、 closedate、 pipeline、 dealstage

products（製品）

name、 description、 price

tickets（チケット）

content、 hs_pipeline、 hs_pipeline_stage、 hs_ticket_category、 hs_ticket_priority、 subject

line_items（明細）

Quantity、 created、 price

quotes（見積もり）

hs_expiration_date、 hs_public_url_key、 hs_status、 hs_title
 

サポート対象外のプロパティー

engagements（例： tasks、 calls、 emails、および notes ）はサポート対象外です。

フィルター

フィルターは、結果をプロパティー値がマッチするCRMオブジェクトに限定する場合に、リクエスト本文の中で使用します。

例：名が「Alice」であるすべてのコンタクトを検索する

Shell script 
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"
          }
        ]
      }
    ]
  }'

複数の filters を filterGroupsに指定すると、論理 AND 演算子を使用して結合されます。複数の filterGroupsを指定すると、論理 OR 演算子を使用して結合されます。最大3つの filterGroups 、それぞれ最大3つの filters がサポートされます。

例：次に一致するすべてのコンタクトを検索します。（名が「Alice」である AND 姓が「Smith」ではない） OR プロパティーenum1が指定されている

Shell script 
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": [
          {
            "property": "enum1",
            "operator": "HAS_PROPERTY"
           }
         ]
       }
    ]
  }'

演算子

サポートされる演算子：

演算子

説明

EQ

次の値に等しい

NEQ

次の値に等しくない

LT

次の値より小さい

LTE

次の値以下

GT

次の値より大きい

GTE

次の値以上

HAS_PROPERTY

次のプロパティー値を持つ

NOT_HAS_PROPERTY

次のプロパティー値を持たない

CONTAINS_TOKEN

次のトークンを含む

NOT_CONTAINS_TOKEN

次のトークンを含まない

 

関連付け

 dealsとtickets の関連付けの検索には擬似プロパティー associations.{objectType}を使用します。 

サポートされる関連付けフィルター：

オブジェクトタイプ

フィルターのpropertyName

deals（取引）

associations.company、
associations.contact、
associations.ticket

tickets（チケット）

associations.company、
associations.contact、
associations.deal

 

例：IDが123のコンタクトに関連付けられているすべてのチケットを検索する

Shell script 
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"
      }
    ]
  }'

並べ替え

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

例：作成日時が新しい順にすべてのコンタクトをリスト表示します。

Shell script 
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

CRMオブジェクトに対し、既定で検索可能なプロパティー：

 

オブジェクト

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

CONTACTS（コンタクト） 

firstname",

"hs_additional_emails",

"phone",

"hs_object_id",

"hs_searchable_calculated_phone_number",

"company",

"email",

"lastname

COMPANIES（会社） 

website",

"phone",

"domain",

"name"

DEALS（取引）

“pipeline",

"dealname",

"dealstage",

"dealtype"

 

TICKETS（チケット）

"hs_ticket_category",

"hs_ticket_id",

"subject",

"hs_pipeline_stage",

"content"

 

QUOTES（見積もり）

"hs_sender_firstname",

"hs_title",

"hs_sender_company_name",

"hs_sender_email",

"hs_quote_number",

"hs_sender_lastname",

"hs_public_url_key"

 

LINE_ITEMS（明細）

NA（該当なし）

PRODUCTS（製品）

"price",

"name",

"description"
Shell script 
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"
  }'

返されるプロパティーの制御

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

例：すべてのコンタクトと、そのEメールとメールアドレスの状態を返す

Shell script 
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にしてページを取得する

Shell script 
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
  }

結果の次ページを取得するには、 after パラメーター（前の応答の paging.next.after プロパティー）を渡す必要があります。 paging.next.after プロパティーがない場合、それ以上表示される結果はありません。注： after パラメーターには文字列を指定します。

例：結果の次ページを取得する

Shell script 
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"
  }'

正常なレスポンスの例

JSON 
// Sample response
{
  "results": [
    {
      "id": "174",
      "properties": {
        "firstname": "Brantley",
        "lastname": "Forrest",
        "email": "bforrest8@acme.com"
      },
      "createdAt": "2019-10-30T03:30:17.883Z",
      "updatedAt": "2019-10-30T16:50:06.678Z",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "10"
    }
  }
}

制限

  • 新規に作成または更新されたCRMオブジェクトが検索結果に表示されるまでには、若干時間がかかることがあります。
  • アーカイブ済みのCRMオブジェクトは検索結果に表示されません。
  • これらの検索エンドポイントには1つの認証トークンにつき1秒間に4回のリクエストというレート制限があり、当社の標準的なレート制限よりも厳しくなっています。 X-HubSpot-RateLimit-* ヘッダーには、ベータ版の期間中はこの情報が反映されません。
  • 検索エンドポイントには、1クエリーにつき合計結果数10,000件という上限があります。10,000件を超える部分のページを取得しようとすると、エラー400が発生します。

 

エラー処理

詳しくはエラーに関するドキュメント（英語）をご覧ください。