페이지 이동경로
  • 문서>
  • 카카오모먼트>
  • 오디언스 관리

카카오모먼트

오디언스 관리

이 문서는 카카오모먼트 오디언스 관리 API 사용 방법을 안내합니다.

오디언스 목록 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/targetings/audiences 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

오디언스 관리의 오디언스 목록을 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O

응답

본문
이름 타입 설명
content Audience[] 오디언스 목록
Audience
이름 타입 설명
id Long 오디언스 번호
name String 오디언스명
audienceStatus String 오디언스 상태
STANDBY(준비중), AVAILABLE(사용가능) SEED_NOT_ENOUGH(모수 부족), ERROR(사용불가) 중 하나
type String 오디언스 유형
DISPLAY, MESSAGE 중 하나
createdDate String 오디언스 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 오디언스 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/audiences" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "content": [
    {
      "id": 1,
      "name": "첫번째_오디언스",
      "audienceStatus": "AVAILABLE",
      "type": "DISPLAY",
      "createdDate": "2021-05-03T18:50:54",
      "lastModifiedDate": "2021-05-03T18:50:54"
    },
    {
      "id": 2,
      "name": "두번째_오디언스",
      "audienceStatus": "AVAILABLE",
      "type": "MESSAGE",
      "createdDate": "2021-04-21T14:36:07",
      "lastModifiedDate": "2021-04-21T14:43:23"
    },
    {
      "id": 3,
      "name": "세번째_오디언스",
      "audienceStatus": "SEED_NOT_ENOUGH",
      "type": "DISPLAY",
      "createdDate": "2021-04-21T14:35:32",
      "lastModifiedDate": "2021-04-21T14:35:42"
    }
  ]
}

오디언스 상세 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/targetings/${ID} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

오디언스 관리의 오디언스 단건을 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 오디언스 번호 O

응답

본문
이름 타입 설명
id Long 오디언스 번호
name String 오디언스명
type String 오디언스 유형
DISPLAY, MESSAGE 중 하나
audienceStatus String 오디언스 상태
STANDBY(준비중), AVAILABLE(사용가능) SEED_NOT_ENOUGH(모수 부족), ERROR(사용불가) 중 하나
populationScore Long 예상 모수
오디언스의 예상 모수
createdDate String 오디언스 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 오디언스 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식
ageType String 연령대 전체 선택 종류
ALL(전체), NOT_ALL(부분 선택) 중 하나
ages Set of String 연령대
genderType String 성별 전체 선택 종류
ALL(전체), NOT_ALL(부분 선택) 중 하나
genders Set of String 성별
F(여성), M(남성)
locations Set of Location 데모그래픽 > 행정구역 > 시/도
시/도 보기 참고
depth2Locations Set of Location 데모그래픽 > 행정구역 > 시/군/구
시/군/구 보기 참고
depth3Locations Set of Depth3Location 데모그래픽 > 행정구역 > 동/읍/면
동/읍/면 보기 참고
ufoInterests EnumSet of UfoInterest 관심사 타게팅
맞춤타겟 카테고리 타입 보기 참고
ufoBusinessTypes EnumSet of UfoBusinessType 업종 타게팅
맞춤타겟 카테고리 타입 보기 참고
talkChannelTargetings Set of TalkChannelTargeting 카카오톡 채널 타게팅
syncAppTargetings Set of SyncAppTargeting 카카오 로그인 이용자 타게팅
customerFileTargetings Set of CustomerFileTargeting 고객파일 타게팅
cohortTargetings Set of CohortTargeting 광고반응 타게팅
trackerTargetings Set of TrackerTargeting 픽셀&SDK 타게팅
talkChannelGroupTargetings Set of TalkChannelGroupTargeting 친구그룹 타게팅

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "id": 1,
  "type": "DISPLAY",
  "audienceStatus": "AVAILABLE",
  "name": "첫번째_오디언스",
  "ageType": "ALL",
  "genders": [
    "F",
    "M"
  ],
  "genderType": "NOT_ALL",
  "locations": [
    {
      "value": "E",
      "description": "광주광역시",
      "depth1Name": "광주광역시"
    },
    {
      "value": "O",
      "description": "충청남도",
      "depth1Name": "충청남도"
    },
    {
      "value": "L",
      "description": "전라남도",
      "depth1Name": "전라남도"
    },
    {
      "value": "M",
      "description": "전라북도",
      "depth1Name": "전라북도"
    },
    {
      "value": "A",
      "description": "강원도",
      "depth1Name": "강원도"
    },
    {
      "value": "K",
      "description": "인천광역시",
      "depth1Name": "인천광역시"
    },
    {
      "value": "I",
      "description": "서울특별시",
      "depth1Name": "서울특별시"
    },
    {
      "value": "P",
      "description": "충청북도",
      "depth1Name": "충청북도"
    },
    {
      "value": "F",
      "description": "대구광역시",
      "depth1Name": "대구광역시"
    },
    {
      "value": "Q",
      "description": "세종특별자치시",
      "depth1Name": "세종특별자치시"
    },
    {
      "value": "N",
      "description": "제주특별자치도",
      "depth1Name": "제주특별자치도"
    },
    {
      "value": "G",
      "description": "대전광역시",
      "depth1Name": "대전광역시"
    },
    {
      "value": "H",
      "description": "부산광역시",
      "depth1Name": "부산광역시"
    },
    {
      "value": "D",
      "description": "경상북도",
      "depth1Name": "경상북도"
    },
    {
      "value": "U",
      "description": "알수없음",
      "depth1Name": "알수없음"
    },
    {
      "value": "J",
      "description": "울산광역시",
      "depth1Name": "울산광역시"
    },
    {
      "value": "B",
      "description": "경기도",
      "depth1Name": "경기도"
    },
    {
      "value": "C",
      "description": "경상남도",
      "depth1Name": "경상남도"
    }
  ],
  "populationScore": 10000,
  "createdDate": "2021-04-14T17:49:35",
  "lastModifiedDate": "2021-04-14T17:49:35"
}

