Kakao Moment

Audience management

This document describes how to use the Audience management APIs.

View list of Audiences

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/targetings/audiences`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves the list of Audiences through the Audience management function.

Send a GET request with the issued business token and an ad account ID (adAccountId) in the request header. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Response

Body

Name	Type	Description
content	`Audience[]`	List of Audience information.

Audience

Name	Type	Description
id	`Long`	Audience's ID.
name	`String`	Audience's name.
audienceStatus	`String`	Audience's status. One of the followings: `STANDBY`: Preparing. `AVAILABLE` Available. `SEED_NOT_ENOUGH`: Insufficient target population. `ERROR`: Unavailable.
type	`String`	Audience's type. Either `DISPLAY` or `MESSAGE`.
createdDate	`String`	Date and time of Audience creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of Audience modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "content": [
    {
      "id": 1,
      "name": "first_audience",
      "audienceStatus": "AVAILABLE",
      "type": "DISPLAY",
      "createdDate": "2021-05-03T18:50:54",
      "lastModifiedDate": "2021-05-03T18:50:54"
    },
    {
      "id": 2,
      "name": "second_audience",
      "audienceStatus": "AVAILABLE",
      "type": "MESSAGE",
      "createdDate": "2021-04-21T14:36:07",
      "lastModifiedDate": "2021-04-21T14:43:23"
    },
    {
      "id": 3,
      "name": "third-audience",
      "audienceStatus": "SEED_NOT_ENOUGH",
      "type": "DISPLAY",
      "createdDate": "2021-04-21T14:35:32",
      "lastModifiedDate": "2021-04-21T14:35:42"
    }
  ]
}

View details of Audience

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/targetings/${ID}`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves detailed information of a specific Audience.

Send a GET request with the issued business token and an ad account ID (adAccountId) in the request header. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Path variable

Name	Type	Description	Required
ID	`Long`	Audience's ID.	O

Response

Body

Name	Type	Description
id	`Long`	Audience's ID.
name	`String`	Audience's name.
type	`String`	Audience's type. Either `DISPLAY` or `MESSAGE`.
audienceStatus	`String`	Audience's status. One of the followings: `STANDBY`: Preparing. `AVAILABLE` Available. `SEED_NOT_ENOUGH`: Insufficient target population. `ERROR`: Unavailable.
populationScore	`Long`	Estimated target population. Estimated target population for Audience.
createdDate	`String`	Date and time of Audience creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of Audience modification in `yyyy-MM-dd'T'HH:mm:ss` format.
ageType	`String`	Selection type for age range. Either `All` (Select all age ranges) or `NOT_ALL` (Select some age ranges).
ages	`Set of String`	Age range.
genderType	`String`	Selection type for gender. Either `All` (Select all genders) or `NOT_ALL` (Select a specific gender).
genders	`Set of String`	Gender. Either `M` (Male) or `F` (Female).
locations	`Set of Location`	-si (city) or -do (province) information. Refer to View city/province.
depth2Locations	`Set of Depth2Location`	-si (city), -gun (county), or -gu (district) information. Refer to View city/county/district.
depth3Locations	`Set of Depth3Location`	-dong (neighborhood), -eup (town), or -myeon (townships) information. Refer to View dong/eup/myeon.
ufoInterests	`EnumSet of UfoInterest`	Information of interest targeting. Refer to View category data for custom audience targeting.
ufoDeprecatedInterests	`EnumSet of UfoInterest`	Deprecated information of interest targeting. Refer to View category data for custom audience targeting.
ufoBusinessTypes	`EnumSet of UfoBusinessType`	Information of business type targeting. Refer to View category data for custom audience targeting.
ufoDeprecatedBusinessTypes	`EnumSet of UfoBusinessType`	Deprecated information of business type targeting. Refer to View category data for custom audience targeting.
talkChannelTargetings	`Set of TalkChannelTargeting`	Information of Kakao Talk Channel targeting.
syncAppTargetings	`Set of SyncAppTargeting`	Information of Kakao Login user targeting.
customerFileTargetings	`Set of CustomerFileTargeting`	Information of customer file targeting.
cohortTargetings	`Set of CohortTargeting`	Information of engagement targeting.
trackerTargetings	`Set of TrackerTargeting`	Information of Pixel & SDK targeting.
talkChannelGroupTargetings	`Set of TalkChannelGroupTargeting`	Information of friends group targeting.

