検索
CRMオブジェクトの絞り込み、並べ替え、検索
CRM検索エンドポイントを使用すると、開発者はコンタクト、取引、会社、チケットなどのCRMオブジェクトタイプ間での絞り込み、並べ替え、検索を実行して効率的にデータを取得できます。 contacts
スコープは、アプリからこれらのエンドポイントを利用する際に必須です。
使用例:
- 特定のHubSpotアカウント上のコンタクトのリストを取得する
- 進行中のすべての取引のリストを取得する
- カスタムプロパティーによりオブジェクト(コンタクトや会社など)を検索する
サポートされるオブジェクトタイプとプロパティー
これらのエンドポイントでは、下記の表に示されているCRMオブジェクトへのアクセスが提供され、プロパティー名と値のマッピングが返されます。既定のプロパティーはオブジェクトタイプごとに異なりますが、CRMオブジェクトプロパティーのエンドポイントを使用して確認できます。レスポンスにおいて返されるプロパティーは変更できます。そのためには、 properties
配列をリクエスト本文で使用します。
オブジェクトタイプ |
既定で返されるプロパティー |
---|---|
companies(会社) |
|
contacts(コンタクト) |
|
deals(取引) |
|
products(製品) |
|
tickets(チケット) |
|
line_items(明細) |
|
quotes(見積もり) |
|
サポート対象外のプロパティー
engagements
(例: tasks
、 calls
、 emails
、および notes
)はサポート対象外です。
フィルター
フィルターは、結果をプロパティー値がマッチするCRMオブジェクトに限定する場合に、リクエスト本文の中で使用します。
例:名が「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"
}
]
}
]
}'
複数の filters
を filterGroups
に指定すると、論理 AND
演算子を使用して結合されます。複数の filterGroups
を指定すると、論理 OR
演算子を使用して結合されます。最大3つの filterGroups
、それぞれ最大3つの filters
がサポートされます。
例:次に一致するすべてのコンタクトを検索します。(名が「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": [
{
"property": "enum1",
"operator": "HAS_PROPERTY"
}
]
}
]
}'
演算子
サポートされる演算子:
演算子 |
説明 |
---|---|
|
次の値に等しい |
|
次の値に等しくない |
|
次の値より小さい |
|
次の値以下 |
|
次の値より大きい |
|
次の値以上 |
|
次のプロパティー値を持つ |
|
次のプロパティー値を持たない |
|
次のトークンを含む |
|
次のトークンを含まない |
関連付け
deals
とtickets
の関連付けの検索には擬似プロパティー associations.{objectType}
を使用します。
サポートされる関連付けフィルター:
オブジェクトタイプ |
フィルターのpropertyName |
---|---|
deals(取引) |
|
tickets(チケット) |
|
例: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"
}
]
}'
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(コンタクト) |
|
COMPANIES(会社) |
|
DEALS(取引) |
|
TICKETS(チケット) |
|
QUOTES(見積もり) |
|
LINE_ITEMS(明細) |
NA(該当なし) |
PRODUCTS(製品) |
|
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メールとメールアドレスの状態を返す
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
}
結果の次ページを取得するには、 after
パラメーター(前の応答の paging.next.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"
}'
正常なレスポンスの例
// 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が発生します。
エラー処理
詳しくはエラーに関するドキュメント(英語)をご覧ください。