카카오모먼트

광고반응타겟 관리

이 문서는 광고반응타겟 관리 API 사용법을 안내합니다.

광고반응타겟 안내

광고반응타겟은 광고그룹 생성 및 수정 시 타게팅 정보로 활용할 수 있습니다. 광고에서 발생한 클릭, 재생, 전환 등의 반응 데이터를 조합하여 만들 수 있는 타게팅 정보입니다.

카카오모먼트 광고는 캠페인의 목표와 유형에 따라 다양한 광고 반응 데이터를 제공합니다. 사용자 선택에 따라 다양한 광고반응 데이터를 설정하여 광고반응타겟을 만들 수 있으며, 캠페인의 유형에 따라 선택할 수 있는 광고반응 데이터의 종류가 달라질 수 있습니다.

광고반응타겟 유형별 정책

광고반응타켓은 어떤 광고 유형(DISPLAY, MESSAGE)에 사용할 것인지를 고려하여 생성합니다. 광고 유형에 따라 광고반응타겟 생성에 사용할 수 있는 캠페인 유형 및 광고 반응 데이터 항목이 다릅니다. 자세한 내용은 아래 표를 참고합니다.

광고 유형: DISPLAY

생성 가능 캠페인 유형	사용 가능 광고 반응 데이터
카카오 비즈보드 카카오 비즈보드 CPT 디스플레이 동영상 포커스 보드 포커스 풀뷰 프로필 풀뷰	클릭, 전환, 재생
다음쇼핑 상품 카탈로그 리치팝 올데이	클릭, 전환
카카오톡 채널 개인화 메시지	전환

광고 유형: MESSAGE

생성 가능 캠페인 유형	사용 가능 광고 반응 데이터
카카오톡 채널 개인화 메시지	클릭, 재생, 열람

광고 반응 데이터 정의

광고 유형별 사용 가능한 광고 반응 지표의 정의가 상이합니다.

구분	클릭	재생	전환	열람
DISPLAY	광고의 클릭 영역 중에서 1곳이라도 클릭한 사용자	동영상을 3초 이상 또는 25% 이상 재생한 사용자(클릭 혹은 전환까지 한 사용자가 포함될 수 있음)	카카오 픽셀 & SDK로 전환이 수집된 사용자 광고로 카카오톡 채널을 추가한 사용자 광고 목표가 카카오톡 채널인 경우 애드뷰 랜딩 시 채널 추가하기 버튼 사용한 경우	-
MESSAGE	열람한 메시지의 클릭 영역 중에서 1곳이라도 클릭한 사용자	열람한 메시지의 동영상을 3초 이상 재생한 사용자(클릭한 사용자가 포함될 수 있음)	-	카카오톡 채널과의 채팅방을 열어서 메시지를 읽음 처리한 사용자

광고 반응 데이터 설정 가능 연산

광고 반응 데이터는 아래와 같은 연산으로 사용 가능합니다.

광고 반응 데이터	연산
클릭(전체)	operation: ONLY firstIndicator: CLICK
재생(전체)	operation: ONLY firstIndicator: PLAY
전환(전체)	operation: ONLY firstIndicator: CONVERSION
열람(전체)	operation: ONLY firstIndicator: OPEN
클릭-재생	operation: MINUS firstIndicator: CLICK secondIndicator: PLAY
재생-클릭	operation: MINUS firstIndicator: PLAY secondIndicator: CLICK
클릭-전환	operation: MINUS firstIndicator: CLICK secondIndicator: CONVERSION
열람-클릭-재생	operation: MINUS firstIndicator: OPEN secondIndicator: CLICK thirdIndicator: PLAY
클릭&재생	operation: AND firstIndicator: PLAY secondIndicator: CLICK

광고반응타겟 목록 조회

기본 정보

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

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

광고그룹 생성 및 수정 시 타게팅 정보로 활용 가능한 광고반응타겟 목록을 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 성공 시 응답 본문에 JSON 객체로 광고반응타겟의 목록을 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더

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

응답

본문

