HEXACO-JP API 문서는 귀사의 서비스에 성격 진단 기능을 손쉽게 통합할 수 있도록 설계된 REST API 연동 가이드입니다. 이 문서 한 편만 숙지하면, 사용자 리다이렉트부터 진단 결과 수신까지 전체 흐름을 5단계로 완성할 수 있습니다. HR 플랫폼, 채용 시스템, 팀 빌딩 도구 등 다양한 서비스에 세계적으로 검증된 HEXACO 성격 모델을 바로 적용해 보세요.
OpenAPI 사양 기반의 대화형 문서(Swagger UI)는 이 링크에서도 확인할 수 있습니다. API를 사용하려면 먼저 진단 사이트에서 프로젝트를 생성하고 응답 슬롯을 구매해야 합니다.
HEXACO-JP API 연동 전체 흐름
API 연동은 총 5단계로 구성되며, 각 단계는 순서대로 진행됩니다. 전체 흐름을 미리 파악해 두면 개발 범위를 정확히 예측할 수 있고, 불필요한 시행착오를 줄일 수 있습니다. 아래는 연동의 큰 그림입니다.
- 진단 사이트에서 프로젝트를 생성하고, 프로젝트 키·API 키·리다이렉트 URL을 발급받습니다.
- 귀사 서비스에서 대상 사용자를 HEXACO-JP 응답 화면으로 리다이렉트합니다.
- 사용자가 100문항에 응답하고 제출합니다.
- 제출 완료 후, 귀사가 지정한 리다이렉트 URL로 사용자가 돌아옵니다. 이때 쿼리 파라미터에 응답 ID 등 메타데이터가 포함됩니다.
- 수신한 쿼리 정보를 이용해 REST API를 호출하고 결과 데이터를 가져옵니다.
이 흐름은 OAuth 2.0의 인가 코드 방식과 유사한 구조를 가집니다. 사용자 인증과 데이터 수신이 분리되어 있어 보안성이 높으며, API 키는 반드시 서버 측에서만 사용해야 합니다.
STEP 1 · 2: 프로젝트 생성 및 사용자 리다이렉트
프로젝트 생성 단계에서 발급받는 2가지 키(프로젝트 키, API 키)가 전체 연동의 핵심입니다. 진단 사이트에 로그인한 뒤 메뉴에서 비즈니스 이용을 선택하고 신규 프로젝트를 생성합니다. 생성 시 다음 항목을 설정합니다.
- 프로젝트 타입: 「API」 선택
- 리다이렉트 URL: 사용자가 응답 제출 후 이동할 귀사 사이트의 URL (이후 변경 가능)
- 응답 수: 구매할 응답 슬롯 수 (1회당 5 USD)
- 문항 내용: HEXACO-JP 100문항 (소요 시간 약 10분)
프로젝트 생성 후 상세 화면에서 프로젝트 키와 API 키(JWT 형식)가 발급됩니다. 두 키 모두 재생성이 가능하며, 리다이렉트 URL도 언제든지 편집할 수 있습니다. 키가 외부에 노출된 경우에는 즉시 재생성하여 기존 키를 무효화하세요.
프로젝트 키를 발급받았다면, 아래 URL 형식으로 사용자를 성격 진단 화면으로 리다이렉트합니다.
https://personalities.me/biz/survey?token=<project_key>&sessionData=<session_data>token: 프로젝트 상세 화면의 프로젝트 키를 입력합니다.sessionData: 귀사 측에서 사용자를 고유하게 식별할 수 있는 임의의 URL 인코딩 문자열 (예: 이메일 주소). 응답 완료 후 그대로 귀사로 반환됩니다.
STEP 3 · 4: 응답 제출 및 리다이렉트 수신
사용자가 100문항에 응답을 완료하고 제출 버튼을 누르면, 응답 저장과 채점 처리는 sunblaze.jp 서버에서 자동으로 진행됩니다. 개발자가 별도로 채점 로직을 구현할 필요가 없으므로, 결과 수신과 표시에만 집중할 수 있습니다.
제출이 완료되면 사용자는 프로젝트에 등록된 리다이렉트 URL로 돌아오며, 이때 다음 5가지 쿼리 파라미터가 자동으로 추가됩니다.
projectId(GUID): 프로젝트 식별자surveyType(문자열, 예:hexaco-jp100): 진단 종류responseId(GUID): 이번 응답의 고유 IDuserId(GUID): 응답자의 사용자 IDsessionData: STEP 2에서 귀사가 지정한 문자열 (그대로 반환)
실제 리다이렉트 URL의 예시는 다음과 같습니다.
<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귀사 서버는 이 쿼리 파라미터 값들을 파싱하여 다음 단계의 API 호출에 사용합니다. sessionData를 활용하면 귀사 내부 사용자 DB와 응답 결과를 손쉽게 매핑할 수 있습니다.
STEP 5: API 엔드포인트 사양 및 응답 형식
결과 데이터는 REST API 단일 엔드포인트 호출로 모두 수신할 수 있으며, API 키는 반드시 서버 측에서만 사용해야 합니다. 브라우저(클라이언트) 측에 API 키가 노출되지 않도록 주의하세요.
API 엔드포인트 사양
GET https://psych.sunblaze.jp/api/psych/v1/projects/{projectId}/surveys/{surveyType}/users/{userId}/responses/{responseId}
Authorization: Bearer <api_key>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}"scope 파라미터와 응답 항목의 차이
프로젝트 계약 시 선택한 scope에 따라 응답 데이터의 항목 수와 내용이 달라집니다. 응답 JSON의 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
}
}각 응답 필드의 의미는 다음과 같습니다.
status:"completed"(완료) 또는"in_progress"(미완료). 미완료 시completedAt과durationSeconds는null이 됩니다.scores: HEXACO 6요소(정직-겸손성, 감정성, 외향성, 원만성, 성실성, 개방성)의 점수(value)와 모집단 평균(average)facets: HEXACO의 하위 패싯(성실성·공정성 등 총 24개 항목)tendencies: 업무·성격 특성과 연결된 행동 경향. 스코프에 따라 항목 수가 달라집니다.necessities:scope=FULL일 때만 반환되는 내적 욕구 계층 점수.
HTTP 상태 코드 일람
API 호출 시 발생할 수 있는 상태 코드와 그 의미를 미리 파악해 두면 오류 처리 로직을 안정적으로 구현할 수 있습니다.
200 OK: 요청 성공. 결과 JSON이 반환됩니다.400 Bad Request: 경로 파라미터가 API 키로 인증된 프로젝트와 일치하지 않을 때 반환됩니다. 구체적인 발생 조건은 다음 4가지입니다. ① API 키에서 특정된 프로젝트와projectId가 다를 때, ② 응답이 해당 프로젝트에 속하지 않을 때, ③ 응답의surveyType이 경로와 다를 때, ④ 응답의userId가 경로와 다를 때, ⑤ 응답이 아직 완료되지 않았을 때(제출 전)401 Unauthorized: API 키가 유효하지 않거나Authorization: Bearer헤더가 누락된 경우403 Forbidden: 프로젝트 계약이 유효하지 않은 경우404 Not Found: 지정한 응답이 존재하지 않는 경우
자주 묻는 질문
API 키나 프로젝트 키가 외부에 노출된 경우 어떻게 해야 하나요?
프로젝트 상세 화면의 「API 키 재생성」 및 「프로젝트 키 재생성」 버튼을 클릭하면 즉시 새로운 키가 발급됩니다. 기존 키는 재생성 즉시 무효화되므로, 노출이 의심되는 시점에 지체 없이 재생성하는 것이 권장됩니다.
리다이렉트 URL은 나중에 변경할 수 있나요?
네, 가능합니다. 프로젝트 상세 화면의 리다이렉트 URL 항목에서 언제든지 수정할 수 있습니다. 변경된 URL은 이미 발급된 응답 슬롯에도 즉시 적용되므로, 도메인 이전이나 URL 구조 변경 시에도 유연하게 대응할 수 있습니다.
응답 1건당 비용과 과금 시점은 언제인가요?
응답 1건당 5 USD(세금 별도)이며, 프로젝트 생성 시 지정한 응답 수만큼 사전에 과금됩니다. 즉, 실제 응답이 발생하기 전에 슬롯을 먼저 구매하는 선불 방식입니다. 자세한 내용은 서비스 소개 페이지를 참고해 주세요.
scope(WORK_ONLY / FULL)는 나중에 변경할 수 있나요?
네, 프로젝트 단위로 WORK_ONLY와 FULL 간의 전환이 가능합니다. 변경을 원하시는 경우 문의 페이지를 통해 연락해 주시면 안내해 드립니다. FULL 스코프로 전환하면 약 90개의 성향 항목과 내적 욕구 계층 데이터(necessities)를 추가로 활용할 수 있습니다.
sessionData에는 어떤 값을 넣어야 하나요?
sessionData는 귀사 서비스에서 사용자를 고유하게 식별할 수 있는 임의의 문자열을 URL 인코딩하여 사용합니다. 일반적으로 사용자 이메일 주소나 내부 사용자 ID를 활용합니다. 이 값은 응답 완료 후 리다이렉트 URL의 쿼리 파라미터로 그대로 반환되므로, 귀사 DB와의 매핑 키로 활용하면 편리합니다.
HEXACO-JP 성격 진단 API를 활용할 수 있는 서비스는 어떤 것이 있나요?
연구에 따르면 HEXACO 모델은 채용 적합성 평가, HR 플랫폼의 직원 배치, 팀 빌딩 도구, 커리어 코칭 서비스 등에 효과적으로 활용되는 경향이 있습니다. API 방식으로 제공되므로 기존 시스템에 최소한의 개발 공수로 통합할 수 있으며, HEXACO 6요소와 24개 패싯 데이터를 바탕으로 심층적인 성격 인사이트를 제공할 수 있습니다.
마치며: HEXACO-JP API 문서를 활용한 다음 단계
이 글에서는 HEXACO-JP API 문서를 바탕으로 프로젝트 생성부터 결과 수신까지의 5단계 연동 흐름, API 엔드포인트 사양, scope 파라미터의 차이, 응답 형식, 그리고 HTTP 상태 코드 처리 방법을 상세히 살펴보았습니다. 개발자 연동 가이드로서 이 문서 하나만으로도 기본 구현을 완성하기에 충분한 정보를 담고 있습니다.
성격 진단 API를 통해 귀사 서비스에 어떤 인사이트를 추가할 수 있는지 직접 확인해 보세요. 진단 사이트에서 프로젝트를 생성하고, 귀사 사용자에게 맞는 성향 데이터를 실제로 받아보는 것이 가장 빠른 이해의 지름길입니다. 연동 과정에서 궁금한 점이 생기면 문의 페이지나 Swagger UI를 적극 활용하시기 바랍니다.