HubSpot APIの使い方
APIキーの取得
いずれのAPIも認証を必要とします（誰でもCRMの中身を閲覧できたり、情報を更新できてはいけませんよね）。認証には
- OAuthの利用
- APIキーの利用
の2通りがありますが、本ページでは手軽なAPIキーを利用します。[設定]（右上の歯車アイコン） → [連携] → [APIキー] よりAPIキー画面を開き、「APIキーを生成」ボタンをクリックします。
![[設定]（右上の歯車アイコン）→ [連携] → [APIキー] よりAPIキー画面へ遷移](http://cdn2.hubspot.net/hubfs/3111128/how-to-hubspot/basics/crm/hsapi/hsapi-get-api-key.gif)
[設定]（右上の歯車アイコン）→ [連携] → [APIキー] よりAPIキー画面へ遷移
または、上部ナビゲーションの右側にある検索欄に「api」と入力することで、APIキー画面にすぐ遷移することもできます。
検索を利用したAPIキー画面への遷移
APIキーの生成が完了されると、画面中央にAPIキーが表示されます。このキーをAPIのリクエストに利用しますので、エディタなどに控えておいてください。またこのキーは外部の人には絶対に教えないようにしてください。
キーを忘れた場合この画面で表示できますが、誰がキーを閲覧したのかその都度ログが残るようになっています。
APIキーが表示された状態
Node.jsとAPIキーの用意ができましたので、さっそくAPIを利用してみましょう。
Eメールアドレスから、特定のコンタクトの情報を取得する
まずはGETメソッドで情報を取得するだけの、単純なAPIから解説していきます。冒頭でも紹介しましたが、使用するAPIはGet Contact By Emailです。コードは次の通りです。
// requestモジュールの読み込み
const request = require("request");
// fsモジュールの読み込み（.jsonファイルの出力に使用）
const fs = require("fs")
function getDeals (email){
// requestモジュールのオプションを予め用意
const options = {
method: "GET",
url: `https://api.hubapi.com/contacts/v1/contact/email/${email}/profile`,
qs: {
hapikey: "APIキーが入ります",
}
}
// HubSpot APIへのリクエスト実行
request(options, function (error, response, body) {
// エラーがあればErrorオブジェクトを投げ、それ以降の処理を停止
if (error) throw new Error(error);
// エラーが無ければ、レスポンスボディをcontact.jsonとして保存
const result = JSON.parse(body)
fs.writeFileSync("./contact.json", JSON.stringify(result, null, 2))
});
}
// 関数の実行
getDeals("handa@pensees.co.jp")
各所にコメントを入れましたので、特に難しいことはないかと思います。
実はこのコードは、公式ドキュメントからコピー&ペーストし、少し改変しただけのものです。公式ドキュメントについては、まずコードの取得方法と、特に重要な必須パラメーター部分を明示します。
公式ドキュメントの必須パラメーター項目とコード例
生成したcontact.jsonは私の場合5,000行近くあるので全ては紹介しませんが、次のようになっています。「”properties”」直下にあるキーが各コンタクトのプロパティーの内部名で、その下に続く「”value”」が各コンタクトプロパティーの値です。
1つ例にとると「num_unique_conversion_events」プロパティーの値が「3」となっていることがわかります。
生成したcontact.jsonの中身
以上が、APIを利用してEメールアドレスがわかっているコンタクトの情報を取得する方法です。APIの利用と聞くと少し難しそうな印象を持たれがちですが、実際のコードを見てみると思ったよりも簡単だったのではないでしょうか。
Eメールアドレスでコンタクトを特定し、情報を更新する
次にPOSTメソッドを利用してHubSpot CRM上の情報を更新するAPIの使い方を解説します。使用するAPIはUpdate Contact By Emailです。コードは次のようになります。
const request = require("request");
function updateContact (){
// Update Contact By Emailへのリクエストボディを予め定義
const contactObj = {
"properties": [
{
"property": "firstname", // 単行テキスト
"value": "Atsushi"
},
{
"property": "lastname", // 単行テキスト
"value": "Handa"
},
{
"property": "privacy_policy_test", // 1つのチェックボックス
"value": false
},
{
"property": "muching_visit_date", // 日付選択カレンダー
"value": Date.parse('2019-11-01') // 日付形式をUNIX時間に変換。変換後の値は1572566400000
},
{
"property": "hs_content_membership_notes", // 複数行テキスト
"value": "パンセスタッフ\n職種：テクニカルディレクター、フロントエンドエンジニアなど"
},
{
"property": "followercount", // 数値
"value": 1000
},
{
"property": "hs_language", // ドロップダウン選択
"value": "ja-jp"
},
{
"property": "interesting_hubspot_tools", // 複数のチェックボックス
"value": "crm;marketing_hub;sales_hub" // HubSpot CRMのフィールドタイプが複数チェックボックスの場合はセミコロン区切りの文字列として渡す
},
]
}
// requestモジュールのオプションを予め用意
const options = {
method: "POST",
url: `http://api.hubapi.com/contacts/v1/contact/email/handa@pensees.co.jp/profile`,
qs: {
hapikey: "APIキーが入ります"
},
json: true, // bodyをJSON形式にするだけでなく、Content-Typeにapplication/jsonを設定する役割も果たす
body: contactObj
}
request(options, (error, response, body) => {
// エラーがあればErrorオブジェクトを投げ、それ以降の処理を停止
if (error) throw new Error(error);
// エラーが無ければ、レスポンスのステータスコードを表示
console.log(response.statusCode)
if (response.statusCode === 400) {
console.log(response.body)
}
});
}
updateContact()
少し長くなりましたので、ポイントごとに解説していきます。
リクエストボディの作成
まずは「contactObj」としてリクエストボディを定義している箇所です。各プロパティーは「”properties”」というキーの配列の要素となっていますが、何も情報が無ければこの構造に辿りつくのは困難でしょう。先ほどGet Contact By EmailのAPIで取得したJSONとも、構造が少し異なっています。
ではこの構造をどこで知るのかというと、これは公式ドキュメントのコードの「JSON」部分に記載されています。ドキュメントは次のキャプチャのように、GETメソッドとPOST（PUT）メソッドで「JSON」部分に記載されている内容が異なります。
GETメソッドのAPIとPOSTメソッドのAPIのJSON欄の違い
そのため、POST（PUT）メソッドのAPIを利用する際は、まずドキュメントのJSON欄でリクエストボディの構造を確認するのが基本となります。
「”properties”」内部の各オブジェクトについては、「”propety”」キーの値に更新したいコンタクトプロパティーの内部名を、「”value”」キーの値に更新したい値を指定します。この際、valueの値はコンタクトプロパティーのフィールドタイプによって、フィールドタイプ内で持つ内部値を正確に指定する必要があります。
コンタクトプロパティーの内部名、及びフィールドタイプの内部値については、HubSpotの [コンタクト] → [コンタクト] → [アクション] → [プロパティーを編集] から各プロパティーの詳細画面を開くことで確認できます。
コンタクトプロパティーの内部名、及びフィールドタイプの内部値の確認
なおこのように独自の内部値を持つフィールドタイプは
- ドロップダウン選択
- ラジオボタン
- 複数のチェックボックス
- HubSpotユーザー
です。
上記コードの例のうち下記2つのコンタクトプロパティー（フィールドタイプ）について特筆します。
- muching_visit_date（日付選択カレンダー）
- 日付選択カレンダーのフィールドタイプの場合、受け付けるのはUNIX時間（1572566400000 など）です。今回はJavaScriptのDateオブジェクトのparseメソッドを利用してUNIX時間に変換しています。
- interesting_hubspot_tools（複数のチェックボックス）
- 複数のチェックボックスは、HubSpot上では下記のキャプチャのような見え方になっているため、valueに配列で[“crm”, “marketing_hub”, “sales_hub”]としたいところですが、実はこれでは上手くいきません。複数のチェックボックスはセミコロン区切りの文字列として渡すのが正解です。
フィールドタイプ「複数のチェックボックス」のHubSpot CRM上での見え方
また先ほどGet Contact By Email APIで生成したcontact.jsonの中身を見ると、コンタクトプロパティーの値は本来BooleanであろうとNumberであろうと、全てStringとして保持されていることがわかります。
（再掲）生成したcontact.jsonの中身
これに合わせ、contactObj変数を定義した時点でBooleanやNumberをクォーテーションで括りStringとしても、特に問題ありません。
なお全フィールドタイプの値の渡し方については、本ページの末尾に「【付録】CRMオブジェクトに対するデータの渡し方一覧」としてまとめましたので、必要に応じてそちらも参照してください。
HubSpot CRMヘデータの送信
続いてHubSpot CRMにデータを送信する部分です。options変数のmethodを「”POST”」に変更しました。また、新たに「json」というプロパティーも追加しています。これをtrueにすることで後に続くbodyプロパティーの値をJSON形式にしてくれるだけでなく、リクエストヘッダーのContent-Typeを「application/json」に設定してくれます。jsonプロパティーを使わないにしても、このContent-Typeに「application/json」を設定せずにリクエストしてエラーが返ってくるミスはしてしまいがちですので、気をつけてください。
エラーハンドリングについては、Get Contact By EmailのAPIと同様です。成功時はステータスコードを返すように設定しています。というのも、ときにエラーハンドリングには引っかからずも、更新が正常に行われていないことがあります。更新が正常に行われた場合は204のステータスコードを返すので、きちんと204が返ってきているか確認するよいでしょう。
なお、他のステータスコードに意味についても、Update Contact By Email APIドキュメントの下部に明記されています。
ドキュメント内のステータスコードの解説
ちなみに、これもドキュメントに明記がありますが、ステータスコードが400以外の場合はレスポンスボディには何も入っていません。
APIの制限について
GETメソッドとPOSTメソッドのAPIの利用例をそれぞれ解説しましたが、注意点として、APIには回数制限が設けられています。これは各APIそれぞれに設けられている訳ではなく、全てのAPIの利用を合算した値です（CMS HubDB APIやForms APIなど、一部利用数のカウント方法が異なったり、カウントされないAPIも存在します）。
この制限値についてはポータルで契約しているプランによって異なります。また度々変更される値でもあるので、本ページでは解説しません。公式ドキュメントのAPI Usage Guidelinesより確認してください。
また利用しようとしているAPIが回数制限にカウントされるかどうかについては、各APIの「Methods Details」部分に明記されています。
Update Contact By Email APIの「Methods Details」部分。「Yes」は「回数制限がある」を意味する
MAIL NOTIFY
