検索 

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

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

使用例:

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

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

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

オブジェクトタイプ

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

companies(会社)

namedomain

contacts(コンタクト)

firstnamelastnameemail

deals(取引)

dealnameamountclosedatepipelinedealstage

products(製品)

namedescriptionprice

tickets(チケット)

contenths_pipelinehs_pipeline_stagehs_ticket_categoryhs_ticket_prioritysubject

line_items(明細)

Quantitycreatedprice

quotes(見積もり)

hs_expiration_datehs_public_url_keyhs_statushs_title

 

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

engagements(例: taskscallsemails、および 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"
          }
        ]
      }
    ]
  }'

複数の filtersfilterGroupsに指定すると、論理 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

次のトークンを含まない

 

関連付け

 dealstickets の関連付けの検索には擬似プロパティー 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が発生します。

 

エラー処理

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