카카오모먼트

오디언스 관리

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

오디언스 목록 조회

기본 정보

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

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

오디언스 관리의 오디언스 목록을 반환합니다.

요청

헤더

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

응답

본문

이름	타입	설명
content	`Audience[]`	오디언스 목록

Audience

이름	타입	설명
id	`Long`	오디언스 번호
name	`String`	오디언스명
audienceStatus	`Enum`	오디언스 상태 `STANDBY`: 준비중 `AVAILABLE`: 사용가능 `SEED_NOT_ENOUGH`: 모수 부족 `ERROR`: 사용불가
type	`Enum`	오디언스 유형 `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 등록 비즈니스 동의항목 설정	에러 코드 용어집

오디언스 관리의 오디언스 단건을 반환합니다.

요청

헤더

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

경로 변수

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

응답

본문

이름	타입	설명
id	`Long`	오디언스 번호
name	`String`	오디언스명
type	`Enum`	오디언스 유형 `DISPLAY`: 디스플레이 `MESSAGE`: 메시지
audienceStatus	`Enum`	오디언스 상태 `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	`Enum`	연령대 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택
ages	`String[]`	연령대
genderType	`Enum`	성별 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택
genders	`String[]`	성별 `M`: 남자 `F`: 여자
locations	`Location[]`	데모그래픽 > 행정구역 > 시/도 시/도 조회 참고
depth2Locations	`Location[]`	데모그래픽 > 행정구역 > 시/군/구 시/군/구 조회 참고
depth3Locations	`Depth3Location[]`	데모그래픽 > 행정구역 > 동/읍/면 동/읍/면 조회 참고
ufoInterests	`UfoInterest[]`	관심사 타게팅 맞춤타겟 카테고리 타입 조회 API 참고
ufoDeprecatedInterests	`UfoInterest[]`	지원 중단된 관심사 타게팅 맞춤타겟 카테고리 타입 조회 API 참고
ufoBusinessTypes	`UfoBusinessType[]`	업종 타게팅 맞춤타겟 카테고리 타입 조회 API 참고
ufoDeprecatedBusinessTypes	`UfoBusinessType[]`	지원 중단된 업종 타게팅 맞춤타겟 카테고리 타입 조회 API 참고
talkChannelTargetings	`TalkChannelTargeting[]`	카카오톡 채널 타게팅
syncAppTargetings	`SyncAppTargeting[]`	카카오 로그인 이용자 타게팅
customerFileTargetings	`CustomerFileTargeting[]`	고객파일 타게팅
cohortTargetings	`CohortTargeting[]`	광고반응 타게팅
trackerTargetings	`TrackerTargeting[]`	픽셀&SDK 타게팅
talkChannelGroupTargetings	`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 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

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

유형	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	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
adAccountId	`Long`	해당 오디언스가 소속되는 광고계정 ID	O
name	`String`	오디언스의 이름	O
type	`Enum`	오디언스 유형 `DISPLAY`: 디스플레이 `MESSAGE`: 메시지	O
ageType	`Enum`	연령대 전체 선택 종류 `ALL`: 전체 선택 `NOT_ALL`: 부분 선택 중요: `ages`로 성인 타게팅을 지정하는 경우 `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`이 `NOT_ALL`인 경우 필수, `ALL`인 경우 요청 불가 중요: 성인 타게팅은 `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`를 배열에 담아 요청 시 지정 가능	X
genderType	`Enum`	성별 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택	O
genders	`String[]`	성별 `M`: 남자 `F`: 여자 중요: `genderType`이 `NOT_ALL`인 경우 필수, `ALL`인 경우 요청 불가	X
ufoInterests	`UfoInterest[]`	맞춤 타겟 > 카카오 데이터 > 카테고리 > 관심사 맞춤타겟 카테고리 타입 조회 API 참고	X
ufoBusinessTypes	`UfoBusinessType[]`	맞춤 타겟 > 카카오 데이터 > 카테고리 > 업종 맞춤타겟 카테고리 타입 조회 API 참고	X
locationType	`Enum`	지역선택 타입 `ALL`: 전체선택 `AREA`: 지역선택	O
locations	`Location[]`	데모그래픽 > 행정구역 > 시/도 시/도 조회 참고 중요: `locationType`이 `ALL`인 경우 요청 불가 중요: 캠페인 유형이 카카오 비즈보드인 경우 해외(`Z`) 요청 불가 참고: `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면)와 함께 요청 가능	X
depth2Locations	`Depth2Location[]`	데모그래픽 > 행정구역 > 시/군/구 시/군/구 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수	X
depth3Locations	`Depth3Location[]`	데모그래픽 > 행정구역 > 동/읍/면 동/읍/면 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수	X
customerFileTargetings	`CustomerFileTargeting[]`	맞춤타겟 > 내 데이터 > 고객파일 타게팅 가능한 고객파일 목록 조회 API로 조회 가능한 정보를 활용	X
trackerTargetings	`TrackerTargeting[]`	맞춤타겟 > 내 데이터 > 픽셀 & SDK 타게팅 가능한 픽셀 & SDK 이벤트 목록 보기로 조회 가능한 정보를 활용	X
cohortTargetings	`CohortTargeting[]`	맞춤타겟 > 내 데이터 > 광고반응타겟 타게팅 가능한 광고반응타겟 조회 API로 조회 가능한 정보를 활용	X
talkChannelTargetings	`TalkChannelTargeting[]`	맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구 타게팅 가능한 카카오톡 채널 정보 목록 조회 API로 조회 가능한 정보를 활용	X
syncAppTargetings	`SyncAppTargeting[]`	맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자 타게팅 가능한 카카오 로그인 이용자 목록 조회 API로 조회 가능한 정보를 활용	X
talkChannelGroupTargetings	`TalkChannelGroupTargeting[]`	맞춤타겟 > 내 데이터 > 친구그룹 타게팅 가능한 친구그룹 목록 조회 API로 조회 가능한 정보를 활용 중요: 카카오톡 채널 X 도달 캠페인에서만 사용 가능	X

