検索 

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

カスタムオブジェクト

hs_createdate、hs_lastmodifieddate、hs_object_id
 

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

tasks、calls、emails、およびnotesなどのengagementsはサポート対象外です。

フィルター

フィルターは、結果をプロパティー値がマッチする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"
          }
        ]
      }
    ]
  }'

filterGroup内に複数のfilterを指定した場合はAND論理演算子によって結合されます。複数のfilterGroupを指定した場合はOR論理演算子によって結合されます。システム上、最大3つのfilterGroupがサポートされ、それぞれに最大3つのfilterがサポートされます。

例：名が「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": [
          {
            "propertyName": "enum1",
            "operator": "HAS_PROPERTY"
           }
         ]
       }
    ]
  }'

演算子

サポートされる演算子：

演算子

説明

EQ

次の値に等しい

NEQ

次の値に等しくない

LT

次の値より小さい

LTE

次の値以下

GT

次の値より大きい

GTE

次の値以上

HAS_PROPERTY

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

NOT_HAS_PROPERTY

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

CONTAINS_TOKEN

次のトークンを含む

NOT_CONTAINS_TOKEN

次のトークンを含まない

 

関連付け

deal（取引）とticket（チケット）の関連付けの検索には、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を含むすべてのコンタクトを検索する

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

 

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

 

オブジェクト

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

CONTACTS（コンタクト） 

"firstname"、

"hs_additional_emails"、

"phone"、

"fax"、

"mobilephone"

"company"、

"email"、

"lastname"

COMPANIES（会社） 

"website"、

"phone"、

"domain"、

"name"

DEALS（取引）

“pipeline"、

"dealname"、

"dealstage"、

"dealtype"、

"description"

 

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"

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

既定で検索結果に返されるプロパティーは、オブジェクトタイプごとに異なります。この動作は、リクエスト本文の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
  }

結果の次ページを取得するには、前のレスポンスのpaging.next.afterプロパティーで提供された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が発生します。

 

エラー処理

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

参考になりましたか？ *
こちらのフォームには開発者向けドキュメントに関するご意見をお聞かせください。なお、HubSpot製品に関するご意見は、アイデアフォーラム（英語）にお寄せください。