検索 

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が発生します。

 

エラー処理

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

Share your feedback

Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.