오디언스 생성하기

기본 정보
메서드 URL 인증 방식
POST https://apis.moment.kakao.com/openapi/v4/targetings 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

광고 그룹 생성 및 수정 시 사용할 오디언스를 생성합니다.

사용자 비즈니스 토큰을 헤더에 담아 POST로 요청합니다. 요청 시 타게팅에 사용할 각 정보들을 입력하여 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

오디언스 유형별 설정 가능 파라미터

유형 DISPLAY MESSAGE
ufoInterests(관심사) O O
ufoBusinessTypes(카테고리) O O
locations(시/도) O O
depth2Locations(시/군/구) O O
depth3Locations(동/읍/면) O O
talkChannelGroupTargetings(친구그룹) X O
customerFileTargetings(고객파일) O X
trackerTargetings(픽셀&SDK) O X
cohortTargetings(광고반응타겟) O O
talkChannelTargetings(카카오톡채널) O O
syncAppTargetings(카카오 로그인 이용자) O O

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 Parameter
adAccountId Long 해당 오디언스가 소속되는 광고계정 ID O
name String 오디언스의 이름 O
type String 오디언스 유형
DISPLAY, MESSAGE 중 하나		 O
ageType String 연령대 전체 선택 종류
ALL (전체 선택), NOT_ALL (부분 선택) 중 하나		 O
ages String[] 연령대
15 (15 ~ 19)
20 (20 ~ 24)
25 (25 ~ 29)
30 (30 ~ 34)
35 (35 ~ 39)
40 (40 ~ 44)
45 (45 ~ 49)
50 (50 ~ 54)
55 (55 ~ 59)
60 (60 ~ 64)
65 (65 ~ 69)
ageType(연령대 전체 선택 종류)이 ALL 인 경우 ages는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함
성인 타게팅 여부(true) 허용으로 설정할 경우 "20","25","30","35","40","45","50","55","60","65" 을 배열에 담아 요청해야 함.		 O*
genderType String 성별 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나		 O
genders String[] 성별
M : 남자
F : 여자
* genderType(성별 전체 선택 종류)이 ALL 인 경우 genders는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함		 O*
ufoInterests Set of UfoInterest 맞춤 타겟 > 카카오 데이터 > 카테고리 > 관심사
맞춤타겟 카테고리 타입 보기 참고		 X
ufoBusinessTypes Set of UfoBusinessType 맞춤 타겟 > 카카오 데이터 > 카테고리 > 업종
맞춤타겟 카테고리 타입 보기 참고		 X
locationType String 지역선택 타입
ALL (전체선택), AREA (지역선택) 중 하나		 O
locations Set of Location 데모그래픽 > 행정구역 > 시/도
시/도 보기 참고
locationType(ALL)으로 요청된 경우 해당 필드는 요청할 수 없음
캠페인 유형이 카카오 비즈보드인 경우 해외(Z)는 요청할 수 없음
locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 함께 요청 가능		 X
depth2Locations Set of Depth2Location 데모그래픽 > 행정구역 > 시/군/구
시/군/구 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야함. 행정구역 타게팅 세 가지 함께 요청 가능		 X
depth3Locations Set of Depth3Location 데모그래픽 > 행정구역 > 동/읍/면
동/읍/면 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야 함
행정구역 타게팅 세 가지 함께 요청 가능		 X
customerFileTargetings Set of CustomerFileTargeting 맞춤타겟 > 내 데이터 > 고객파일
타게팅 가능한 고객파일 목록 보기를 통해 조회되는 정보를 활용		 X
trackerTargetings Set of TrackerTargeting 맞춤타겟 > 내 데이터 > 픽셀 & SDK
타게팅 가능한 픽셀 & SDK 이벤트 목록 보기를 통해 조회되는 정보를 활용		 X
cohortTargetings Set of CohortTargeting 맞춤타겟 > 내 데이터 > 광고반응타겟
타게팅 가능한 광고반응타겟 보기를 통해 조회되는 정보를 활용		 X
talkChannelTargetings Set of TalkChannelTargeting 맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구
타게팅 가능한 카카오톡 채널 정보 목록 보기를 통해 조회되는 정보를 활용		 X
syncAppTargetings Set of SyncAppTargeting 맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자
타게팅 가능한 카카오 로그인 이용자 목록 보기를 통해 조회되는 정보를 활용		 X
talkChannelGroupTargetings Set of TalkChannelGroupTargeting 맞춤타겟 > 내 데이터 > 친구그룹
타게팅 가능한 친구그룹 목록 보기를 통해 조회되는 정보를 활용
비고: 카카오톡 채널 X 도달 캠페인에서만 사용 가능		 X