이름	타입	설명
-	`CohortTarget[]`	타게팅 정보로 활용 가능한 광고반응타겟 목록

CohortTarget

이름	타입	설명
id	`Long`	광고반응타겟 번호
audienceType	`String`	광고반응 타겟 유형, 아래 중 하나 `DISPLAY`: 디스플레이 `MESSAGE`: 메시지
name	`String`	광고반응타겟 이름
baseAds	`BaseAd[]`	광고반응 데이터 목록
collectDuration	`Integer`	수집 기간 오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함 단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
cohortStatus	`String`	타겟 모수 상태, 아래 중 하나 `WAITING`: 준비 중 `AVAILABLE_ERROR`: 모출 추출 에러 `AVAILABLE`: 모수 추출 완료 `MODIFYING`: 수정 중 `DELETE`: 삭제 또는 삭제중 `ERROR`: 그 외 에러
popultaionScore	`Long`	타겟 모수 타겟 모수 상태가 `AVAILABLE` 인 경우 정상 추출된 모수 선택한 광고에 반응한 카카오 사용자 추정 도달수로 광고반응타겟 생성 요청 후 1시간 이내 모수 추출이 완료되며 모수는 실시간 갱신됨 준비중 상태인 타겟은 모수 추출 전 단계로 타게팅에 사용 불가능
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/cohort/list" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "adAccountId": 1234,
        "id": 1,
        "audienceType": "MESSAGE",
        "name": "첫번째_광고반응타겟",
        "baseAds": [
            {
                "campaign": {
                    "id": 5678,
                    "name": "첫번째_캠페인",
                    "campaignTypeGoal": {
                        "campaignType": "TALK_CHANNEL",
                        "goal": "REACH"
                    }
                },
                "adGroup": {
                    "id": 20425,
                    "name": "첫번째_광고그룹"
                },
                "operation": "ONLY",
                "firstIndicator": "OPEN"
            }
        ],
        "collectDuration": 90,
        "cohortStatus": "AVAILABLE",
        "createdDate": "2020-01-01 00:00:00",
        "lastModifiedDate": "2020-01-01 00:00:00"
    }
]

광고반응타겟 조회

기본 정보

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

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

지정한 광고반응타겟의 상세 정보를 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 정보를 조회할 광고반응타겟의 번호를 전달해야 합니다. 요청 성공 시 응답은 해당 광고반응타겟의 상세 정보 및 상태를 포함합니다.

요청

헤더

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

경로 변수

이름	타입	설명	필수
ID	`Long`	광고반응타겟 번호	O

응답

본문

이름	타입	설명
id	`Long`	광고반응타겟 번호
audienceType	`String`	광고반응 타겟 유형 광고그룹, 오디언스 생성/수정시 올바르게 매칭하여 사용 `DISPLAY`, `MESSAGE` 중 하나
adAccountId	`Long`	광고계정 번호
name	String	광고반응타겟 이름
baseAds	`BaseAd[]`	광고반응 데이터 목록
collectDuration	`Integer`	수집 기간 오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함 단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
cohortStatus	`String`	타겟 모수 상태, 아래 중 하나 `WAITING`: 준비 중 `AVAILABLE_ERROR`: 모출 추출 에러 `AVAILABLE`: 모수 추출 완료 `MODIFYING`: 수정 중 `DELETE`: 삭제 또는 삭제중 `ERROR`: 그 외 에러
popultaionScore	`Long`	타겟 모수 타겟 모수 상태가 `AVAILABLE` 인 경우 정상 추출된 모수 선택한 광고에 반응한 카카오 사용자 추정 도달수로 광고반응타겟 생성 요청 후 1시간 이내 모수 추출이 완료되며 모수는 실시간 갱신됨 준비중 상태인 타겟은 모수 추출 전 단계로 타게팅에 사용 불가능
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/cohort/${ID}' \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId": 65721,
    "id": 100943,
    "collectDuration": 90,
    "cohortStatus": "WAITING",
    "name": "first_engagement_target",
    "audienceType": "MESSAGE",
    "baseAds": [
        {
            "campaign": {
                "id": 82141,
                "name": "first_campaign",
                "campaignTypeGoal": {
                    "campaignType": "TALK_CHANNEL",
                    "goal": "REACH"
                }
            },
            "adGroup": {
                "id": 101326,
                "name": "first_ad_group"
            },
            "operation": "ONLY",
            "firstIndicator": "OPEN"
        },
        {
            "messageAd": {
                "id": "msg-ad-1336211109228568577"
            },
            "operation": "ONLY",
            "firstIndicator": "OPEN"
        }
    ],
    "populationScore": 0,
    "createdDate": "2025-04-15T13:27:57.603841",
    "lastModifiedDate": "2025-04-15T13:27:57.60384",
    "populationUpdateDate": null
}

