사이드 메뉴
커뮤니케이션
API 제공
어드민 API
이해하기
이 문서는 카카오 또는 공동체 서비스용 사용자 정보에 대해 안내합니다. 카카오 로그인을 사용하면 여러 카카오 API로 다양한 사용자 정보를 제공받을 수 있습니다.
이 문서에 안내된 사용자 정보는 서비스 앱에 카카오 로그인한 사용자에 한해 제공 가능합니다. 카카오 로그인을 사용하지 않는 서비스나 사용자의 정보는 카카오 API 플랫폼에서 제공할 수 없습니다.
카카오 로그인을 사용하는 서비스는 사용자 정보 조회 등 카카오 API로 여러 사용자 정보를 제공받을 수 있습니다. 제공하는 사용자 정보는 앱 관리 페이지의 [카카오 로그인] > [동의항목]에 설정된 항목들을 포함하며, 일부 사용자 정보는 동의항목 설정 및 응답 권한이 필요합니다.
이 문서에서 필요한 사용자 정보를 찾을 수 없는 경우, 제공 여부를 [서비스] API플랫폼 아지트로 문의합니다.
서비스는 사용자 정보 조회로 카카오 로그인한 사용자의 정보를 요청할 수 있습니다.
사용자 정보 조회로 제공받을 수 있는 카카오 로그인 사용자의 기본적인 정보입니다. 기본 정보는 사용자가 각 서비스 앱에 카카오 로그인해 발급받은 고유 식별자인 회원번호와 앱 연결 시각을 포함합니다. 기본 정보는 동의항목 설정 없이도 제공받을 수 있습니다. 일부 응답 필드는 권한이 있어야 제공받을 수 있습니다.
아래는 제공받을 수 있는 기본 정보의 종류를 정리한 표입니다. API 응답 상세 정보는 사용자 정보 조회를 참고합니다.
| 사용자 정보(Key) | 설명 |
|---|---|
| 회원번호 ( id) | 앱에서 사용자를 식별하기 위한 고유 값 |
| 카카오계정 ID ( account_id)Internal Only | 카카오 및 공동체 서비스에만 제공하는 카카오계정 ID 응답 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 카카오톡 회원번호 ( talk_user_id)Internal Only | 카카오 및 공동체 서비스에만 제공하는 연결된 카카오톡 회원번호 응답 권한 필요 |
| 다음 회원 ID ( daum_user_id)Internal Only | 카카오 및 공동체 서비스에만 제공하는 다음 ID 카카오계정이 다음 통합 계정인 경우 제공 응답 권한 필요 |
| 연결 여부 ( has_signed_up) | 앱과 사용자의 연결 여부 자동 연결 설정을 비활성화한 경우만 존재 수동 연결 참고 |
| 연결 시각 ( connected_at) | 연결 완료 시각 자동 연결의 경우, 첫 카카오 로그인을 완료해 사용자와 앱이 연결된 시각 수동 연결의 경우, 수동 연결 API로 사용자와 앱이 연결된 시각 |
| 싱크 연결 시각 ( synched_at) | 카카오싱크 간편가입으로 로그인한 시각 |
| 사용자 프로퍼티 ( properties) | 서비스의 사용자 정보를 카카오 플랫폼에 저장하고자 할 때 사용 사용자 프로퍼티 참고 |
| 그룹 사용자 토큰 ( group_user_token) | 해당 앱이 그룹 앱에 속한 경우 그룹에서 맵핑(Mapping) 정보로 사용할 수 있는 값 그룹 정보가 변경되면 바뀔 수 있는 값이므로 사용자 ID로 사용하지 말 것 앱 설정 권한 필요 |
참고: 제휴 정보
아래는 일부 공동체에 제공하는 제휴 정보입니다.
| 사용자 정보(Key) | 설명 |
|---|---|
| 고유 ID ( uuid) | 다른 사용자의 친구 정보에서 보여지는 해당 사용자의 고유 ID 서비스의 초대 이벤트 보상 처리를 위해 사용자 정보 조회 API로도 제공 |
| 남은 초대 메시지 전송 횟수(게임 전용) ( remaining_invite_count) | 카카오게임 전용 남은 일별 초대 메시지 전송 횟수 |
| 남은 그룹방 메시지 전송 횟수(게임 전용) ( remaining_group_msg_count) | 카카오게임 전용 남은 일별 그룹 메시지 전송 횟수 |
사용자 정보 조회로 제공받을 수 있는 카카오 로그인 사용자의 카카오계정 정보입니다. 각 카카오계정 정보는 항목별 동의항목을 설정하고, 카카오 로그인 시 사용자가 해당 동의항목에 동의해야 제공받을 수 있습니다. 일부 정보는 권한이 있어야 동의항목 설정 및 정보 제공이 가능합니다.
아래는 제공받을 수 있는 카카오계정 정보의 종류와 동의항목을 정리한 표입니다. API 응답 상세 정보는 사용자 정보 조회를 참고합니다.
| 사용자 정보(Key) | 동의항목 | 설명 |
|---|---|---|
| 닉네임 ( nickname) | 프로필(닉네임/사진) 또는 닉네임 | 닉네임 참고: 2021년 6월 25일부터 프로필 정보를 닉네임, 프로필 사진으로 분리해 제공, 공지 참고, 신규 동의항목을 사용하려면 [서비스] API플랫폼 아지트로 문의 |
| 프로필 사진 ( profile_image_url) | 프로필(닉네임/사진) 또는 프로필 사진 | 프로필 이미지 URL 참고: 2021년 6월 25일부터 프로필 정보를 닉네임, 프로필 사진으로 분리해 제공, 공지 참고, 신규 동의항목을 사용하려면 [서비스] API플랫폼 아지트로 문의 |
| 프로필 썸네일 이미지 ( thumbnail_image_url) | 프로필(닉네임/사진) 또는 프로필 사진 | 프로필 이미지의 미리보기 이미지 URL 참고: 2021년 6월 25일부터 프로필 정보를 닉네임, 프로필 사진으로 분리해 제공, 공지 참고, 신규 동의항목을 사용하려면 [서비스] API플랫폼 아지트로 문의 |
| 기본 프로필 이미지 여부 ( is_default_image) | 프로필(닉네임/사진) 또는 프로필 사진 | 프로필 이미지 URL이 기본 프로필 이미지 URL인지 여부 사용자가 등록한 프로필 이미지가 없을 경우, 기본 프로필 이미지 제공 |
| 카카오계정(이메일) ( account_email) | 카카오계정(이메일) | 대표 이메일 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 중요: 이메일 사용 시 주의 사항 |
| 유효 이메일 여부 ( is_email_valid) | 카카오계정(이메일) | 이메일이 다른 카카오계정에 사용돼 만료되었다면 무효(false) 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 이메일 인증 여부 ( is_email_verified) | 카카오계정(이메일) | 이메일 인증 여부 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 이름 ( name) | 이름 | 카카오계정의 이름 본인인증된 실명이 있다면 해당 값 제공 실명과 일치하지 않을 수 있으니, 실명이 필요할 경우 본인확인정보(이름) 사용 권장 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 참고: 본인확인정보(이름) 동의항목과 함께 사용할 수 없음 |
| 성별 ( gender) | 성별 | 성별 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 참고: 본인확인정보(성별) 동의항목과 함께 사용할 수 없음 |
| 연령대 ( age_range) | 연령대 | 연령대 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 생일 ( birthday) | 생일 | 생일 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 참고: 본인확인정보(생년월일) 동의항목과 함께 사용할 수 없음 |
| 생일 타입 ( birthday_type) | 생일 | 생일 타입, 양력 또는 음력 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 출생 연도 ( birtyear) | 출생 연도 | 출생 연도 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 참고: 본인확인정보(생년월일) 동의항목과 함께 사용할 수 없음 |
| 카카오계정(휴대전화번호) ( phone_number) | 카카오계정(전화번호) | 카카오계정에 연결된 카카오톡의 전화번호 연계정보(CI) 생성 시 사용된 전화번호와 무관 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| CI(연계정보) ( ci) | CI(연계정보) | 연계정보 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 본인인증 받은 시각 ( ci_authenticated_at) | CI(연계정보) | 본인인증기관이 연계정보를 발급한 시각 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 본인확인정보(이름) ( legal_name) | 본인확인정보(이름) | 본인인증을 거친 카카오계정 사용자 실명 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 참고: 이름 동의항목과 함께 사용할 수 없음 |
| 본인확인정보(생년월일) ( legal_birth_date) | 본인확인정보(생년월일) | 본인인증을 거친 법정 생년월일 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 참고: 생일, 출생 연도 동의항목과 함께 사용할 수 없음 |
| 본인확인정보(성별) ( legal_gender) | 본인확인정보(성별) | 본인인증을 거친 법정 성별 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 참고: 성별 동의항목과 함께 사용할 수 없음 |
| 본인확인정보(내외국인) ( is_korean) | 본인확인정보(내외국인) | 본인인증을 거친 내국인 여부 (대한민국 국적 보유 여부) 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 카카오계정 가입일자 ( account_creation_date) | 카카오계정 가입일자 | 카카오계정 가입일자 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 카카오톡 서비스 가입 여부 ( is_kakaotalk_user) | 카카오톡 서비스 가입 여부 | 카카오톡 서비스 가입 여부 동의항목 설정 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 카카오계정 대표 정보 ( display_id) | 카카오계정(이메일), 카카오계정(전화번호) | 카카오계정 대표 정보(기본값: 이메일 또는 전화번호) 응답 권한 필요 참고: 카카오계정 대표 정보 |
| 카카오계정 통합 여부 ( unification_status) | - | 카카오계정 통합 여부 응답 권한 필요 |
카카오계정 대표 정보(display_id)는 서비스에서 카카오계정 정보를 표시할 때 사용할 수 있는 정보입니다. 각 카카오계정의 이메일과 전화번호 값을 바탕으로 구성됩니다. 가입 방법에 따라 카카오계정 정보에 이메일과 전화번호 값이 없을 수 있으므로, 서비스 내 카카오계정 정보를 일관되게 표시하려면 대표 정보를 사용합니다. 아래는 대표 정보 사용 시 주의 사항입니다.
- 이메일과 전화번호 두 가지 동의항목에 대한 사용자 동의 필요
- 인하우스 앱은 이메일과 전화번호를 [필수 동의] 동의항목으로 설정 후 응답 권한 신청 (참고: 인하우스 앱의 동의항목 설정)
- 공동체 앱은 이메일과 전화번호 [필수 동의] 동의항목 설정 권한, 카카오계정 대표 정보 응답 권한 신청 필요
email,phone_number값과 일치하지 않을 수 있음- 일부 마스킹(Masking)되어 제공될 수 있음 (참고: display_id 정책 정리)
사용자 정보 조회 또는 그룹 내 사용자 정보 조회로 제공하는 그룹 내 사용자 정보입니다. 그룹 내 사용자 정보는 그룹 앱에 속한 각 앱과 앱별 사용자 회원번호를 포함합니다.
| 사용자 정보(Key) | 동의항목 | 설명 |
|---|---|---|
| 그룹 사용자 토큰 ( group_user_token) | - | 해당 앱이 그룹 앱에 속한 경우 그룹에서 맵핑(Mapping) 정보로 사용할 수 있는 값 그룹 정보가 변경되면 바뀔 수 있는 값이므로 사용자 ID로 사용하지 말 것 앱 설정 권한 필요 사용자 정보 조회 API로도 제공하며, 해당 API로 group_user_token을 제공 받으려면 앱 설정 권한 필요 |
참고: 그룹 앱
그룹 앱은 2개 이상의 앱을 하나의 그룹으로 묶는 기능입니다. 그룹 앱 기능을 사용하려면 권한이 필요합니다.
카카오 로그인한 사용자의 카카오계정에 등록된 배송지를 제공합니다. 배송지는 Kakao SDK 또는 REST API로 요청 가능합니다. Kakao SDK는 사용자가 서비스에 제공하거나 추가, 수정할 배송지를 직접 선택할 수 있는 배송지 피커를 지원해 더욱 편리하게 배송지를 활용할 수 있습니다.
| 기능 | 요청 방식 | 설명 |
|---|---|---|
| 배송지 조회 | REST API / Kakao SDK | 배송지 ID에 해당하는 특정 배송지 또는 전체 배송지 목록 제공 참고: 배송지 조회 API만 단독으로 사용할 경우, 사용자가 전체 배송지 목록을 조회하고, 서비스에 제공할 배송지를 선택하는 배송지 목록 UI 직접 구현 필요 |
| 배송지 선택 | Kakao SDK | 사용자가 서비스에 제공할 배송지를 직접 선택할 수 있는 배송지 피커를 불러오고, 선택된 배송지의 ID 제공 |
| 배송지 등록 | Kakao SDK | 카카오 및 공동체 전용 기능 사용자가 카카오계정에 새로운 배송지를 등록할 수 있는 배송지 피커를 불러오고, 추가된 배송지의 ID 제공 |
| 배송지 수정 | Kakao SDK | 카카오 및 공동체 전용 기능 사용자가 카카오계정에 등록된 배송지를 수정할 수 있는 배송지 피커를 불러오고, 수정된 배송지의 ID 제공 |
배송지 기능을 사용하려면 아래 조건을 만족해야 합니다.
배송지 선택, 배송지 조회 API를 사용한 배송지 제공 과정에 대한 안내는 배송지를 참고합니다. 서비스에서 카카오계정의 배송지를 추가, 수정하는 방법에 대한 안내는 배송지 등록, 배송지 수정을 참고합니다.
배송지 피커로 사용자에게 새로운 배송지 추가를 요청하는 기능입니다. 이 기능을 사용하면 배송지 선택 과정을 거치지 않고 곧바로 새로운 배송지 등록을 요청할 수 있습니다.
- 먼저, 새로운 배송지 추가가 필요한 경우인지 판단합니다.
- 서비스에서 배송지 조회 API와 자체 구현한 배송지 목록을 사용하지만, 사용자 카카오계정에 등록된 배송지가 없는 경우
- 배송지 선택 API 사용 시에는 사용자 카카오계정에 등록된 배송지가 없다면 배송지를 등록하는 페이지가 출력되므로, 배송지 등록 API 별도 요청 불필요
- 배송지 등록 API로 사용자에게 새로운 배송지 등록을 요청하고, 추가된 배송지 ID를 받습니다.
- 배송지 조회 API로 추가된 배송지의 상세 정보를 받습니다.
배송지 피커로 사용자에게 카카오계정의 배송지를 수정 요청하는 기능입니다. 서비스에서 사용자의 배송지 ID와 함께 배송지를 저장하고 있는 경우, 서비스 UI로 사용자가 기존 배송지를 확인하고 필요 시 수정할 수 있도록 할 때 사용합니다. 배송지 수정은 수정된 배송지의 ID만 제공하므로, 수정된 배송지 상세 정보를 받으려면 아래와 같이 두 단계로 요청합니다.
- 기존 배송지의 ID로 배송지 수정 API를 요청해 배송지 피커에서 사용자가 배송지를 수정할 수 있도록 합니다. 사용자가 수정을 완료하면, 수정된 배송지의 ID가 반환됩니다.
- 수정된 배송지의 ID로 배송지 조회 API로 해당 배송지의 상세 정보를 받습니다.
공동체 앱: 사용자 분석 데이터 조회로 제공받을 수 있는 사용자 분석 데이터입니다. 해당 API는 공동체 전용으로 권한을 받아야 사용할 수 있으며, 동의항목 설정 및 사용자 동의가 필요합니다.
| 사용자 정보(Key) | 동의항목 | 설명 |
|---|---|---|
| 회원번호 ( id) | - | 앱에서 사용자를 식별하기 위한 고유 값 |
| 카카오계정 ID ( account_id)Internal Only | - | 카카오 및 공동체 서비스에만 제공하는 카카오계정 ID 응답 권한 필요 인하우스 앱은 별도 권한 신청 없이 사용 가능 |
| 추정 연령대 ( age_group) | 서비스 이용내역으로 추정한 정보(연령대,성별) | 추정 연령대와 추정 성별 동의항목 설정 권한 필요 API 사용 권한 필요 |
추정 성별(gender)( estimated_age_range) | 서비스 이용내역으로 추정한 정보(연령대,성별) | 추정 연령대와 추정 성별 동의항목 설정 권한 필요 API 사용 권한 필요 |
| 추정 관심사 ( interests) | 서비스 이용내역으로 추정한 정보(관심사) | 추정 관심사 동의항목 설정 권한 필요 API 사용 권한 필요 |
일부 사용자 정보는 앱에 동의항목을 설정하고, 해당 동의항목에 사용자가 동의해야 제공받을 수 있습니다. 동의항목를 참고합니다. 사용자 정보별 필요한 동의항목은 해당 사용자 정보 표의 동의항목 및 설명을 참고합니다.
카카오로부터 제공받은 사용자 이메일 사용 시, 이메일과 함께 제공하는 이메일 유효 여부(is_email_valid)와 이메일 인증 여부(is_email_verified) 값으로 유효한 이메일인지 항상 확인해야 합니다.(OIDC: 사용자 정보 조회의 경우 email_verified)
이메일 유효 여부 값이 false인 경우 이메일이 유효하지 않은 사용자에 해당하며, 해당 사용자의 이메일은 일부 마스킹(Masking)해 제공합니다. (예: ka***@kakao.com) 이메일 인증 여부가 false인 경우, 인증되지 않은 이메일이므로 사용자에게 서비스에서 발송한 이메일이 올바르게 전송되지 않을 수 있습니다.
또한 이메일은 사용자 요청에 따라 변경될 수 있으므로, 이메일을 ID로 사용하거나 이메일로 동일 사용자인지 확인하는 방식을 권장하지 않습니다.
사용자의 앱 연결 상태에 따른 호출 제한, SDK 지원 여부, 권한 요구 사항은 지원 범위를 참고합니다.
| API | 설명 | 문서 | |
|---|---|---|---|
| 사용자 정보 조회 | 사용자의 카카오계정 정보를 받습니다. 참고: 인하우스/공동체 문서의 사용자 정보 조회 API는 카카오와 공동체를 위한 추가 정보를 포함하며, 오픈 API보다 더 다양한 사용자 정보를 제공합니다. | REST API JavaScript Android iOS Flutter | |
| 사용자 목록 조회 | 앱의 사용자 회원번호 목록을 가져옵니다. | REST API | |
| 여러 사용자 정보 조회 | 앱과 연결된 사용자 여러 명의 정보를 받습니다. | REST API | |
| 사용자 프로퍼티 저장 | 사용자 프로퍼티 값을 저장합니다. | REST API JavaScript Android iOS Flutter | |
| 배송지 | 배송지 선택 | Kakao SDK에서 제공하는 기능입니다. 사용자가 서비스에 제공할 배송지를 직접 선택할 수 있는 배송지 피커를 불러오고, 선택된 배송지의 ID를 제공합니다. | JavaScript Android iOS Flutter |
| 배송지 조회 | 배송지 ID에 해당하는 특정 배송지 또는 전체 배송지 목록을 제공합니다. | REST API JavaScript Android iOS Flutter | |
| 배송지 등록 | Kakao SDK for Partner에서 제공하는 기능입니다. 사용자가 카카오계정에 새로운 배송지를 등록할 수 있는 배송지 피커를 불러오고, 추가된 배송지의 ID를 제공합니다. | JavaScript Android iOS | |
| 배송지 수정 | Kakao SDK for Partner에서 제공하는 기능입니다. 사용자가 카카오계정에 등록된 배송지를 수정할 수 있는 배송지 피커를 불러오고, 수정된 배송지의 ID를 제공합니다. | JavaScript Android iOS | |
| 사용자 ID 조회 | 특정 사용자 ID로 다른 유형 ID를 조회합니다. | REST API | |
| 그룹 내 사용자 정보 조회 | 그룹에 속한 다른 연결된 앱의 기본 정보와 사용자 회원번호를 가져옵니다. | REST API | |
| 연결된 앱 정보 조회 | 사용자와 연결된 앱의 정보를 가져옵니다. | REST API | |
| 앱 연결 이력 조회 | 사용자의 앱 연결 이력을 조회합니다. | REST API | |
| 카카오계정 상태 조회 | 사용자의 카카오계정 상태와 서비스 앱 로그인 가능 여부를 조회합니다. | REST API | |
| 카카오계정 검색 | 사용자의 이메일 또는 전화번호에 해당하는 카카오계정 ID를 조회합니다. | REST API | |
| 앱에 연결된 카카오계정 휴면 방지 | 사용자 카카오계정의 최종 접속 시간을 갱신해 휴면 상태로 전환되지 않게 합니다. | REST API | |
| 앱과 사용자 인증 | 액세스 토큰과 앱 키에 해당하는 앱이 일치하는지 확인합니다. | REST API | |
| 회원번호 사전 발급 | 앱에 연결 없음 상태의 사용자 회원번호를 생성합니다. | REST API | |
| 사용처 제한 API | 공동체 앱: 사용자 분석 데이터 조회 | 사용자의 카카오 플랫폼 내 서비스 이용내역을 분석해 추정한 성별, 연령대, 관심사 정보를 가져옵니다. | REST API |
| 공동체 앱: 본인인증 정보 등록 가능 여부 조회 | 요청 시 전달된 본인인증 정보를 카카오계정에 등록할 수 있는지 확인합니다. | REST API | |
| 공동체 앱: 카카오계정에 본인인증 정보 등록 | 사용자 카카오계정에 공동체에서 수집한 본인인증 정보를 등록합니다. | REST API | |
| 공동체 앱: 카카오계정에서 본인인증 정보 삭제 | 사용자 카카오계정에 등록한 공동체의 본인인증 정보를 삭제합니다. | REST API | |
| 공동체 앱: 카카오계정과 본인인증 정보 비교 | 요청 시 전달된 본인인증 정보가 카카오계정의 본인인증 정보와 일치하는지 비교합니다. | REST API | |