HEXACO-JP REST API Docs: Get Diagnosis Results : サンブレイズ

Q: What is the difference between the WORK_ONLY and FULL scope settings?

WORK_ONLY is the standard scope and returns approximately 80 work- and career-related behavioral tendency items. FULL expands this to approximately 90 tendency items and also includes the necessities object — a set of hierarchical intrinsic motivation scores. The active scope is always visible in the scope field of every API response, so your application can branch logic accordingly.

Q: Can the scope be changed after a project is already running?

Yes, it is possible to switch between WORK_ONLY and FULL at the project level. However, scope changes are handled through the support team rather than the self-serve dashboard. If you would like to upgrade or downgrade your scope, please reach out via the contact page.

Q: What does the sessionData parameter do, and what values can it hold?

sessionData is a free-form, URL-encoded string that you supply when redirecting the user to the survey. It is returned unchanged in the callback query parameters after the user submits. Its purpose is to let you identify which user in your own system completed the survey — common values include email addresses or internal user IDs. There is no fixed format requirement beyond valid URL encoding.

If you’re looking for a practical HEXACO-JP API integration guide, this page walks you through every step — from project setup to retrieving scored personality results via REST API. Whether you’re embedding a personality assessment into an HR platform, a career-matching app, or a team-building tool, the HEXACO-JP API offers a clean, OAuth-style redirect flow that keeps your users inside your product experience while sunblaze.jp handles all the scoring and data storage on the backend.

This guide covers all 5 integration steps, explains the full response specification including HEXACO scope parameters, and provides curl sample code you can drop into your environment right away. An interactive OpenAPI reference (Swagger UI) is also available at psych.sunblaze.jp/api/psych/api/docs for developers who prefer hands-on exploration.

Overview of the Integration Flow

The HEXACO-JP API uses a redirect-based flow similar to OAuth, making it straightforward to embed into any existing web service without managing questionnaire logic yourself. Here is the end-to-end sequence in 5 steps:

Create a project on the diagnosis site and obtain your Project Key, API Key, and Redirect URL.
Redirect the target user from your service to the HEXACO-JP answer screen.
The user completes the 100-question survey and submits their responses.
After submission, the user is redirected back to your specified Redirect URL with metadata attached as query parameters (including the Response ID).
Your server calls the REST API using that metadata to retrieve the full scored results.

This architecture means your application never touches raw questionnaire data — sunblaze.jp handles secure storage and scoring, and your server simply requests the finished result object when it needs it.

STEP 1 — Create a Project and Obtain Your Keys

Before any API call can be made, you need an active project on the diagnosis site — this is where your Project Key and API Key are generated. Log in to the diagnosis site, select Business Use from the menu, and create a new project with the following settings:

Project Type: Select “API”
Redirect URL: The URL on your site where users will land after completing the survey (can be updated at any time)
Response Count: The number of response slots to purchase upfront (priced at 5 USD per response)
Question Set: HEXACO-JP 100 questions (approximately 10 minutes to complete)

Once the project is created, the project detail screen will display your Project Key and API Key (in JWT format). Both keys can be regenerated at any time if a security issue arises, and your Redirect URL can be edited without affecting already-purchased response slots.

STEP 2 — Redirect the User to the Survey Screen

Sending a user to the HEXACO-JP survey is as simple as constructing a URL with 2 query parameters and pointing a button or link to it. The redirect target URL takes the following form:

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

token: Your Project Key from the project detail screen
sessionData: Any URL-encoded string that uniquely identifies the user on your side (for example, their email address or an internal user ID). This value is passed back to you unchanged after the user submits their answers.

The sessionData parameter is your bridge between the HEXACO-JP system and your own user records. Because it is returned verbatim in the redirect callback, you can use it to look up the correct user in your database without maintaining a separate session mapping table.

STEP 3 — The User Completes the Survey

Once redirected, the user sees the HEXACO-JP personality assessment interface. The test consists of 100 questions and typically takes around 10 minutes to complete. All answer storage and scoring are handled entirely by sunblaze.jp’s servers — your integration does not need to touch any of this logic. When the user presses Submit, the flow automatically moves to STEP 4.

STEP 4 — Handle the Redirect Callback and Capture Query Parameters

After submission, the user’s browser is redirected back to your Redirect URL with 5 query parameters that you will need in order to retrieve the results via the API. A real callback URL tends to look like this:

<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

The 5 parameters and their roles are:

projectId (GUID) — Identifies the project the response belongs to
surveyType (string, e.g., hexaco-jp100) — Specifies which question set was used
responseId (GUID) — The unique identifier for this specific response record
userId (GUID) — The user identifier assigned by the HEXACO-JP system
sessionData — The same string you passed in STEP 2, returned unchanged

Store all 5 values on your server side before proceeding to the API call. They are all required path components for the results endpoint.

STEP 5 — HEXACO-JP API Integration Guide: Fetching Results via REST API