광고반응타겟 생성 가능 대상 조회

기본 정보

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

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

광고반응타겟 생성에 필요한 정보인 광고계정 하위의 캠페인 및 광고그룹 정보의 목록을 조회합니다.

광고반응타겟 생성 가능한 캠페인 유형 X 목표의 광고그룹 정보만 조회할 수 있습니다. 생성 가능한 캠페인 유형은 광고반응타겟 유형별 정책에서 확인할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 검색할 캠페인의 유형 X 목표 및 이름을 선택 파라미터로 전달할 수 있습니다. 성공 시 광고그룹 및 캠페인 정보를 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더

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

쿼리 파라미터

이름	타입	설명	필수
campaignType	`CampaignType`	검색할 캠페인 유형	O
goal	`Goal`	검색할 캠페인 목표	O
searchKeyword	`String`	검색할 캠페인 이름	O

응답

본문

이름	타입	설명
-	`AdGroupAndCampaign[]`	광고계정 하위의 캠페인 및 광고그룹 정보의 목록

AdGroupAndCampaign

이름	타입	설명
adGroup	`AdGroup`	광고그룹
campaign	`Campaign`	캠페인

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/cohort/creatables?campaignType=DISPLAY&goal=VISITING&searchKeyword=HG" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -d '{
            "campaignType": "DISPLAY",
            "goal": "VISITING",
            "searchKeyword":"HG"
        }'

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "campaign": {
            "id": 1234,
            "name": "첫번째_캠페인",
            "campaignTypeGoal": {
                "campaignType": "DISPLAY",
                "goal": "VISITING"
            }
        },
        "adGroup": [
            {
                "id": 56,
                "name": "첫번째_광고그룹"
            },
            {
                "id": 78,
                "name": "두번째_광고그룹"
            }
        ]
    }
]

광고반응타겟 생성

기본 정보

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

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

광고반응타겟을 생성합니다.

광고반응타겟은 광고그룹 생성 및 수정 시 타게팅 정보로 활용할 수 있습니다. 광고에서 발생한 클릭, 재생, 반응 데이터를 조합하여 만들 수 있는 타게팅 정보이며 계정당 계정당 50개까지만 등록 가능합니다.

상세한 광고반응타겟 유형별 정책, 캠페인 유형별 정책, 연산 및 반응 종류 정책은 광고반응타겟 안내를 참고합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다. 성공 시 JSON 객체로 생성한 광고반응타겟 정보를 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더

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

본문

이름	타입	설명	필수
audienceType	`String`	광고반응타겟 유형 `DISPLAY`, `MESSAGE` 중 하나	O
name	`String`	광고반응타겟 이름 한글, 영문, 특수문자, 공백을 허용하며 50자를 넘을 수 없음	O
baseAds	`BaseAd[]`	광고반응 데이터	O

BaseAd

이름	타입	설명	필수
adGroup	`AdGroup`	광고그룹	O
campaign	`Campaign`	캠페인	O
operation	`Operation`	연산 종류 연산 및 반응 종류 정책 참조	O
firstIndicator	`Indicator`	첫 번째 반응 종류 연산 및 반응 종류 정책 참조	O
secondIndicator	`Indicator`	두 번째 반응 종류 연산 및 반응 종류 정책 참조	X
thirdIndicator	`Indicator`	세번째 반응 종류 연산 및 반응 종류 정책 참조	X