응답

본문
이름 타입 설명
id Long 오디언스 번호
name String 오디언스명
type String 오디언스 유형
DISPLAY, MESSAGE 중 하나
adAccountId Long 광고계정 ID
audienceStatus String 오디언스 상태
STANDBY(준비중), AVAILABLE(사용가능) SEED_NOT_ENOUGH(모수 부족), ERROR(사용불가) 중 하나
populationScore Long 예상 모수
오디언스의 예상 모수
createdDate String 오디언스 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 오디언스 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식
ageType String 연령대 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나
ages Set of String 연령대
genderType String 성별 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나
genders Set of String 성별
locations Set of Location 시/도
시/도 보기 참고
depth2Locations Set of Depth2Location 시/군/구
시/군/구 보기 참고
depth3Locations Set of Location 데모그래픽 > 행정구역 > 동/읍/면
동/읍/면 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야 함
행정구역 타게팅 세 가지 함께 요청 가능
ufoInterests EnumSet of UfoInterest 관심사 타게팅
맞춤타겟 카테고리 타입 보기 참고
ufoBusinessTypes EnumSet of UfoBusinessType 업종 타게팅
맞춤타겟 카테고리 타입 보기 참고
talkChannelTargetings Set of TalkChannelTargeting 카카오톡 채널 타게팅
syncAppTargetings Set of SyncAppTargeting 카카오 로그인 이용자 타게팅
customerFileTargetings Set of CustomerFileTargeting 고객파일 타게팅
cohortTargetings Set of CohortTargeting 광고반응 타게팅
trackerTargetings Set of TrackerTargeting 픽셀&SDK 타게팅
talkChannelGroupTargetings Set of TalkChannelGroupTargeting 친구그룹 타겟팅

