If you’re looking to embed psychological personality assessments directly into your platform, HEXACO-JP REST API integration offers a streamlined, developer-friendly solution. This guide walks you through every step — from project setup and API key generation to endpoint calls and response parsing — so your team can connect personality assessment data to your service with confidence.
The HEXACO-JP API is built around a simple redirect-and-retrieve flow. Your service sends users to a hosted survey, they complete the HEXACO 100-question assessment (approximately 10 minutes), and your backend retrieves richly structured personality data via a secure REST call. No proprietary SDK required — just standard HTTP requests and a few credential keys.
How HEXACO-JP REST API Integration Works: The Overall Flow
The entire integration follows 5 sequential steps, making it easy to reason about and implement incrementally. Understanding the big picture before writing a single line of code tends to reduce implementation errors significantly.
- Create a project on the diagnostic site and obtain your Project Key, API Key, and Redirect URL.
- Redirect your target user from your service to the HEXACO-JP survey screen.
- The user answers all questions and submits the assessment.
- After submission, the user is returned to your designated Redirect URL with metadata query parameters appended.
- Your server uses those query parameters to call the REST API and retrieve the full diagnostic result.
This architecture keeps sensitive scoring logic on Sunblaze’s servers while giving your application full programmatic access to the personality data API response. Each phase is independently testable, which is useful when debugging a specific step of your pipeline.
STEP 1 — Create a Project and Obtain Your Keys
Before any API call can be made, you need an active project on the diagnostic site, which issues the 2 credentials your integration depends on. Log in to the diagnostic site, select Business Use from the menu, and create a new project.
- Project Type: Select “API” to enable programmatic result retrieval.
- Redirect URL: The URL on your own site where users will land after completing the survey. This can be updated at any time.
- Response Count: The number of assessment slots you are purchasing upfront. Each slot costs 5 USD (tax exclusive).
- Survey Content: HEXACO-JP 100 questions — estimated completion time is approximately 10 minutes.
Once the project is created, your Project Key and API Key are displayed on the project detail screen. Both keys can be regenerated at any time (the old key is immediately invalidated), and the Redirect URL can be edited freely after creation.
STEP 2 & 3 — Redirecting Users to the Survey
Sending a user to the assessment screen requires only a single redirect URL with 2 query parameters. A button or hyperlink on your UI is the most common pattern.
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 (e.g., an email address or internal user ID). This value is returned to you unchanged after the survey is completed, making it easy to match results to your own user records.
Once redirected, the user completes the HEXACO-JP 100-question assessment. All response storage and scoring processing is handled server-side by Sunblaze — your application does not need to manage any of that data at this stage.
STEP 4 — Receiving the Redirect Callback
When the user submits their answers, they are automatically redirected back to your Redirect URL, and 5 key query parameters are appended to it. Your backend should be prepared to read and store these values, as they are required to retrieve results from the personality assessment API.
projectId(GUID) — Identifies the project.surveyType(string, e.g.,hexaco-jp100) — Identifies the assessment type.responseId(GUID) — Uniquely identifies this individual response.userId(GUID) — Identifies the respondent within the HEXACO-JP system.sessionData— The exact string your service passed in STEP 2, returned unchanged.
A typical redirect callback looks 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.comSTEP 5 — Calling the HEXACO-JP REST API Integration Endpoint
The diagnostic result API uses a single GET endpoint that embeds the 4 identifiers from the redirect callback directly into the URL path, with your API Key passed as a Bearer token. This endpoint should always be called from your server — never from client-side browser code — to avoid exposing your API Key.
API Endpoint
GET https://psych.sunblaze.jp/api/psych/v1/projects/{projectId}/surveys/{surveyType}/users/{userId}/responses/{responseId}
Authorization: Bearer <api_key>REST API Response Schema — What the Data Looks Like
A successful 200 OK response returns a richly structured JSON object covering HEXACO 6-factor scores, lower-level facets, and approximately 90 tendency indicators. Here is an example of the full personality data API response:
{
"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
}
}The response structure breaks down into 3 main data groups:
scores: The HEXACO 6-factor scores. Each factor includes the individual’svalueand the populationaverage, making it straightforward to compute relative standing.facets: Sub-facet scores (e.g., sincerity, fairness) that offer more granular insight within each broad factor.tendencies: Approximately 90 applied tendency indicators — such as leadership potential (72 in the example above) and teamwork orientation (85) — ready to use directly in your product logic.
HTTP Status Codes to Handle
200 OK: Request succeeded; response body contains the full personality data.401 Unauthorized: The API Key is missing or invalid.403 Forbidden: The project’s contract or subscription is inactive.404 Not Found: The specified response ID does not exist.
Quick Implementation Sample (curl)
The simplest way to verify your integration is working correctly is with a curl command using the 4 GUIDs from a test redirect. This is useful both for initial testing and for debugging production issues.
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}"Store your API_KEY as a server-side environment variable rather than hardcoding it into your source code. This reduces the risk of accidental credential exposure through version control systems.
Frequently Asked Questions
What should I do if my API Key or Project Key is compromised?
You can immediately regenerate either key from the project detail screen on the diagnostic site. Use the “Regenerate API Key” or “Regenerate Project Key” button. The old key is invalidated instantly upon regeneration, so any requests using the old credential will begin returning 401 errors right away. Update your server environment variables promptly after regenerating.
Can I change the Redirect URL after the project has been created?
Yes. The Redirect URL can be updated at any time from the project detail screen. The change applies to all subsequent completions, including responses from already-distributed survey links. This is useful when migrating between environments (e.g., staging to production) without needing to create a new project or purchase additional response slots.
When are response slots charged — upfront or per completion?
Response slots are purchased upfront at project creation time. Each slot costs 5 USD (tax exclusive), and the number of slots you specify is billed at that point. This means you pre-purchase a fixed number of assessment completions. For details on volume pricing or enterprise arrangements, see the service landing page.
What does the sessionData parameter do, and is it required?
The sessionData parameter is a URL-encoded string you supply when redirecting the user to the survey. It is returned to you unchanged in the redirect callback after survey completion. Its purpose is to let you match the returning user to your own internal records (e.g., by passing an email address or user ID). While technically optional, omitting it tends to make it harder to associate results with the correct user in your system.
What does the tendencies field in the API response contain?
The tendencies field contains approximately 90 applied behavioral tendency scores derived from the HEXACO personality assessment. Examples include indicators like leadership potential and teamwork orientation, expressed as numeric values (0–100 scale). These scores are designed to be directly usable in product features such as team matching, role recommendation, or candidate evaluation, without requiring additional scoring logic on your side.
Is it safe to call the API from a browser-side JavaScript client?
No — calling the HEXACO-JP REST API integration endpoint from browser-side code is not recommended. Doing so would expose your API Key in the client environment, where it could be extracted by anyone inspecting network traffic or source code. All API requests should be made from your own backend server, which then passes only the necessary result data to the front end.
How long does it take users to complete the HEXACO-JP assessment?
The HEXACO-JP consists of 100 questions and typically takes approximately 10 minutes to complete. This estimate tends to vary slightly based on the individual respondent’s reading pace. The durationSeconds field in the API response records the exact elapsed time for each completion, which can be useful for detecting anomalous (unusually fast) response patterns in your data.
Summary
The HEXACO-JP REST API integration is designed to be both developer-accessible and psychologically rigorous. In just 5 steps — create a project, redirect users, handle the callback, call the API endpoint, and parse the JSON response — your service gains access to HEXACO 6-factor scores, lower-level facets, and approximately 90 behavioral tendency indicators per respondent. The REST API response schema is consistent and well-structured, making it straightforward to map personality data into your existing product logic. If you’re ready to bring validated personality science into your platform, set up your first project and explore what your users’ personality data can reveal.