AdGroup

이름	타입	설명
id	`Long`	광고그룹 번호

Campaign

이름	타입	설명	필수
id	`Long`	캠페인 번호	O

응답

본문

이름	타입	설명
id	`Long`	광고반응타겟 번호
adAccountId	`Long`	광고계정 번호
name	`String`	광고반응타겟 이름
collectDuration	`Integer`	수집 기간 오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함 단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
baseAds	`BaseAd[]`	광고반응 데이터
cohortStatus	`String`	타겟 모수 상태, 아래 중 하나 `WAITING`: 준비 중 `AVAILABLE_ERROR`: 모출 추출 에러 `AVAILABLE`: 모수 추출 완료 `MODIFYING`: 수정 중 `DELETE`: 삭제 또는 삭제중 `ERROR`: 그 외 에러
createdDate	`String`	생성일시 `yyyy-MM-dd'T'HH:mm:ss` 형식
lastModifiedDate	`String`	마지막 수정일시 `yyyy-MM-dd'T'HH:mm:ss` 형식

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/v4/targetings/cohort" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -d '{
            "name": "첫번째_광고반응",
            "audienceType": "MESSAGE",
            "baseAds": [
                {
                    "campaign": {
                        "id": 56,
                        "campaignTypeGoal": {
                            "campaignType": "TALK_CHANNEL"
                        }
                    },
                    "adGroup": {
                        "id": 78
                    },
                    "firstIndicator": "OPEN",
                    "operation": "ONLY"
                }
            ]
        }'

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId": 1234,
    "id": 1,
    "audienceType": "MESSAGE",
    "collectDuration": 90,
    "cohortStatus": "WAITING",
    "name": "첫번째_광고반응",
    "baseAds": [
        {
            "campaign": {
                "id": 56,
                "name": "첫번째_캠페인",
                "campaignTypeGoal": {
                    "campaignType": "TALK_CHANNEL",
                    "goal": "REACH"
                }
            },
            "adGroup": {
                "id": 78,
                "name": "첫번째_광고그룹"
            },
            "operation": "ONLY",
            "firstIndicator": "OPEN"
        }
    ],
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 00:00:00"
}

광고반응타겟 이름 수정

기본 정보

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

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

광고반응타겟의 이름을 수정합니다.

이미 삭제된 광고반응타겟은 수정할 수 없으며, 수정하고자 하는 광고반응타겟 이름이 기존에 존재하는 경우에도 수정이 불가능합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청합니다. 성공 시 수정된 광고반응타겟 정보를 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

이 API는 사용자 계정마다 10초에 한 번씩 요청이 가능하도록 제한되어 있습니다.

요청

헤더

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

본문

이름	타입	설명	필수
id	`Long`	광고반응타겟 번호	O
name	`String`	광고반응타겟 이름 한글, 영문, 특수문자, 공백을 허용하며 50자를 넘을 수 없음	O

응답

본문

이름	타입	설명
adAccountId	`Long`	광고계정 번호
id	`Long`	광고반응타겟 번호
audienceType	`String`	광고반응 타겟 유형 광고그룹, 오디언스 생성/수정시 올바르게 매칭하여 사용 `DISPLAY`, `MESSAGE` 중 하나
name	`String`	광고반응타겟 이름
collectDuration	`Integer`	수집 기간 오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함 단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
baseAds	`BaseAd[]`	광고반응 데이터
cohortStatus	`String`	타겟 모수 상태, 아래 중 하나 `WAITING`: 준비 중 `AVAILABLE_ERROR`: 모출 추출 에러 `AVAILABLE`: 모수 추출 완료 `MODIFYING`: 수정 중 `DELETE`: 삭제 또는 삭제중 `ERROR`: 그 외 에러
createdDate	`String`	생성일시 `yyyy-MM-dd'T'HH:mm:ss` 형식
lastModifiedDate	`String`	마지막 수정일시 `yyyy-MM-dd'T'HH:mm:ss` 형식

예제

