HEXACO-JP API ドキュメント｜診断結果を取得するREST API連携手順 : サンブレイズ

このページでは、HEXACO-JP API を自社サービスに組み込むための手順とエンドポイント仕様を説明します。API の利用には診断サイトでのプロジェクト作成・回答枠の購入が必要です。

連携の全体像

診断サイトでプロジェクトを作成し、プロジェクトキー・APIキー・リダイレクトURLを取得
自社サービスから対象ユーザーを HEXACO-JP の回答画面にリダイレクト
ユーザーが質問に回答して送信
送信完了後、自社が指定したリダイレクトURLにユーザーが戻る（クエリにレスポンスIDなどが付与）
クエリ情報を使ってREST APIから結果データを取得

STEP 1：プロジェクトを作成しキーを取得

診断サイトにログインし、メニューから ビジネス利用 を選択して新規プロジェクトを作成します。

プロジェクトタイプ：「API」を選択
リダイレクトURL：ユーザーが回答送信後に遷移する自社サイトのURL（後から変更可）
回答数：購入する回答枠の数（1回 5 USD）
質問内容：HEXACO-JP100問（10分）

作成後、プロジェクト詳細画面で プロジェクトキー と APIキー が発行されます。どちらも再生成が可能で、リダイレクトURLも後から編集できます。

STEP 2：ユーザーを診断画面に遷移させる

自社サービスから次のURLにユーザーをリダイレクトします。ボタンやリンクで遷移させる形が一般的です。

https://personalities.me/biz/survey?token=<project_key>&sessionData=<session_data>

token：プロジェクト詳細画面の プロジェクトキー
sessionData：自社側でユーザーを一意に識別できる任意のURLエンコード文字列（例：メールアドレス）。回答完了後にそのまま自社へ返却されます。

STEP 3：ユーザーが回答を送信

ユーザーは HEXACO-JP100問（約10分）に回答し、送信ボタンを押します。回答内容のサーバー保管・採点処理はサンブレイズ側で行います。

STEP 4：自社サービスへリダイレクト

送信完了後、プロジェクトに登録した リダイレクトURL にユーザーが戻ります。このとき、APIで結果を取得するために必要なメタデータがクエリパラメータとして付与されます。

projectId（GUID）
surveyType（文字列。例：hexaco-jp100）
responseId（GUID）
userId（GUID）
sessionData（STEP 2 で自社が指定した文字列）

リダイレクト例：

<HTTP_REDIRECT_URL>?responseId=e5f6ea19-eae0-4e07-a972-dbd94436c1e0
  &projectId=fc3980c8-7f51-47b3-b4cf-43fe1d62a3a0
  &surveyType=hexaco-jp100
  &userId=336bd9b8-fafc-4d98-9081-b2049d146205
  &sessionData=jay@amegumi.com

STEP 5：API で結果データを取得

自社サーバーからREST APIを呼び出し、回答結果を取得します。クエリで受け取った値をパスに埋め込み、ヘッダーに APIキー を Bearer 形式で付与してください。

エンドポイント

GET https://psych.sunblaze.jp/api/psych/v1/projects/{projectId}/surveys/{surveyType}/users/{userId}/responses/{responseId}

Authorization: Bearer <api_key>

APIキーはクライアント側（ブラウザ）に露出させず、必ず自社サーバー経由で呼び出してください。

レスポンス例（200 OK）

{
  "responseId": "resp_xyz789",
  "projectId": "proj_abc123",
  "userId": "user_123",
  "email": "user@example.com",
  "surveyType": "hexaco-jp100",
  "status": "completed",
  "startedAt": "2025-12-24T10:00:00Z",
  "completedAt": "2025-12-24T10:15:00Z",
  "durationSeconds": 900,
  "scores": {
    "honesty_humility":  { "value": 3.45, "average": 3.2 },
    "emotionality":      { "value": 2.89, "average": 3.1 },
    "extraversion":      { "value": 4.12, "average": 3.5 },
    "agreeableness":     { "value": 3.67, "average": 3.3 },
    "conscientiousness": { "value": 3.91, "average": 3.4 },
    "openness":          { "value": 3.23, "average": 3.2 }
  },
  "facets": {
    "sincerity": 3.2,
    "fairness":  3.5
  },
  "tendencies": {
    "leadership": 72,
    "teamwork":   85
  }
}

scores：HEXACO 6要素のスコア（value）と母集団平均（average）
facets：下位ファセットの一覧（誠実さ・公平性など）
tendencies：リーダーシップ・チームワークなど約90項目の傾向値

ステータスコード

200 OK：成功
401 Unauthorized：APIキーが無効または未指定
403 Forbidden：プロジェクトの契約が無効
404 Not Found：指定したレスポンスが存在しない

実装サンプル（curl）

curl -X GET \
  "https://psych.sunblaze.jp/api/psych/v1/projects/${PROJECT_ID}/surveys/hexaco-jp100/users/${USER_ID}/responses/${RESPONSE_ID}" \
  -H "Authorization: Bearer ${API_KEY}"

よくある質問

APIキーやプロジェクトキーが漏洩した場合は？

プロジェクト詳細画面の「APIキーを再生成」「プロジェクトキーを再生成」ボタンから再発行できます。旧キーは即座に無効化されます。

リダイレクトURLは後から変更できますか？

はい。プロジェクト詳細画面のリダイレクトURL欄から随時更新できます。すでに発行済みの回答枠にも適用されます。

回答数の課金タイミングは？

プロジェクト作成時に指定した回答数分が事前に課金されます。1回あたり 5 USD（税別）です。詳細はサービスLP をご覧ください。

HEXACO-JP API ドキュメント｜診断結果を取得するREST API連携手順