예제

요청
curl -X POST "https://apis.moment.kakao.com/openapi/v4/targetings" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
    "adAccountId": 1,
    "name": "오픈API생성",
    "type": "DISPLAY",
    "ageType": "NOT_ALL",
    "ages": ["20", "15"],
    "genderType": "NOT_ALL",
    "genders": ["M"],
    "locationType": "AREA",
    "locations": [
            {
                "value": "E",
                "description": "광주광역시",
                "depth1Name": "광주광역시"
            },
            {
                "value": "O",
                "description": "충청남도",
                "depth1Name": "충청남도"
            }
        ],
        "depth2locations" : [
            {
                "value" : "B7222",
                "desrciption" : "경기도 여주시",
                "depth1Name": "경기도",
                "depth2Name": "여주시"
            },
            {
                "value" : "I1009",
                "desrciption" : "서울특별시 도봉구",
                "depth1Name": "광주광역시",
                "depth2Name": "도봉구"
            }
        ],
        "depth3Locations" : [
            {
                "value" : "A70052424",
                "desrciption" : "강원도 삼척시 원덕읍",
                "depth1Name": "강원도",
                "depth2Name": "삼척시",
                "depth3Name": "원덕읍"
            },
            {
                "value" : "E13010702",
                "desrciption" : "광주광역시 남구 백운2동",
                "depth1Name": "광주광역시",
                "depth2Name": "남구",
                "depth3Name": "백운2동"
            }
        ]
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1,
    "type": "DISPLAY",
    "adAccountId": 1,
    "name": "오픈API생성",
    "ageType": "NOT_ALL",
    "ages": [
        "15",
        "20"
    ],
    "genders": [
        "M"
    ],
    "genderType": "NOT_ALL",       "locations": [
            {
                "value": "E",
                "description": "광주광역시",
                "depth1Name": "광주광역시"
            },
            {
                "value": "O",
                "description": "충청남도",
                "depth1Name": "충청남도"
            }
        ],
        "depth2locations" : [
            {
                "value" : "B7222",
                "desrciption" : "경기도 여주시",
                "depth1Name": "경기도",
                "depth2Name": "여주시"
            },
            {
                "value" : "I1009",
                "desrciption" : "서울특별시 도봉구",
                "depth1Name": "광주광역시",
                "depth2Name": "도봉구"
            }
        ],
        "depth3Locations" : [
            {
                "value" : "A70052424",
                "desrciption" : "강원도 삼척시 원덕읍",
                "depth1Name": "강원도",
                "depth2Name": "삼척시",
                "depth3Name": "원덕읍"
            },
            {
                "value" : "E13010702",
                "desrciption" : "광주광역시 남구 백운2동",
                "depth1Name": "광주광역시",
                "depth2Name": "남구",
                "depth3Name": "백운2동"
            }
                 
        ]
 }

오디언스 수정하기

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/targetings 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

오디언스를 수정합니다.