요청

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/targetings/cohort/name" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -d '{
            "id": 1,
            "name": "광고반응타겟_이름_수정"
        }'

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId": 1234,
    "id": 1,
    "audienceType": "MESSAGE",
    "collectDuration": 90,
    "cohortStatus": "WAITING",
    "name": "광고반응타겟_이름_수정",
    "baseAds": [
        {
            "campaign": {
                "id": 56,
                "name": "첫번째_캠페인",
                "campaignTypeGoal": {
                    "campaignType": "TALK_CHANNEL",
                    "goal": "REACH"
                }
            },
            "adGroup": {
                "id": 78,
                "name": "첫번째_광고그룹"
            },
            "operation": "ONLY",
            "firstIndicator": "OPEN"
        }
    ],
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 12:00:00"
}

광고반응타겟 데이터 수정

기본 정보

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

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

광고반응타겟의 데이터를 수정합니다.

광고반응타겟 조회 API로 기존 광고반응타겟의 정보를 조회한 후, 수정하고자 하는 필드와 수정을 원치 않는 필드를 조합하여 요청해야 합니다. 수정을 원치 않는 필드도 기존 값으로 요청해야 광고반응타겟의 정보를 유지할 수 있습니다.

타겟을 수정하면 1시간 이내에 수정된 타겟으로 업데이트됩니다. 수정 완료 전까지는 수정 전 타겟 모수로 광고그룹 타겟팅이 작동하며, 수정이 완료되면 수정된 타겟으로 광고그룹 타겟이 변경됩니다. (이 API로는 광고반응타겟 이름은 수정할 수 없습니다)

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청합니다. 성공 시 응답은 수정된 광고반응타겟 정보를 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더

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

본문

이름	타입	설명	필수
id	`Long`	광고반응타겟 번호	O
baseAds	`BaseAd[]`	광고반응	O

BaseAd

이름	타입	설명	필수
adGroup	`Long`	광고그룹	O
campaign	`Long`	캠페인	O
operation	`Operation`	연산 종류 "ONLY","MINUS","AND" 중 하나 연산 및 반응 종류 정책 참조	O
firstIndicator	`Indicator`	첫 번째 반응 종류 "PLAY", "CLICK", "OPEN", CONVERSION" 중 하나 연산 및 반응 종류 정책 참조	O
secondIndicator	`Indicator`	두 번째 반응 종류 "PLAY", "CLICK", "CONVERSION" 중 하나 연산 및 반응 종류 정책 참조	X

응답

본문

이름	타입	설명
id	`Long`	광고반응타겟 번호
audienceType	`String`	광고반응 타겟 유형 광고그룹, 오디언스 생성/수정시 올바르게 매칭하여 사용 `DISPLAY`, `MESSAGE` 중 하나
adAccountId	`Long`	광고계정 번호
name	`String`	광고반응타겟 이름
collectDuration	`Integer`	수집 기간 오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함 단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
baseAds	`BaseAd[]`	광고반응 데이터
cohortStatus	`String`	타겟 모수 상태, 아래 중 하나 `WAITING`: 준비 중 `AVAILABLE_ERROR`: 모출 추출 에러 `AVAILABLE`: 모수 추출 완료 `MODIFYING`: 수정 중 `DELETE`: 삭제 또는 삭제중 `ERROR`: 그 외 에러
createdDate	`String`	생성일시 `yyyy-MM-dd'T'HH:mm:ss` 형식
lastModifiedDate	`String`	마지막 수정일시 `yyyy-MM-dd'T'HH:mm:ss` 형식

예제

요청

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/targetings/cohort" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -d '{
            "id": 1234,
            "name": "광고반응타겟_데이터_수정",
            "baseAds": [
                {
                    "campaign": {
                        "id": 56,
                        "campaignTypeGoal": {
                            "campaignType": "TALK_CHANNEL"
                        }
                    },
                    "adGroup": {
                        "id": 78
                    },
                    "firstIndicator": "OPEN",
                    "operation": "ONLY"
                }
            ]
        }'

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId": 1234,
    "id": 1,
    "audienceType": "MESSAGE",
    "collectDuration": 90,
    "cohortStatus": "WAITING",
    "name": "광고반응타겟_이름_수정",
    "baseAds": [
        {
            "campaign": {
                "id": 56,
                "name": "첫번째_캠페인",
                "campaignTypeGoal": {
                    "campaignType": "TALK_CHANNEL",
                    "goal": "REACH"
                }
            },
            "adGroup": {
                "id": 78,
                "name": "첫번째_광고그룹"
            },
            "operation": "ONLY",
            "firstIndicator": "OPEN"
        }
    ],
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 15:00:00"
}

