HEXACO-JP API 문서를 처음 접하는 개발자라면, 자사 서비스에 성격 진단 기능을 연동하는 전체 흐름을 한눈에 파악하는 것이 중요합니다. 이 페이지에서는 HEXACO-JP API를 자사 서비스에 통합하기 위한 단계별 절차와 API 엔드포인트 사양을 상세히 설명합니다. API를 이용하려면 먼저 진단 사이트에서 프로젝트를 생성하고 응답 횟수를 구매해야 합니다.
HEXACO 성격 진단은 정직성·겸손함, 감정성, 외향성, 원만성, 성실성, 개방성이라는 6가지 핵심 요소로 인간의 성격을 측정하는 심리학적으로 검증된 도구입니다. 이 API를 활용하면 채용, 팀 구성, 커리어 컨설팅 등 다양한 비즈니스 서비스에 과학적 성격 데이터를 손쉽게 통합할 수 있습니다.
프로젝트 연동 절차의 전체 흐름
API 연동의 핵심은 5단계 순환 구조로 이루어집니다. 각 단계가 유기적으로 연결되어 있으므로, 전체 흐름을 먼저 이해한 뒤 세부 구현에 착수하는 것이 효율적입니다. 아래 순서를 기준으로 개발 계획을 수립하세요.
- 진단 사이트에서 프로젝트를 생성하고, 프로젝트 키·API 키·리다이렉트 URL을 발급받습니다.
- 자사 서비스에서 대상 사용자를 HEXACO-JP 응답 화면으로 리다이렉트합니다.
- 사용자가 100문항에 응답하고 제출합니다.
- 제출 완료 후, 자사가 지정한 리다이렉트 URL로 사용자가 돌아옵니다(쿼리에 응답 ID 등이 자동으로 부여됨).
- 쿼리 정보를 활용해 REST API로 진단 결과 데이터를 취득합니다.
이 5단계 구조를 이해하면, 각 단계에서 무엇을 준비하고 어떤 데이터를 주고받는지 명확해집니다. 이제 각 단계를 자세히 살펴보겠습니다.
STEP 1 — 프로젝트 생성 및 키 발급
모든 연동의 출발점은 진단 사이트에서의 프로젝트 생성입니다. 진단 사이트에 로그인한 후, 메뉴에서 비즈니스 이용을 선택하여 신규 프로젝트를 만듭니다.
- 프로젝트 타입: 「API」를 선택합니다.
- 리다이렉트 URL: 사용자가 응답 제출 후 돌아올 자사 사이트의 URL을 입력합니다(나중에 수정 가능).
- 응답 횟수: 구매할 응답 슬롯 수를 지정합니다. 1회당 5 USD입니다.
- 문항 내용: HEXACO-JP 100문항(소요 시간 약 10분)이 자동으로 사용됩니다.
프로젝트 생성 후, 상세 화면에서 프로젝트 키와 API 키가 자동으로 발급됩니다. 두 키 모두 재생성이 가능하며, 리다이렉트 URL도 이후 언제든지 수정할 수 있습니다. 키가 외부에 노출되었다고 판단될 경우 즉시 재생성하는 것을 권장합니다.
STEP 2 & 3 — 사용자 리다이렉트 및 응답 제출
자사 서비스에서 아래 URL로 사용자를 리다이렉트하면 진단이 시작됩니다. 버튼이나 링크를 활용해 자연스럽게 유도하는 방식이 일반적입니다.
https://personalities.me/biz/survey?token=<project_key>&sessionData=<session_data>token: 프로젝트 상세 화면에서 확인한 프로젝트 키를 입력합니다.sessionData: 자사 측에서 사용자를 고유하게 식별할 수 있는 임의의 URL 인코딩 문자열입니다(예: 이메일 주소). 응답 완료 후 그대로 반환됩니다.
사용자는 리다이렉트된 화면에서 HEXACO-JP 100문항(약 10분)에 응답하고 제출 버튼을 누릅니다. 응답 데이터의 서버 저장 및 채점 처리는 모두 Sunblaze 측에서 자동으로 처리되므로, 자사 서버에 별도의 채점 로직을 구현할 필요가 없습니다.
STEP 4 — 자사 서비스로의 리다이렉트와 쿼리 파라미터
제출이 완료되면 사용자는 자사가 등록한 리다이렉트 URL로 자동 복귀하며, 결과 취득에 필요한 메타데이터가 쿼리 파라미터로 함께 전달됩니다. 이 파라미터들을 자사 서버에서 수신하고 저장해 두는 것이 다음 단계의 핵심입니다.
projectId(GUID): 프로젝트를 식별하는 고유 IDsurveyType(문자열, 예: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.comSTEP 5 — REST API로 진단 결과 취득 및 API 응답 형식
HEXACO-JP API 문서에서 가장 중요한 부분은 실제 결과 데이터를 가져오는 REST API 호출 방법입니다. 자사 서버에서 아래 엔드포인트를 호출할 때, 쿼리로 받은 값을 경로에 삽입하고 헤더에 API 키를 Bearer 형식으로 부여해야 합니다.
API 엔드포인트 사양
GET https://psych.sunblaze.jp/api/psych/v1/projects/{projectId}/surveys/{surveyType}/users/{userId}/responses/{responseId}
Authorization: Bearer <api_key>보안상 중요한 주의 사항: API 키는 반드시 자사 서버 경유로만 호출해야 하며, 브라우저(클라이언트 사이드)에 노출되어서는 안 됩니다. 프론트엔드 코드에 API 키를 직접 포함하면 심각한 보안 위협으로 이어질 수 있습니다.
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: 성실성, 공정성 등 각 요소의 하위 패싯(facet) 점수 목록입니다.tendencies: 리더십, 팀워크 등 약 90개 항목의 성향 지수를 0~100 사이 값으로 제공합니다.
HTTP 상태 코드 일람
200 OK: 요청 성공, 결과 데이터가 반환됩니다.401 Unauthorized: API 키가 유효하지 않거나 지정되지 않았습니다.403 Forbidden: 프로젝트 계약이 유효하지 않습니다(응답 잔여 횟수 부족 등).404 Not Found: 지정한 응답 ID가 존재하지 않습니다.
curl을 활용한 구현 샘플
아래는 curl을 사용한 가장 간단한 API 호출 예시입니다. 실제 구현 시에는 환경 변수를 통해 키 값을 안전하게 관리하세요.
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}"이 샘플을 기반으로 Python, Node.js, PHP 등 자사 기술 스택에 맞게 변환하여 적용할 수 있습니다. API 호출은 반드시 서버 사이드에서 실행해야 한다는 점을 재차 강조합니다.
자주 묻는 질문 (FAQ)
API 키 또는 프로젝트 키가 외부에 노출되었을 때는 어떻게 하나요?
프로젝트 상세 화면의 「API 키 재생성」 또는 「프로젝트 키 재생성」 버튼을 클릭하면 즉시 새 키가 발급됩니다. 기존 키는 재생성과 동시에 즉각 무효화되므로, 노출이 의심되는 즉시 재생성하는 것을 강력히 권장합니다. 재생성 후에는 자사 서버 환경 변수도 반드시 업데이트해야 합니다.
리다이렉트 URL은 프로젝트 생성 후에도 변경할 수 있나요?
네, 가능합니다. 프로젝트 상세 화면의 리다이렉트 URL 항목에서 언제든지 수정할 수 있습니다. 변경된 URL은 이미 발급된 응답 슬롯에도 즉시 적용됩니다. 따라서 스테이징 환경과 프로덕션 환경을 전환할 때도 유연하게 대응할 수 있습니다.
응답 횟수는 어떤 방식으로 과금되나요?
프로젝트 생성 시 지정한 응답 횟수만큼 사전에 일괄 과금됩니다. 1회당 5 USD(세금 별도)입니다. 잔여 응답 횟수를 소진한 경우, 추가 구매 후 계속 이용할 수 있습니다. 자세한 요금 정책은 서비스 소개 페이지를 참조하세요.
sessionData 파라미터에는 어떤 값을 넣어야 하나요?
sessionData는 자사 시스템에서 응답자를 고유하게 식별할 수 있는 임의의 문자열을 URL 인코딩하여 전달합니다. 이메일 주소, 내부 사용자 ID, 세션 토큰 등을 활용할 수 있습니다. 이 값은 응답 완료 후 리다이렉트 URL의 쿼리 파라미터로 그대로 반환되므로, 어떤 사용자의 응답인지 매핑하는 데 활용할 수 있습니다.
API 응답의 tendencies(성향) 항목에는 어떤 데이터가 포함되나요?
tendencies 필드에는 리더십, 팀워크, 스트레스 내성 등 약 90개 항목의 성향 지수가 0~100 범위의 수치로 제공됩니다. 이 수치들은 HEXACO 6요소 점수를 기반으로 산출되며, 채용 적합도 분석이나 팀 구성 최적화 등 다양한 비즈니스 용도로 활용할 수 있습니다. 연구에 따르면 이러한 복합 지표는 단일 점수보다 실무 적용 정확도가 높아지는 경향이 있습니다.
HEXACO 성격 진단은 얼마나 신뢰할 수 있는 도구인가요?
HEXACO 모델은 심리학 연구 분야에서 광범위하게 검증된 성격 측정 도구로, 기존의 빅 5(Big Five) 모델에 정직성·겸손함 요소를 추가한 6요소 구조가 특징입니다. 연구에 따르면 문화권을 초월하여 안정적인 측정 결과를 나타내는 경향이 있으며, 특히 직업 및 조직 심리학 분야에서의 적용 가능성이 높다고 알려져 있습니다.
마무리 — HEXACO-JP API 문서를 활용한 다음 단계
이 문서에서 설명한 5단계 연동 절차를 따르면, 자사 서비스에 과학적으로 검증된 HEXACO 성격 진단 기능을 체계적으로 통합할 수 있습니다. 프로젝트 생성부터 API 키 발급, 사용자 리다이렉트, 그리고 REST API를 통한 진단 결과 취득까지의 전체 흐름을 이해했다면, 실제 구현에 자신감을 가지고 착수할 수 있을 것입니다. HEXACO-JP API 문서를 참고하여 자사 서비스만의 성격 데이터 활용 방식을 설계해 보세요 — 채용 심사, 팀 빌딩, 자기계발 플랫폼 등 어떤 맥락에서든 약 90개 성향 지표가 의사결정의 질을 높이는 데 기여할 것입니다. 궁금한 점이 있다면 문의 페이지를 통해 언제든지 질문하세요.