사용자 비즈니스 토큰을 헤더에 담아 PUT으로 요청합니다. 요청 시 타게팅에 사용할 각 정보들을 입력하여 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
id Long 해당 오디언스의 ID O
type String 오디언스 유형
DISPLAY, MESSAGE 중 하나		 O
adAccountId Long 해당 오디언스가 소속되는 광고계정 ID O
name String 오디언스의 이름 O
ageType String 연령대 전체 선택 종류
ALL (전체 선택), NOT_ALL (부분 선택) 중 하나
adult(성인 타게팅 여부)가 true인 경우 해당 필드는 NOT_ALL로만 요청 가능		 O
ages String[] 연령대
15 (15 ~ 19)
20 (20 ~ 24)
25 (25 ~ 29)
30 (30 ~ 34)
35 (35 ~ 39)
40 (40 ~ 44)
45 (45 ~ 49)
50 (50 ~ 54)
55 (55 ~ 59)
60 (60 ~ 64)
65 (65 ~ 69)
ageType(연령대 전체 선택 종류)이 ALL 인 경우 ages는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함
성인 타게팅 여부(true) 허용으로 설정할 경우 "20","25","30","35","40","45","50","55","60","65" 을 배열에 담아 요청해야 함.		 O*
genderType String 성별 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나		 O
genders String[] 성별
M : 남자
F : 여자
* genderType(성별 전체 선택 종류)이 ALL 인 경우 genders는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함		 O*
ufoInterests Set of UfoInterest 맞춤 타겟 > 카카오 데이터 > 카테고리 > 관심사
맞춤타겟 카테고리 타입 보기 참고		 X
ufoBusinessTypes Set of UfoBusinessType 맞춤 타겟 > 카카오 데이터 > 카테고리 > 업종
맞춤타겟 카테고리 타입 보기 참고		 X
locationType String 지역선택 타입
ALL (전체선택), AREA (지역선택) 중 하나		 O
locations Set of Location 데모그래픽 > 행정구역 > 시/도
시/도 보기 참고
locationType(ALL)으로 요청된 경우 해당 필드는 요청할 수 없음
캠페인 유형이 카카오 비즈보드인 경우 해외(Z)는 요청할 수 없음
locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 함께 요청 가능		 X
depth2Locations Set of Depth2Location 데모그래픽 > 행정구역 > 시/군/구
시/군/구 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야함. 행정구역 타게팅 세 가지 함께 요청 가능		 X
depth3Locations Set of Depth3Location 데모그래픽 > 행정구역 > 동/읍/면
동/읍/면 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야 함
행정구역 타게팅 세 가지 함께 요청 가능		 X
customerFileTargetings Set of CustomerFileTargeting 맞춤타겟 > 내 데이터 > 고객파일
타게팅 가능한 고객파일 목록 보기를 통해 조회되는 정보를 활용		 X
trackerTargetings Set of TrackerTargeting 맞춤타겟 > 내 데이터 > 픽셀 & SDK
타게팅 가능한 픽셀 & SDK 이벤트 목록 보기를 통해 조회되는 정보를 활용		 X
cohortTargetings Set of CohortTargeting 맞춤타겟 > 내 데이터 > 광고반응타겟
타게팅 가능한 광고반응타겟 보기를 통해 조회되는 정보를 활용		 X
talkChannelTargetings Set of TalkChannelTargeting 맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구
타게팅 가능한 카카오톡 채널 정보 목록 보기를 통해 조회되는 정보를 활용		 X
syncAppTargetings Set of SyncAppTargeting 맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자
타게팅 가능한 카카오 로그인 이용자 목록 보기를 통해 조회되는 정보를 활용		 X
talkChannelGroupTargetings Set of TalkChannelGroupTargeting 맞춤타겟 > 내 데이터 > 친구그룹
타게팅 가능한 친구그룹 목록 보기를 통해 조회되는 정보를 활용
비고: 카카오톡 채널 X 도달 캠페인에서만 사용 가능		 X

응답