광고반응타겟 삭제

기본 정보

메서드	URL	인증 방식
`DELETE`	`https://apis.moment.kakao.com/openapi/v4/targetings/cohort/${ID}`	비즈니스 토큰

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

광고반응타겟을 삭제합니다.

이미 삭제된 광고반응타겟 또는 사용 중인 광고반응타겟은 삭제할 수 없습니다.

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

이 API는 사용자 계정마다 1초에 한 번씩 요청이 가능하도록 제한되어 있습니다.

요청

헤더

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

경로 변수

이름	타입	설명	필수
ID	`Long`	광고반응타겟 번호	O

예제

요청

curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/targetings/cohort/${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

광고반응타겟 여러 개 삭제

기본 정보

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

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

복수의 광고반응타겟을 한번에 삭제합니다.

이미 삭제된 광고반응타겟 또는 사용 중인 광고반응타겟은 삭제할 수 없습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청합니다. 실패 시 에러 코드에서 원인을 확인합니다.

이 API는 사용자 계정마다 1초에 한 번씩 요청이 가능하도록 제한되어 있습니다.

요청

헤더

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

쿼리 파라미터

이름	타입	설명	필수
cohortIds	`String`	광고반응타겟 번호 여러 개의 광고반응타겟 번호를 쉼표(,)로 구분한 하나의 문자열로 전달	O

예제

요청

curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/targetings/cohort?cohortIds=${COHORT_ID},${COHORT_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/cohort/usages/${ID}`	비즈니스 토큰

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

광고반응타겟 사용 현황 목록을 조회할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 광고반응타겟 번호를 전달해야 합니다. 성공 시 계정 내 해당 광고반응타겟이 타게팅에 사용된 광고그룹 및 메시지 목록을 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더

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

경로 변수

이름	타입	설명	필수
ID	`Long`	광고반응타겟 번호	O

응답

본문

이름	타입	설명
-	`AdGroupAndCampaign[]`	광고반응타겟 사용 현황 목록

AdGroupAndCampaign

이름	타입	설명
adGroup	`AdGroup`	광고그룹
campaign	`Campaign`	캠페인
messageAd	`MessageAd`	메시지

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/cohort/usages/${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "adGroup": {
            "id": 105488,
            "name": "first_ad_group",
            "adGroupStatus": ["LIVE"],
            "adGroupType": "DISPLAY"
        },
        "campaign": {
            "id": 62286,
            "name": "first_campaign",
            "campaignTypeGoal": {
                "campaignType": "DISPLAY",
                "goal": "VISITING"
            }
        }
    },
    {
        "messageAd": {
            "id": "msg-ad-1362737813386051585",
            "name": "first_message",
            "opStatus": ["READY"]
        }
    }
]

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

광고반응타겟 관리

광고반응타겟 안내

광고반응타겟 유형별 정책

광고 유형: DISPLAY

광고 유형: MESSAGE

광고 반응 데이터 정의

광고 반응 데이터 설정 가능 연산

광고반응타겟 목록 조회

기본 정보

요청

헤더

응답

본문

CohortTarget

예제

요청

응답

광고반응타겟 조회

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

광고반응타겟 생성 가능 대상 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

AdGroupAndCampaign

예제

요청

응답

광고반응타겟 생성

기본 정보

요청

헤더

본문

BaseAd

AdGroup

Campaign

응답

본문

예제

요청

응답

광고반응타겟 이름 수정

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

광고반응타겟 데이터 수정

기본 정보

요청

헤더

본문

BaseAd

응답

본문

예제