Sample

Request

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

Response

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"
}

Create Audience

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/v4/targetings`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Creates a new Audience that you can use when creating or editing an ad group.

Send a POST request with the issued business token and an ad account ID (adAccountId) in the request header. You must pass the information used for targeting when you request. If failed, refer to Error code to figure out its failure cause.

Available parameter by Audience type

Type	DISPLAY	MESSAGE
`ufoInterests` (Interest)	O	O
`ufoBusinessTypes` (Category)	O	O
`locations` (Cities/provinces)	O	O
`depth2Locations` (Cities/counties/districts)	O	O
`depth3Locations` (dong/eup/myeon)	O	O
`customerFileTargetings` (Customer file)	O	X
`trackerTargetings` (Pixel & SDK)	O	X
`cohortTargetings` (Engagement targeting)	O	O
`talkChannelTargetings` (Kakao Talk Channel)	O	O
`syncAppTargetings` (Kakao Login user)	O	O
`talkChannelGroupTargetings` (Friend group)	X	O

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Body

Name	Type	Description	Required
adAccountId	`Long`	Ad account's ID that the corresponding Audience is included.	O
name	`String`	Audience's name.	O
type	`String`	Audience's type. Either `DISPLAY` or `MESSAGE`.	O
ageType	`String`	Selection type for age range. Either `All` (Select all age ranges) or `NOT_ALL` (Select some age ranges).	O
ages	`String[]`	Age range. Use one or more of the followings: `15`: 15 to 19 `20`: 20 to 24 `25`: 25 to 29 `30`: 30 to 34 `35`: 35 to 39 `40`: 40 to 44 `45`: 45 to 49 `50`: 50 to 54 `55`: 55 to 59 `60`: 60 to 64 `65`: 65 to 69 Only allowed if `ageType` is set to `NOT_ALL`. If you set `ageType` to `ALL`, do not pass `ages`. If you set `adult` to `true`, pass `"20","25","30","35","40","45","50","55","60","65"` as an array.	O*
genderType	`String`	Selection type for gender. Either `All` (Select all genders) or `NOT_ALL` (Select a specific gender).	O
genders	`String[]`	Gender. Either `M` (Male) or `F` (Female). If you set `genderType` to `ALL`, do not pass `genders`.	O*
ufoInterests	`Set of UfoInterest`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [관심사(Interests)] Refer to View category data for custom audience targeting.	X
ufoBusinessTypes	`Set of UfoBusinessType`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [업종(Industries) Refer to View category data for custom audience targeting.	X
locationType	`String`	Selection type for areas. Either `ALL` (Select all) or `AREA` (Select some areas).	O
locations	`Set of Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/도(-si/do)] Refer to View city/province. Not allowed if `locationType` is set to `ALL`. Allowed to pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). If the campaign type is 'Kakao Bizboard', Overseas(Z) is not allowed.	X
depth2Locations	`Set of Depth2Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/군/구(-si/gun/gu)] Refer to View city/county/district. If `locationType` is set to `AREA`, you must pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). You can also pass all of three parameters.	X
depth3Locations	`Set of Depth3Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [동/읍/면(-dong/eup/myeon)] Refer to View dong/eup/myeon. If `locationType` is set to `AREA`, you must pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). You can also pass all of three parameters.	X
customerFileTargetings	`Set of CustomerFileTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [고객파일(Customer file]) Use information retrieved through the Viewing list of targetable customer files API.	X
trackerTargetings	`Set of TrackerTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [픽셀 & SDK(Pixel & SDK)] Use information retrieved through the Viewing targetable Pixel & SDK events API.	X
cohortTargetings	`Set of CohortTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [광고반응타겟(Engagement target)] Use information retrieved through the Viewing targetable engagement targets API.	X
talkChannelTargetings	`Set of TalkChannelTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user) > [카카오톡 채널 친구(Kakao Talk Channel friend)] Use information retrieved through the Viewing list of targetable Kakao Talk Channels API.	X
syncAppTargetings	`Set of SyncAppTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user) > [카카오 로그인 이용자(Kakao Login user)] Use information retrieved through the Viewing list of targetable Kakao Login users API.	X
talkChannelGroupTargetings	`Set of TalkChannelGroupTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [친구그룹(Friend group)] Use the information retrieved through the Viewing list of targetable Friend groups API. Only the campaigns with 'Kakao Talk Channel X Reach(도달)' type are allowed.	X