본문
이름 타입 설명
id Long 오디언스 번호
name String 오디언스명
type String 오디언스 유형
DISPLAY, MESSAGE 중 하나
adAccountId Long 광고계정 ID
audienceStatus String 오디언스 상태
STANDBY(준비중), AVAILABLE(사용가능) SEED_NOT_ENOUGH(모수 부족), ERROR(사용불가) 중 하나
populationScore Long 예상 모수
오디언스의 예상 모수
createdDate String 오디언스 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 오디언스 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식
ageType String 연령대 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나
ages Set of String 연령대
genderType String 성별 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나
genders Set of String 성별
locations Set of Location 시/도
시/도 보기 참고
depth2Locations Set of Depth2Location 시/군/구
시/군/구 보기 참고
depth3Locations Set of Location 데모그래픽 > 행정구역 > 동/읍/면
동/읍/면 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야 함
행정구역 타게팅 세 가지 함께 요청 가능
ufoInterests EnumSet of UfoInterest 관심사 타게팅
맞춤타겟 카테고리 타입 보기 참고
ufoBusinessTypes EnumSet of UfoBusinessType 업종 타게팅
맞춤타겟 카테고리 타입 보기 참고
talkChannelTargetings Set of TalkChannelTargeting 카카오톡 채널 타게팅
syncAppTargetings Set of SyncAppTargeting 카카오 로그인 이용자 타게팅
customerFileTargetings Set of CustomerFileTargeting 고객파일 타게팅
cohortTargetings Set of CohortTargeting 광고반응 타게팅
trackerTargetings Set of TrackerTargeting 픽셀&SDK 타게팅
talkChannelGroupTargetings Set of TalkChannelGroupTargeting 친구그룹 타겟팅

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/targetings" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
    "adAccountId": 1,
    "name": "오픈API생성",
    "type": "DISPLAY",
    "ageType": "NOT_ALL",
    "ages": ["20", "15"],
    "genderType": "NOT_ALL",
    "genders": ["M"],
    "locationType": "ALL",
    "locations": [
        {
            "value": "A",
            "description": "강원도",
            "depth1Name": "강원도"
        },
        {
            "value": "B",
            "description": "경기도",
            "depth1Name": "경기도"
        },
        {
            "value": "C",
            "description": "경상남도",
            "depth1Name": "경상남도"
        },
        {
            "value": "D",
            "description": "경상북도",
            "depth1Name": "경상북도"
        },
        {
            "value": "E",
            "description": "광주광역시",
            "depth1Name": "광주광역시"
        },
        {
            "value": "F",
            "description": "대구광역시",
            "depth1Name": "대구광역시"
        },
        {
            "value": "G",
            "description": "대전광역시",
            "depth1Name": "대전광역시"
        },
        {
            "value": "H",
            "description": "부산광역시",
            "depth1Name": "부산광역시"
        },
        {
            "value": "I",
            "description": "서울특별시",
            "depth1Name": "서울특별시"
        },
        {
            "value": "J",
            "description": "울산광역시",
            "depth1Name": "울산광역시"
        },
        {
            "value": "K",
            "description": "인천광역시",
            "depth1Name": "인천광역시"
        },
        {
            "value": "L",
            "description": "전라남도",
            "depth1Name": "전라남도"
        },
        {
            "value": "M",
            "description": "전라북도",
            "depth1Name": "전라북도"
        },
        {
            "value": "N",
            "description": "제주특별자치도",
            "depth1Name": "제주특별자치도"
        },
        {
            "value": "O",
            "description": "충청남도",
            "depth1Name": "충청남도"
        },
        {
            "value": "P",
            "description": "충청북도",
            "depth1Name": "충청북도"
        },
        {
            "value": "Q",
            "description": "세종특별자치시",
            "depth1Name": "세종특별자치시"
        },
        {
            "value": "U",
            "description": "알수없음",
            "depth1Name": "알수없음"
        }
    ]
}'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1,
    "type": "DISPLAY",
    "adAccountId": 1,
    "name": "오픈API생성",
    "ageType": "NOT_ALL",
    "ages": [
        "15",
        "20"
    ],
    "genders": [
        "M"
    ],
    "genderType": "NOT_ALL",
    "locations": [
        {
            "value": "E",
            "description": "광주광역시",
            "depth1Name": "광주광역시"
        },
        {
            "value": "O",
            "description": "충청남도",
            "depth1Name": "충청남도"
        },
        {
            "value": "L",
            "description": "전라남도",
            "depth1Name": "전라남도"
        },
        {
            "value": "M",
            "description": "전라북도",
            "depth1Name": "전라북도"
        },
        {
            "value": "A",
            "description": "강원도",
            "depth1Name": "강원도"
        },
        {
            "value": "K",
            "description": "인천광역시",
            "depth1Name": "인천광역시"
        },
        {
            "value": "I",
            "description": "서울특별시",
            "depth1Name": "서울특별시"
        },
        {
            "value": "P",
            "description": "충청북도",
            "depth1Name": "충청북도"
        },
        {
            "value": "F",
            "description": "대구광역시",
            "depth1Name": "대구광역시"
        },
        {
            "value": "Q",
            "description": "세종특별자치시",
            "depth1Name": "세종특별자치시"
        },
        {
            "value": "N",
            "description": "제주특별자치도",
            "depth1Name": "제주특별자치도"
        },
        {
            "value": "G",
            "description": "대전광역시",
            "depth1Name": "대전광역시"
        },
        {
            "value": "H",
            "description": "부산광역시",
            "depth1Name": "부산광역시"
        },
        {
            "value": "D",
            "description": "경상북도",
            "depth1Name": "경상북도"
        },
        {
            "value": "U",
            "description": "알수없음",
            "depth1Name": "알수없음"
        },
        {
            "value": "J",
            "description": "울산광역시",
            "depth1Name": "울산광역시"
        },
        {
            "value": "B",
            "description": "경기도",
            "depth1Name": "경기도"
        },
        {
            "value": "C",
            "description": "경상남도",
            "depth1Name": "경상남도"
        }
    ]
}

