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

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

OpenAPI仕様の対話的なドキュメント（Swagger UI）はこちらでも参照できます。

連携の全体像

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

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

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

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

作成後、プロジェクト詳細画面で プロジェクトキー と APIキー（JWT形式）が発行されます。どちらも再生成が可能で、リダイレクト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キー（JWT）を Bearer 形式で付与してください。

エンドポイント

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

Authorization: Bearer <api_key>

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

レスポンスのスコープ（scope）

プロジェクトの契約スコープによって、tendencies に含まれる項目数と necessities の有無が変わります。レスポンス内の scope フィールドで現在のスコープを確認できます。

WORK_ONLY（標準）：仕事・キャリア・チームワーク関連の傾向約80項目に限定（darkTrend、highIQ、leadershipTransformational など）。necessities は含まれません。
FULL：傾向のフルセット（約90項目）と、ニーズ階層（necessities）まで含めて返却されます。

レスポンス例（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,
  "scope": "WORK_ONLY",
  "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": {
    "leadershipTransformational": 72,
    "goodTeam": 85
  }
}

scope = FULL の場合、tendencies に追加項目が含まれるほか、necessities（マズローのニーズ階層に相当する内的欲求の傾向）が同梱されます。

status："completed"（完了）または "in_progress"（未完了）。未完了時は completedAt と durationSeconds が null になります。
scores：HEXACO 6要素のスコア（value）と母集団平均（average）
facets：HEXACOの下位ファセット（誠実さ・公平性など24項目）
tendencies：仕事・性格特性に紐づく行動傾向。スコープによって項目数が変わります。
necessities：scope=FULL のときのみ返却される、内的欲求の階層スコア。

ステータスコード

200 OK：成功
400 Bad Request：パスパラメータがAPIキーで認証されたプロジェクトと一致しない場合に返却されます。発生条件は次のいずれかです。
- APIキーから特定されるプロジェクトと projectId が一致しない
- レスポンスが当該プロジェクトに属していない
- レスポンスの surveyType がパスと一致しない
- レスポンスの userId がパスと一致しない
- レスポンスがまだ完了していない（送信前）
401 Unauthorized：APIキーが無効または Authorization: Bearer ヘッダーが未指定
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 をご覧ください。

scope は途中で変更できますか？

はい。プロジェクト単位で WORK_ONLY と FULL の切り替えが可能です。希望される場合はお問い合わせよりご連絡ください。

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