Response

Body

Name	Type	Description
id	`Long`	Audience's ID.
name	`String`	Audience's name.
type	`String`	Audience's type. Either `DISPLAY` or `MESSAGE`.
audienceStatus	`String`	Audience's status. One of the followings: `STANDBY`: Preparing. `AVAILABLE` Available. `SEED_NOT_ENOUGH`: Insufficient target population. `ERROR`: Unavailable.
populationScore	`Long`	Estimated target population. Estimated target population for Audience.
createdDate	`String`	Date and time of Audience creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of Audience modification in `yyyy-MM-dd'T'HH:mm:ss` format.
ageType	`String`	Selection type for age range. Either `All` (Select all age ranges) or `NOT_ALL` (Select some age ranges).
ages	`Set of String`	Age range.
genderType	`String`	Selection type for gender. Either `All` (Select all genders) or `NOT_ALL` (Select a specific gender).
genders	`Set of String`	Gender. Either `M` (Male) or `F` (Female).
locations	`Set of Location`	-si (city) or -do (province) information. Refer to View city/province.
depth2Locations	`Set of Depth2Location`	-si (city), -gun (county), or -gu (district) information. Refer to View city/county/district.
depth3Locations	`Set of Depth3Location`	-dong (neighborhood), -eup (town), or -myeon (townships) information. Refer to View dong/eup/myeon.
ufoInterests	`EnumSet of UfoInterest`	Information of interest targeting. Refer to View category data for custom audience targeting.
ufoBusinessTypes	`EnumSet of UfoBusinessType`	Information of business type targeting. Refer to View category data for custom audience targeting.
talkChannelTargetings	`Set of TalkChannelTargeting`	Information of Kakao Talk Channel targeting.
syncAppTargetings	`Set of SyncAppTargeting`	Information of Kakao Login user targeting.
customerFileTargetings	`Set of CustomerFileTargeting`	Information of customer file targeting.
cohortTargetings	`Set of CohortTargeting`	Information of engagement targeting.
trackerTargetings	`Set of TrackerTargeting`	Information of Pixel & SDK targeting.
talkChannelGroupTargetings	`Set of TalkChannelGroupTargeting`	Information of friends group targeting.

Sample

Request

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": "create_open_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동"
            }
        ]
    }'

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1,
    "type": "DISPLAY",
    "adAccountId": 1,
    "name": "create_open_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동"
        }
    ]
}