응답

본문

이름	타입	설명
id	`Long`	오디언스 번호
name	`String`	오디언스명
type	`Enum`	오디언스 유형 `DISPLAY`: 디스플레이 `MESSAGE`: 메시지
adAccountId	`Long`	광고계정 ID
audienceStatus	`Enum`	오디언스 상태 `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	`Enum`	연령대 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택
ages	`String[]`	연령대
genderType	`Enum`	성별 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택
genders	`String[]`	성별
locations	`Location[]`	시/도 시/도 조회 참고
depth2Locations	`Depth2Location[]`	시/군/구 시/군/구 조회 참고
depth3Locations	`Depth3Location[]`	데모그래픽 > 행정구역 > 동/읍/면 동/읍/면 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수
ufoInterests	`UfoInterest[]`	관심사 타게팅 맞춤타겟 카테고리 타입 조회 API 참고
ufoBusinessTypes	`UfoBusinessType[]`	업종 타게팅 맞춤타겟 카테고리 타입 조회 API 참고
talkChannelTargetings	`TalkChannelTargeting[]`	카카오톡 채널 타게팅
syncAppTargetings	`SyncAppTargeting[]`	카카오 로그인 이용자 타게팅
customerFileTargetings	`CustomerFileTargeting[]`	고객파일 타게팅
cohortTargetings	`CohortTargeting[]`	광고반응 타게팅
trackerTargetings	`TrackerTargeting[]`	픽셀&SDK 타게팅
talkChannelGroupTargetings	`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",
                "description": "경기도 여주시",
                "depth1Name": "경기도",
                "depth2Name": "여주시"
            },
            {
                "value": "I1009",
                "description": "서울특별시 도봉구",
                "depth1Name": "광주광역시",
                "depth2Name": "도봉구"
            }
        ],
        "depth3Locations": [
            {
                "value": "A70052424",
                "description": "강원도 삼척시 원덕읍",
                "depth1Name": "강원도",
                "depth2Name": "삼척시",
                "depth3Name": "원덕읍"
            },
            {
                "value": "E13010702",
                "description": "광주광역시 남구 백운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",
      "description": "경기도 여주시",
      "depth1Name": "경기도",
      "depth2Name": "여주시"
    },
    {
      "value": "I1009",
      "description": "서울특별시 도봉구",
      "depth1Name": "광주광역시",
      "depth2Name": "도봉구"
    }
  ],
  "depth3Locations": [
    {
      "value": "A70052424",
      "description": "강원도 삼척시 원덕읍",
      "depth1Name": "강원도",
      "depth2Name": "삼척시",
      "depth3Name": "원덕읍"
    },
    {
      "value": "E13010702",
      "description": "광주광역시 남구 백운2동",
      "depth1Name": "광주광역시",
      "depth2Name": "남구",
      "depth3Name": "백운2동"
    }
  ]
}

