카카오모먼트

오디언스 관리

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

오디언스 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/targetings/audiences`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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}`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	관심사 타게팅 맞춤타겟 카테고리 타입 조회 참고
ufoDeprecatedInterests	`EnumSet of UfoInterest`	지원 중단된 관심사 타게팅 맞춤타겟 카테고리 타입 조회 참고
ufoBusinessTypes	`EnumSet of UfoBusinessType`	업종 타게팅 맞춤타겟 카테고리 타입 조회 참고
ufoDeprecatedBusinessTypes	`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": "M55550301",
        "description": "전북특별자치도 전주시 덕진구 금암1동",
        "depth1Name": "전북특별자치도",
        "depth2Name": "전주시 덕진구",
        "depth3Name": "금암1동",
        "deprecated": true
     },
    {
        "value": "M55550302",
        "description": "전북특별자치도 전주시 덕진구 금암2동",
        "depth1Name": "전북특별자치도",
        "depth2Name": "전주시 덕진구",
        "depth3Name": "금암2동",
        "deprecated": true
    }
    ],
    "ufoInterests": [
        "I0202",
        "I020601",
        "I03",
        "I320104"
    ],
    "ufoDeprecatedInterests": [
        "I320104"
    ],
    "ufoBusinessTypes": [
        "P1021",
        "P2003"
    ],
    "ufoDeprecatedBusinessTypes": [
        "P2003"
    ],
    "populationScore": 100,
    "createdDate": "2021-04-14T17:49:35",
    "lastModifiedDate": "2021-04-14T17:49:35"
}

오디언스 생성

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/v4/targetings`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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}`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

오디언스를 삭제합니다.

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

요청

헤더

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

경로 변수

이름	타입	설명	필수
ID	`Long`	오디언스 ID	O

예제

요청

curl -v -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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

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

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

요청

헤더

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

쿼리 파라미터

이름	타입	설명	필수
audienceIds	`String`	오디언스 ID 여러 개의 오디언스 ID를 쉼표(,)로 구분한 하나의 문자열로 전달	O

예제

요청

curl -v -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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

오디언스 관리

오디언스 목록 조회

기본 정보

요청

헤더

응답

본문

Audience

예제

요청

응답

오디언스 상세 조회

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

오디언스 생성

기본 정보

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

요청

헤더

본문

응답

본문

예제

요청

응답

오디언스 수정

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

오디언스 삭제

기본 정보

요청

헤더

경로 변수

예제

요청

응답

오디언스 여러 개 삭제

기본 정보

요청

헤더

쿼리 파라미터

예제

요청

응답

오디언스 사용 현황 조회

기본 정보

요청

헤더

경로 변수

응답

본문

AudienceAdGroup

예제

요청

응답

오디언스 사용 해제