The final step in the HEXACO-JP API integration guide is making a single authenticated GET request from your server to retrieve the fully scored personality assessment result. Embed the query parameters from STEP 4 into the path, and include your API Key as a Bearer token in the Authorization header.

API Endpoint

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

Authorization: Bearer <api_key>

Important: Always call this endpoint from your own server, never from browser-side JavaScript. Exposing your API Key (JWT) on the client side creates a serious security risk.

Understanding HEXACO Scope Parameters

The response payload varies depending on the HEXACO scope parameters configured for your project. The scope field in every response tells you which data tier is active:

WORK_ONLY (standard): Returns approximately 80 work- and career-related behavioral tendency items under tendencies (such as darkTrend, highIQ, and leadershipTransformational). The necessities object is not included in this scope.
FULL: Returns the complete set of approximately 90 tendency items plus the necessities object — a hierarchy of intrinsic motivational needs analogous to Maslow’s hierarchy.

Sample Response (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
  }
}

Key fields in the response object are explained below:

status: Either "completed" or "in_progress". When in_progress, both completedAt and durationSeconds return null.
scores: Numeric scores for all 6 HEXACO dimensions, each accompanied by a population-level average for benchmarking.
facets: The 24 lower-level HEXACO facets (e.g., sincerity, fairness) that provide more granular insight beneath the 6 main dimensions.
tendencies: Behavioral tendency scores tied to work and personality traits. The number of items returned depends on the active scope — approximately 80 items for WORK_ONLY, approximately 90 for FULL.
necessities: Only present when scope is FULL. Contains hierarchical intrinsic motivation scores.

HTTP Status Codes

200 OK: Request succeeded and the result object is returned.
400 Bad Request: One or more path parameters do not match the authenticated project. This tends to occur when: the projectId does not match the project identified by your API Key; the response does not belong to that project; the surveyType in the path differs from the response record; the userId in the path differs from the response record; or the response has not yet been submitted.
401 Unauthorized: The API Key is invalid or the Authorization: Bearer header is missing.
403 Forbidden: The project’s subscription or contract is inactive.
404 Not Found: No response record exists for the specified responseId.

Implementation Sample (curl)

The following curl command reproduces a complete API call. Replace each environment variable with the actual values obtained from your project and the redirect callback:

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}"

Run this from your backend environment (not a browser console) to keep your API Key secure. A successful call returns the JSON response object described in STEP 5 above.

Frequently Asked Questions

What should I do if my API Key or Project Key is compromised?

You can regenerate either key immediately from the project detail screen using the “Regenerate API Key” or “Regenerate Project Key” buttons. The old key is invalidated the moment a new one is issued. There is no waiting period — your integration should switch to the new key right away to restore secure access.

Can the Redirect URL be changed after the project is created?

Yes. The Redirect URL can be updated at any time from the project detail screen. The change applies to all future redirects, including those using response slots that were already purchased. No re-purchase or project recreation is necessary when updating the URL.

When are response slots charged, and how much do they cost?

Response slots are purchased upfront at the time of project creation, at a rate of 5 USD per response (excluding applicable taxes). You specify the number of slots when setting up the project. For full pricing details and volume options, see the HEXACO-JP API service page.

What is the difference between the WORK_ONLY and FULL scope settings?

WORK_ONLY is the standard scope and returns approximately 80 work- and career-related behavioral tendency items. FULL expands this to approximately 90 tendency items and also includes the necessities object — a set of hierarchical intrinsic motivation scores. The active scope is always visible in the scope field of every API response, so your application can branch logic accordingly.

Can the scope be changed after a project is already running?

Yes, it is possible to switch between WORK_ONLY and FULL at the project level. However, scope changes are handled through the support team rather than the self-serve dashboard. If you would like to upgrade or downgrade your scope, please reach out via the contact page.

What does the sessionData parameter do, and what values can it hold?

sessionData is a free-form, URL-encoded string that you supply when redirecting the user to the survey. It is returned unchanged in the callback query parameters after the user submits. Its purpose is to let you identify which user in your own system completed the survey — common values include email addresses or internal user IDs. There is no fixed format requirement beyond valid URL encoding.

Is it safe to call the API endpoint from a browser or mobile app directly?

No. The API Key (in JWT format) must never be exposed in client-side code — this includes browser JavaScript and mobile application binaries. Always route the API call through your own backend server, which keeps the key hidden from end users. The redirect callback parameters can be safely received on the client side, but the actual results fetch should happen server-to-server.

Summary and Related Resources

This HEXACO-JP API integration guide has walked you through all 5 steps: creating a project and obtaining keys, redirecting users to the survey, handling the callback, and fetching fully scored personality data via a single authenticated REST API call. The HEXACO API endpoints are designed to be minimal and predictable — once your redirect and callback handling are in place, retrieving a rich personality profile including 6 dimension scores, 24 facets, and up to approximately 90 behavioral tendency items requires only one GET request. If you’re ready to connect personality science to your product, create your first project and run your first HEXACO personality assessment API call today.

HEXACO-JP REST API Docs: Get Diagnosis Results