---
url: /api-sdk/data/user-nicknames.md
description: 파트너사가 회원번호 목록으로 게임플레이 프로필 닉네임을 일괄 조회하는 API
---

# 사용자 닉네임 목록 조회 API

파트너사가 카카오 서버로 호출하는 API입니다. 전달한 회원번호(`user_ids`) 목록에 대해 각 사용자의 게임플레이 프로필 닉네임을 일괄 조회합니다.

게임 안에서 사용자 표기·랭킹에 카카오톡 게임플레이 닉네임을 그대로 사용할 때 씁니다.

## Endpoint

```http
GET https://kapi.kakao.com/v1/gameplay/profiles
```

## 요구 사항

* [카카오 로그인 사용 설정](https://developers.kakao.com/docs/ko/kakaologin/prerequisite#kakao-login-activate)

## 인증

파트너사 디벨로퍼스 앱의 [어드민 키](https://developers.kakao.com/docs/ko/app-setting/app#admin-key)로 인증합니다.

| Header | 설명 |
| --- | --- |
| `Authorization` | 필수`KakaoAK {SERVICE_APP_ADMIN_KEY}`: 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
| `Content-Type` | 필수`application/x-www-form-urlencoded;charset=utf-8` |

::: danger 주의사항
어드민 키는 앱의 모든 권한을 가지므로 **어떤 경우에도 외부에 노출되면 안 됩니다.** 게임 클라이언트 번들·소스 저장소·로그에 키를 남기지 말고, 파트너사 서버의 환경 변수나 시크릿 저장소에서 주입합니다. 게임웹뷰에서 이 API를 직접 호출하면 요청 헤더에 키가 그대로 드러나므로, 반드시 파트너사 서버를 경유해 호출합니다.
:::

## Request

조회할 회원번호를 쿼리 파라미터로 전달합니다.

| 파라미터 | 타입 | 설명 |
| --- | --- | --- |
| `user_ids` | `Long[]` | 필수게임플레이 프로필을 조회할 사용자의 회원번호 목록. 회원번호는 카카오계정과 앱이 연결될 때 부여하는 앱별 사용자 ID입니다. **최대 50개**이며, 초과하면 여러 번 나누어 호출합니다. |

```bash
curl -G GET "https://kapi.kakao.com/v1/gameplay/profiles" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  --data-urlencode 'user_ids=[123456789,987654321]'
```

## Response

`200 OK`.

| 필드 | 타입 | 제공 여부 | 설명 |
| --- | --- | --- | --- |
| `targets` | `GameplayProfileInfo[]` | 항상 | 조회된 게임플레이 프로필 목록. 조회된 프로필이 없으면 빈 배열 |

**`GameplayProfileInfo`**

| 필드 | 타입 | 제공 여부 | 설명 |
| --- | --- | --- | --- |
| `user_id` | `Long` | 항상 | 서비스 앱의 회원번호 |
| `nickname` | `String` | 항상 | 게임플레이 프로필 닉네임 |

**조회된 프로필이 있는 경우**

```json
{
  "targets": [
    {
      "user_id": 123456789,
      "nickname": "카카오프렌즈"
    },
    {
      "user_id": 987654321,
      "nickname": "게임마스터"
    }
  ]
}
```

**조회된 프로필이 없는 경우**

```json
{
  "targets": []
}
```

::: warning 주의사항

* **조회할 수 없는 사용자는 응답에서 제외됩니다.** 따라서 요청한 회원번호 개수와 `targets` 길이가 다를 수 있고, 하나도 조회되지 않으면 빈 배열이 옵니다.
* **응답을 요청 목록의 인덱스(순번)와 1:1로 가정하면 어긋납니다.** 결과를 매칭할 때는 순번이 아니라 각 항목의 `user_id` 값을 키로 매핑해야 합니다.
* 닉네임을 얻지 못한 사용자를 위해 게임 자체의 대체 표기(예: `user138531`)를 준비해 두는 것을 권장합니다.
  :::

## 에러

응답 코드와 에러 코드는 카카오 API 공통 규격을 따릅니다. 상세는 [에러 코드](https://developers.kakao.com/docs/ko/rest-api/error-code#common)를 참고하세요.

## 참고 문서

* 게임플레이 파트너센터: 게임 정보 관리
* [액션데이터 API](/api-sdk/data/action-data): 사용자별 실제 랭킹 기록값 전송
* [카카오싱크 설정](/docs/authentication/kakao-login-sync): 회원번호 확보를 위한 인증·동의 설정
* 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)