오디언스 수정

기본 정보

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

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

오디언스를 수정합니다.

요청

헤더

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

본문

이름	타입	설명	필수
id	`Long`	해당 오디언스의 ID	O
type	`Enum`	오디언스 유형 `DISPLAY`: 디스플레이 `MESSAGE`: 메시지	O
adAccountId	`Long`	해당 오디언스가 소속되는 광고계정 ID	O
name	`String`	오디언스의 이름	O
ageType	`Enum`	연령대 전체 선택 종류 `ALL`: 전체 선택 `NOT_ALL`: 부분 선택 중요: `ages`로 성인 타게팅을 지정하는 경우 `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`이 `NOT_ALL`인 경우 필수, `ALL`인 경우 요청 불가 중요: 성인 타게팅은 `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`를 배열에 담아 요청 시 지정 가능	X
genderType	`Enum`	성별 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택	O
genders	`String[]`	성별 `M`: 남자 `F`: 여자 중요: `genderType`이 `NOT_ALL`인 경우 필수, `ALL`인 경우 요청 불가	X
ufoInterests	`UfoInterest[]`	맞춤 타겟 > 카카오 데이터 > 카테고리 > 관심사 맞춤타겟 카테고리 타입 조회 API 참고	X
ufoBusinessTypes	`UfoBusinessType[]`	맞춤 타겟 > 카카오 데이터 > 카테고리 > 업종 맞춤타겟 카테고리 타입 조회 API 참고	X
locationType	`Enum`	지역선택 타입 `ALL`: 전체선택 `AREA`: 지역선택	O
locations	`Location[]`	데모그래픽 > 행정구역 > 시/도 시/도 조회 참고 중요: `locationType`이 `ALL`인 경우 요청 불가 중요: 캠페인 유형이 카카오 비즈보드인 경우 해외(`Z`) 요청 불가 참고: `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면)와 함께 요청 가능	X
depth2Locations	`Depth2Location[]`	데모그래픽 > 행정구역 > 시/군/구 시/군/구 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수	X
depth3Locations	`Depth3Location[]`	데모그래픽 > 행정구역 > 동/읍/면 동/읍/면 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수	X
customerFileTargetings	`CustomerFileTargeting[]`	맞춤타겟 > 내 데이터 > 고객파일 타게팅 가능한 고객파일 목록 조회 API로 조회 가능한 정보를 활용	X
trackerTargetings	`TrackerTargeting[]`	맞춤타겟 > 내 데이터 > 픽셀 & SDK 타게팅 가능한 픽셀 & SDK 이벤트 목록 보기로 조회 가능한 정보를 활용	X
cohortTargetings	`CohortTargeting[]`	맞춤타겟 > 내 데이터 > 광고반응타겟 타게팅 가능한 광고반응타겟 조회 API로 조회 가능한 정보를 활용	X
talkChannelTargetings	`TalkChannelTargeting[]`	맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구 타게팅 가능한 카카오톡 채널 정보 목록 조회 API로 조회 가능한 정보를 활용	X
syncAppTargetings	`SyncAppTargeting[]`	맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자 타게팅 가능한 카카오 로그인 이용자 목록 조회 API로 조회 가능한 정보를 활용	X
talkChannelGroupTargetings	`TalkChannelGroupTargeting[]`	맞춤타겟 > 내 데이터 > 친구그룹 타게팅 가능한 친구그룹 목록 조회 API로 조회 가능한 정보를 활용 중요: 카카오톡 채널 X 도달 캠페인에서만 사용 가능	X

응답

본문

이름	타입	설명
id	`Long`	오디언스 번호
name	`String`	오디언스명
type	`Enum`	오디언스 유형 `DISPLAY`: 디스플레이 `MESSAGE`: 메시지
adAccountId	`Long`	광고계정 ID
audienceStatus	`Enum`	오디언스 상태 `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	`Enum`	연령대 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택
ages	`String[]`	연령대
genderType	`Enum`	성별 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택
genders	`String[]`	성별
locations	`Location[]`	시/도 시/도 조회 참고
depth2Locations	`Depth2Location[]`	시/군/구 시/군/구 조회 참고
depth3Locations	`Depth3Location[]`	데모그래픽 > 행정구역 > 동/읍/면 동/읍/면 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수
ufoInterests	`UfoInterest[]`	관심사 타게팅 맞춤타겟 카테고리 타입 조회 API 참고
ufoBusinessTypes	`UfoBusinessType[]`	업종 타게팅 맞춤타겟 카테고리 타입 조회 API 참고
talkChannelTargetings	`TalkChannelTargeting[]`	카카오톡 채널 타게팅
syncAppTargetings	`SyncAppTargeting[]`	카카오 로그인 이용자 타게팅
customerFileTargetings	`CustomerFileTargeting[]`	고객파일 타게팅
cohortTargetings	`CohortTargeting[]`	광고반응 타게팅
trackerTargetings	`TrackerTargeting[]`	픽셀&SDK 타게팅
talkChannelGroupTargetings	`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 등록 비즈니스 동의항목 설정	에러 코드 용어집

오디언스를 삭제합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_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 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_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 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

요청

헤더

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

경로 변수

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

응답

본문

이름	타입	설명
content	`AudienceAdGroup[]`	오디언스를 사용하고 있는 광고그룹 목록

AudienceAdGroup

이름	타입	설명
campaignId	`Long`	캠페인 번호
campaignName	`String`	캠페인명
campaignTypeGoal	`CampaignTypeGoal`	캠페인 유형 X 목표
adGroupId	`Long`	광고그룹 번호
adGroupName	`String`	광고그룹명
adGroupStatus	`Enum: Status[]`	광고그룹 상태
adGroupType	`Enum: AdGroupType`	광고그룹 종류

예제

요청

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 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

요청

헤더

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

경로 변수

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

본문

이름	타입	설명	필수
adGroupId	`Long`	광고그룹 번호	O

예제

요청

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/targetings/${ID}/unlink" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "Content-Type: application/json" \
    -d '{
        "adGroupId": "${AD_GROUP_ID}"
    }'

응답

HTTP/1.1 200 OK

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

오디언스 관리

오디언스 목록 조회

기본 정보

요청

헤더

응답

본문

Audience

예제

요청

응답

오디언스 상세 조회

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

오디언스 생성

기본 정보

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

요청

헤더

본문

응답

본문

예제

요청

응답

오디언스 수정

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

오디언스 삭제

기본 정보

요청

헤더

경로 변수

예제

요청

응답

오디언스 여러 개 삭제

기본 정보

요청

헤더

쿼리 파라미터

예제

요청

응답

오디언스 사용 현황 조회

기본 정보

요청

헤더

경로 변수

응답

본문

AudienceAdGroup

예제

요청

응답

오디언스 사용 해제