Edit Audience

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/targetings`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Enables you to edit the Audience.

Send a PUT request with the issued business token and an ad account ID (adAccountId) in the request header. You must also pass the information used for targeting when you request. If the request is successful, this API returns the changed information of the Audience in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Body

Name	Type	Description	Required
id	`Long`	Audience's ID.	O
type	`String`	Audience's type. Either `DISPLAY` or `MESSAGE`.	O
adAccountId	`Long`	Ad account's ID that the corresponding Audience is included.	O
name	`String`	Audience's name.	O
ageType	`String`	Selection type for age range. Either `All` (Select all age ranges) or `NOT_ALL` (Select some age ranges). If you set `adult` to `true`, only `NOT_ALL` is allowed.	O
ages	`String[]`	Age range. Use one or more of the followings: `15`: 15 to 19 `20`: 20 to 24 `25`: 25 to 29 `30`: 30 to 34 `35`: 35 to 39 `40`: 40 to 44 `45`: 45 to 49 `50`: 50 to 54 `55`: 55 to 59 `60`: 60 to 64 `65`: 65 to 69 Only allowed if `ageType` is set to `NOT_ALL`. If you set `ageType` to `ALL`, do not pass `ages`. If you set `adult` to `true`, pass `"20","25","30","35","40","45","50","55","60","65"` as an array.	O*
genderType	`String`	Selection type for gender. Either `All` (Select all genders) or `NOT_ALL` (Select a specific gender).	O
genders	`Set of String`	Gender. Either `M` (Male) or `F` (Female).	O*
ufoInterests	`EnumSet of UfoInterest`	Information of interest targeting. Refer to View category data for custom audience targeting.	X
ufoBusinessTypes	`EnumSet of UfoBusinessType`	Information of business type targeting. Refer to View category data for custom audience targeting.	X
locations	`Set of Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/도(-si/do)] Refer to View city/province. Not allowed if `locationType` is set to `ALL`. Allowed to pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). If the campaign type is 'Kakao Bizboard', Overseas(Z) is not allowed.	X
depth2Locations	`Set of Depth2Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/군/구(-si/gun/gu)] Refer to View city/county/district. If `locationType` is set to `AREA`, you must pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). You can also pass all of three parameters.	X
depth3Locations	`Set of Depth3Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [동/읍/면(-dong/eup/myeon)] Refer to View dong/eup/myeon. If `locationType` is set to `AREA`, you must pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). You can also pass all of three parameters.	X
customerFileTargetings	`Set of CustomerFileTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [고객파일(Customer file]) Use information retrieved through the Viewing list of targetable customer files API.	X
trackerTargetings	`Set of TrackerTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [픽셀 & SDK(Pixel & SDK)] Use information retrieved through the Viewing targetable Pixel & SDK events API.	X
cohortTargetings	`Set of CohortTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [광고반응타겟(Engagement target)] Use information retrieved through the Viewing targetable engagement targets API.	X
talkChannelTargetings	`Set of TalkChannelTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user) > [카카오톡 채널 친구(Kakao Talk Channel friend)] Use information retrieved through the Viewing list of targetable Kakao Talk Channels API.	X
syncAppTargetings	`Set of SyncAppTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user) > [카카오 로그인 이용자(Kakao Login user)] Use information retrieved through the Viewing list of targetable Kakao Login users API.	X
talkChannelGroupTargetings	`Set of TalkChannelGroupTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [친구그룹(Friend group)] Use the information retrieved through the Viewing list of targetable Friend groups API. Only the campaigns with 'Kakao Talk Channel X Reach(도달)' type are allowed.	X

Response

Body

Name	Type	Description
id	`Long`	Audience's ID.
name	`String`	Audience's name.
type	`String`	Audience's type. Either `DISPLAY` or `MESSAGE`.
audienceStatus	`String`	Audience's status. One of the followings: `STANDBY`: Preparing. `AVAILABLE` Available. `SEED_NOT_ENOUGH`: Insufficient target population. `ERROR`: Unavailable.
populationScore	`Long`	Estimated target population. Estimated target population for Audience.
createdDate	`String`	Date and time of Audience creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of Audience modification in `yyyy-MM-dd'T'HH:mm:ss` format.
ageType	`String`	Selection type for age range. Either `All` (Select all age ranges) or `NOT_ALL` (Select some age ranges).
ages	`Set of String`	Age range.
genderType	`String`	Selection type for gender. Either `All` (Select all genders) or `NOT_ALL` (Select a specific gender).
genders	`Set of String`	Gender. Either `M` (Male) or `F` (Female).
locations	`Set of Location`	-si (city) or -do (province) information. Refer to View city/province.
depth2Locations	`Set of Depth2Location`	-si (city), -gun (county), or -gu (district) information. Refer to View city/county/district.
depth3Locations	`Set of Depth3Location`	-dong (neighborhood), -eup (town), or -myeon (townships) information. Refer to View dong/eup/myeon.
ufoInterests	`EnumSet of UfoInterest`	Information of interest targeting. Refer to View category data for custom audience targeting.
ufoBusinessTypes	`EnumSet of UfoBusinessType`	Information of business type targeting. Refer to View category data for custom audience targeting.
talkChannelTargetings	`Set of TalkChannelTargeting`	Information of Kakao Talk Channel targeting.
syncAppTargetings	`Set of SyncAppTargeting`	Information of Kakao Login user targeting.
customerFileTargetings	`Set of CustomerFileTargeting`	Information of customer file targeting.
cohortTargetings	`Set of CohortTargeting`	Information of engagement targeting.
trackerTargetings	`Set of TrackerTargeting`	Information of Pixel & SDK targeting.
talkChannelGroupTargetings	`Set of TalkChannelGroupTargeting`	Information of friends group targeting.

Sample

Request

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": "create_open_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동"
            }
        ]
    }'

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1,
    "type": "DISPLAY",
    "adAccountId": 1,
    "name": "create_open_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동"
        }
    ]
 }

Delete Audience

Basic information