오디언스 삭제하기

기본 정보
메서드 URL 인증 방식
DELETE https://apis.moment.kakao.com/openapi/v4/targetings/${ID} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

오디언스를 삭제합니다.

사용자 비즈니스 토큰을 헤더에 담아 DELETE로 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 오디언스 ID O

예제

요청
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/targetings/${ID}" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8

오디언스 여러 개 삭제하기

기본 정보
메서드 URL 인증 방식
DELETE https://apis.moment.kakao.com/openapi/v4/targetings 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

복수의 오디언스를 한 번에 삭제합니다.

사용자 비즈니스 토큰을 헤더에 담아 DELETE로 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
쿼리 파라미터
이름 타입 설명 필수
audienceIds String 오디언스 ID
여러 개의 오디언스 ID를 쉼표(,)로 구분한 하나의 문자열로 전달		 O

예제

요청
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/targetings?audienceIds=${AUDIENCE_ID},${AUDIENCE_ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "successCount": 1,
    "failCount": 1,
    "errorMessages": [
        "타겟을 사용 중인 오디언스가 있습니다."
    ]
}

오디언스 사용 현황 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/targetings/${ID}/adGroups 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

오디언스 관리의 오디언스를 사용하고 있는 광고그룹들을 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 오디언스 번호 O

응답

본문
이름 타입 설명
content AudienceAdGroup[] 오디언스를 사용하고 있는 광고그룹 목록
AudienceAdGroup
이름 타입 설명
campaignId Long 캠페인 번호
campaignName String 캠페인명
campaignTypeGoal CampaignTypeGoal 캠페인 유형 X 목표
adGroupId Long 광고그룹 번호
adGroupName String 광고그룹명
adGroupStatus Status[] 광고그룹 상태
adGroupType String 광고그룹 종류
DISPLAY(디스플레이), DIRECT_MESSAGE(메시지) 중 하나

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/${ID}/adGroups" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "content": [
    {
      "campaignId": 1,
      "campaignName": "첫번째_캠페인",
      "campaignTypeGoal": {
        "campaignType": "TALK_BIZ_BOARD",
        "goal": "VISITING"
      },
      "adGroupId": 1,
      "adGroupName": "첫번째_광고그룹",
      "adGroupStatus": [
        "OFF"
      ],
      "adGroupType": "DISPLAY"
    },
    {
      "campaignId": 1,
      "campaignName": "첫번째_캠페인",
      "campaignTypeGoal": {
        "campaignType": "TALK_BIZ_BOARD",
        "goal": "VISITING"
      },
      "adGroupId": 2,
      "adGroupName": "두번째_광고그룹",
      "adGroupStatus": [
        "OFF"
      ],
      "adGroupType": "DISPLAY"
    },
    {
      "campaignId": 2,
      "campaignName": "두번째_캠페인",
      "campaignTypeGoal": {
        "campaignType": "TALK_BIZ_BOARD",
        "goal": "VISITING"
      },
      "adGroupId": 3,
      "adGroupName": "세번째_광고그룹",
      "adGroupStatus": [
        "OFF"
      ],
      "adGroupType": "DISPLAY"
    }
  ]
}

오디언스 사용 해제하기

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/targetings/${ID}/unlink 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

오디언스 관리의 오디언스를 사용하고 있는 광고그룹을 사용 해제합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 오디언스 번호 O
본문
이름 타입 설명 필수
adGroupId Long 광고그룹 번호 O

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/${ID}/unlink?adGroupId=${AD_GROUP_ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK

더 보기

카카오모먼트> 오디언스 관리