Method	URL	Authorization
`DELETE`	`https://apis.moment.kakao.com/openapi/v4/targetings/${ID}`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Deletes an Audience.

Send a DELETE request with the issued business token and an ad account ID (adAccountId) in the request header. You must pass the Audience's ID as a parameter when you request. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Path variable

Name	Type	Description	Required
ID	`Long`	Audience's ID.	O

Sample

Request

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"

Response

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

Delete multiple Audiences

Basic information

Method	URL	Authorization
`DELETE`	`https://apis.moment.kakao.com/openapi/v4/targetings`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Deletes multiple Audiences at once.

Send a DELETE request with the issued business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Query parameter

Name	Type	Description	Required
audienceIds	`String`	Audience's ID. To pass multiple Audience IDs, separate them with comma(,).	O

Sample

Request

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}"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "successCount": 1,
    "failCount": 1,
    "errorMessages": [
        "이미 삭제된 오디언스입니다."
    ]
}

View usage of Audience

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/targetings/${ID}/adGroups`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves the information of ad groups that use the designated Audience through the Audience management function.

Send a GET request with the issued business token and an ad account ID (adAccountId) in the request header. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Path variable

Name	Type	Description	Required
ID	`Long`	Audience's ID.	O

Response

Body

Name	Type	Description
content	`AudienceAdGroup[]`	List of ad groups using the Audience.

AudienceAdGroup

Name	Type	Description
campaignId	`Long`	Campaign's ID.
campaignName	`String`	Campaign's name.
campaignTypeGoal	`CampaignTypeGoal`	Campaign Type X Goal.
adGroupId	`Long`	Ad group's ID.
adGroupName	`String`	Ad group' name.
adGroupStatus	`Status[]`	Ad group's status.
adGroupType	`String`	Ad group's type. Either `DISPLAY` or `DIRECT_MESSAGE`.

Sample

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "content": [
        {
            "campaignId": 1,
            "campaignName": "first_campaign",
            "campaignTypeGoal": {
                "campaignType": "TALK_BIZ_BOARD",
                "goal": "VISITING"
            },
            "adGroupId": 1,
            "adGroupName": "first_ad_group",
            "adGroupStatus": [
                "OFF"
            ],
            "adGroupType": "DISPLAY"
        },
        {
          "campaignId": 1,
          "campaignName": "first_campaign",
          "campaignTypeGoal": {
              "campaignType": "TALK_BIZ_BOARD",
              "goal": "VISITING"
          },
          "adGroupId": 2,
          "adGroupName": "second_ad_group",
          "adGroupStatus": [
              "OFF"
          ],
          "adGroupType": "DISPLAY"
        },
        {
            "campaignId": 2,
            "campaignName": "second_campaign",
            "campaignTypeGoal": {
                "campaignType": "TALK_BIZ_BOARD",
                "goal": "VISITING"
            },
            "adGroupId": 3,
            "adGroupName": "third_ad_group",
            "adGroupStatus": [
                "OFF"
            ],
            "adGroupType": "DISPLAY"
        }
    ]
}

Disable use of Audience

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/targetings/${ID}/unlink`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Enables you to disable the ad group that uses the designated Audience through the Audience management function.

Send a PUT request with the issued business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Path variable

Name	Type	Description	Required
ID	`Long`	Audience's ID.	O

Query parameter

Name	Type	Description	Required
adGroupId	`Long`	Ad group's ID.	O

Sample

Request

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}"

Response

HTTP/1.1 200 OK

See more

Kakao Moment API Reference

사이드 메뉴

Getting started

Kakao Developers

Login

Communication

Kakao Map

Navigation

Advertisement

Search

More

Audience management

View list of Audiences

Basic information

Request

Header

Response

Body

Audience

Sample

Request

Response

View details of Audience

Basic information

Request

Header

Path variable

Response

Body

Sample

Request

Response

Create Audience

Basic information

Available parameter by Audience type

Request

Header

Body

Response

Body

Sample

Request

Response

Edit Audience

Basic information

Request

Header

Body

Response

Body

Sample

Request

Response

Delete Audience

Basic information

Request

Header

Path variable

Sample

Request

Response

Delete multiple Audiences

Basic information

Request

Header

Query parameter

Sample

Request

Response

View usage of Audience

Basic information

Request

Header

Path variable

Response

Body

AudienceAdGroup

Sample

Request

Response

Disable use of Audience