Kakao Moment

Targeting for ad group

This document describes how to use the Targeting for ad group APIs.

Targeting for ad group APIs provide ad group's information for the targeting settings as a list. You can use these APIs to check the required parameter values before you create or edit an ad group.

View city / province

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/targetings/location/depth1`	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

Returns a list of -si (city) or -do (province) information for region targeting.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O

Response

Body

Name	Type	Description
-	`Location[]`	List of -si (city) or -do (province) information. Use each `value` for `targeting.locations` when creating or editing an ad group.

Sample

Request

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

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
  {
    "value": "A",
    "description": "강원도",
    "depth1Name": "강원도"
  },
  {
    "value": "B",
    "description": "경기도",
    "depth1Name": "경기도"
  },
  {
    "value": "C",
    "description": "경상남도",
    "depth1Name": "경상남도"
  }
  // ...
]

View city / county / district

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/targetings/location/depth2`	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

Returns a list of -si (city), -gun (county), or -gu (district) information for region targeting.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
keyword	`String`	Location you want to know its -si, -gun, or -gu information.	O

Response

Body

Name	Type	Description
-	`Depth2Location[]`	List of -si (city), -gun (county), or -gu information. Use each `value` for `targeting.depth2Locations` when creating or editing an ad group.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/location/depth2?keyword=서울" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"

Response

[
  {
    "value": "I1000",
    "description": "서울특별시 강남구",
    "depth1Name": "서울특별시",
    "depth2Name": "강남구"
  },
  {
    "value": "I1001",
    "description": "서울특별시 강동구",
    "depth1Name": "서울특별시",
    "depth2Name": "강동구"
  }
  // ...
]

Response: Fail

// HTTP/1.1 400 Bad request
// Content-Type: application/json;charset=UTF-8
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 75029,
    "detailMsg": "조회할 시/군/구 검색어를 입력해 주세요."
  }
}

View neighborhood / town / township

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/targetings/location/depth3`	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

Returns a list of -dong (neighborhood), -eup (town), or -myeon (township) information for region targeting.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
keyword	`String`	Location you want to know its -dong, -eup, or -myeon information.	O

Response

Body

Name	Type	Description
-	`Depth3Location[]`	List of -dong, -eup, or -myeon information. Use each `value` for `targeting.depth3Locations` when creating or editing an ad group.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/location/depth3?keyword=논현" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"

Response

[
  {
    "value": "I10000101",
    "description": "서울특별시 강남구",
    "depth1Name": "서울특별시",
    "depth2Name": "강남구",
    "depth3Name": "논현1동"
  },
  {
    "value": "I10000102",
    "description": "서울특별시 강동구",
    "depth1Name": "서울특별시",
    "depth2Name": "강남구",
    "depth3Name": "논현2동"
  }
  // ...
]

Response: Fail

// HTTP/1.1 400 Bad request
// Content-Type: application/json;charset=UTF-8
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 75528,
    "detailMsg": "조회할 동/읍/면 검색어를 입력해 주세요."
  }
}

View categories of Network for placements

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/targetings/placement/adServingCategories`	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

Returns a list of placements available when creating or editing an ad group.

Network placements cannot be set for Display X Conversion campaigns.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O

Response

Body

Name	Type	Description
-	`NetworkPlacement[]`	List of the category information for Network placement.

NetworkPlacement

Name	Type	Description
code	`String`	Category code of the Network placement. When creating or editing an ad group, set the `adServingCategories` field to `code` as an array. In this case, `name` is not required.
name	`String`	Category name of the Network placement.

Sample

Request

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

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
  {
    "code": "IAB16",
    "name": "애완동물"
  },
  {
    "code": "IAB8",
    "name": "식음료"
  },
  {
    "code": "IAB15",
    "name": "과학"
  }
  // ...
]

View list of section categories

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/targetings/placement/sectionCategories`	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

Returns a list of section categories you can select when you create or edit an ad group.

You can select a section category only when the campaign type is 'Kakao Bizboard' and placements is set to KAKAO_TALK.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O

Response

Body

Name	Type	Description
-	`SectionCategory[]`	List of section categories.

SectionCategory

Name	Type	Description
code	`String`	Code of section category. When you create or edit ad group, use this `code` for the `sectionCategories` field as an array. In this case, `name` is not required.
name	`String`	Name of section category.

Sample

Request

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

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
  {
    "code": "KKO99-1",
    "name": "채팅탭에만 노출"
  }
  // ...
]

View targetable engagement targets

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/cohort/availables`	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

Returns a list of engagement targets for custom audience targeting that you can use when creating or editing an ad group.

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
-	`CohortAvailable[]`	List of engagement targets that can be used for custom audience targeting.

CohortAvailable

Name	Type	Description
id	`Long`	Engagement target's ID. Pass this value through `cohortId` as the array of `targeting.cohortTargetings` when creating or editing an ad group.
audienceType	`String`	Engagement target's type. Either `DISPLAY` or `MESSAGE`. When you create or edit an ad group or Audience, you need to use the available Audience type between Display and Message according to its campaign Type X Goal.
adAccountId	`Long`	Ad account's ID.
name	`String`	Engagement target's name.
baseAds	`BaseAd[]`	List of ad response data.
collectDuration	`Integer`	Collecting period. User data collected during this period from today is used for the ad targeting. If no one responded to your ad during this period, data may not exist even though you have run ads before.
status	`String`	Status of target population. One of the followings: `WAITING`: Preparing for extracting target population. `AVAILABLE_ERROR`: Error in extracting target population. `AVAILABLE`: Target population has been extracted from a customer file. `SEED_NOT_ENOUGH`: Insufficient target population. `DELETE`: Deleted or deleting. `ERROR`: Other errors.
populationScore	`Long`	Target population.
createdDate	`String`	Date and time of creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

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

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
  {
    "adAccountId": 1234,
    "id": 1,
    "audienceType": "DISPLAY",
    "name": "first_ad_response_target",
    "baseAds": [
      {
        "campaign": {
          "id": 5678,
          "name": "first_campaign",
          "campaignTypeGoal": {
            "campaignType": "DISPLAY",
            "goal": "VISITING"
          }
        },
        "adGroup": {
          "id": 9012,
          "name": "first_ad_group"
        },
        "operation": "MINUS",
        "firstIndicator": "OPEN",
        "secondIndicator": "CLICK"
      }
    ],
    "collectDuration": 90,
    "status": "AVAILABLE",
    "createdDate": "2018-02-07 10:46:12",
    "lastModifiedDate": "2020-07-07 19:15:38"
  },
  {
    "adAccountId": 1234,
    "id": 2,
    "audienceType": "DISPLAY",
    "name": "second_ad_response_target",
    "baseAds": [
      {
        "campaign": {
          "id": 5678,
          "name": "second_campaign",
          "campaignTypeGoal": {
            "campaignType": "DISPLAY",
            "goal": "CONVERSION"
          }
        },
        "adGroup": {
          "id": 9012,
          "name": "second_ad_group"
        },
        "operation": "ONLY",
        "firstIndicator": "CONVERSION"
      }
    ],
    "collectDuration": 90,
    "status": "AVAILABLE",
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 00:00:00"
  }
]

View targetable Pixel & SDK events

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/trackers/eventCreatables/${TRACK_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

Returns a list of Pixel & SDK events for custom audience targeting that you can use when creating or editing an ad group.

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
TRACK_ID	`String`	Tracker ID. Use the `id` that is retrieved through the View Pixel & SDK API.	O

Query parameter

Name	Type	Description	Required
term	`Integer`	Targeting period. (Min: 1, Max: 180)	O

Response

Body

Name	Type	Description
-	`PixelAndSdkEvent[]`	List of Pixel & SDK events that can be used for custom audience targeting.

PixelAndSdkEvent

Name	Type	Description
eventCode	`String`	Event code.
eventName	`String`	Event name.
eventExtraName	`String`	Custom event name.
trackRuleId	`String`	Tracker information ID.
trackRule	`TrackRule`	Tracker rule. It has no value when `eventCode` is '모든 이벤트(All events)'.
population	`Integer`	Collected target population.
lastEventDate	`String`	Date and time of event confirmed in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/trackers/eventCreatables/${TRACK_ID}?term=${term}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
  {
    "lastEventDate": "2019.10.16 19:36",
    "eventCode": "*",
    "eventName": "모든 이벤트",
    "trackRuleId": "*",
    "population": 15300000
  },
  {
    "trackRule": {
      "trackRuleId": "*",
      "trackId": "3830610710806837838",
      "eventCode": "PageView",
      "name": "visit",
      "ruleSetStr": "[]"
    },
    "lastEventDate": "2019.10.16 19:36",
    "eventCode": "PageView",
    "eventName": "visit",
    "trackRuleId": "*",
    "population": 15290918
  }
]

View list of targetable customer files

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/customerFiles/availables`	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

Returns a list of customer files you can use for targeting when you create or edit an ad group.

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
-	`CustomerFile[]`	List of customer files information that can be used for custom audience targeting.

CustomerFile

Name	Type	Description
id	`Long`	Customer file's ID.
adAccountId	`Long`	Ad account's ID.
name	`String`	Customer file's name.
adidListKey	`String`	Customer file's registration key.
status	`String`	Status. One of the followings: `WAITING`: Waiting for extracting target population `COMPLETE`: Target population has been extracted from a customer file. `DELETE`: Deleted or deleting. `ERROR`: Other abnormal cases.
populationScore	`String`	Target population. The number of Kakao users extracted from the registered customer file. If a customer file's status is `WAITING`, you cannot use the customer file for targeting because population has not been extracted yet. Population is extracted within 6 hours after a customer file is registered.
ready	`Boolean`	Whether it is ready or not.
createdDate	`String`	Date and time of target creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifyRequestDate	`String`	Date and time of target modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/customerFiles/availables" \
    -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,
    "adAccountId": 1234,
    "name": "first_customer file",
    "adidListKey": "123456789abcdefghijklmn",
    "status": "COMPLETE",
    "populationScore": 100,
    "ready": true,
    "createdDate": "2020-01-01 00:00",
    "lastModifyRequestDate": "2020-01-01 00:00"
  }
]

View list of targetable Kakao Talk Channels

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/talkChannels/availables`	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

Returns a list of Kakao Talk Channels you can use for targeting when you create or edit an ad group.

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
-	`ChannelProfile[]`	List of Kakao Talk Channel profile that can be used for custom audience targeting.

ChannelProfile

Name	Type	Description
id	`String`	Kakao Talk Channel's profile ID.
name	`String`	Kakao Talk Channel's profile name.
searchId	`String`	Kakao Talk Channel's name used for search.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/talkChannels/availables" \
    -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": "_xbHxd",
    "name": "first_friend",
    "searchId": "first_friend"
  },
  {
    "id": "_ZQxd",
    "name": "second_friend",
    "searchId": "second_friend"
  }
]

View list of targetable Kakao Login users

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/syncProfiles/availables`	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

Returns a list of Kakao Login users you can use for targeting when you create or edit an ad group.

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
-	`SyncProfile[]`	List of Kakao Login users that can be used for custom audience targeting.

SyncProfile

Name	Type	Description
id	`String`	Kakao Talk Channel's profile ID. Use as the Kakao Login user targeting value when creating or editing an ad group.
name	`String`	Kakao Talk Channel's profile name.
searchId	`String`	Kakao Talk Channel's name used for search.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/syncProfiles/availables" \
    -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": "_XLd",
    "name": "first_friend_with_profile",
    "searchId": "now_profile_exist"
  },
  {
    "id": "_cWn",
    "name": "second_friend_with_profile",
    "searchId": "after_profile_exist"
  }
]

View list of targetable Friend groups

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/talkChannelGroupFiles/availables`	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

Returns a list of Friend groups you can use for targeting when you create or edit an ad group.

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
profileId	`String`	Kakao Talk Channel's profile ID. Campaign's `objective` value.	O

Response

Body

Name	Type	Description
-	`TalkChannelGroupFiles[]`	List of Friend groups that can be used for custom audience targeting.

TalkChannelGroupFiles

Name	Type	Description
id	`Long`	Friend group's ID.
name	`String`	Friend group's name.
profileId	`String`	Kakao Talk Channel's profile ID.
groupKey	`String`	Friend group file's group key.
fileType	`String`	Friend group's type. One of the followings: `APP_USER_ID`: Service user ID `PHONE_NUMBER`: Phone number `MESSAGE_RETARGET`: Message recipients
appId	`Integer`	App ID.
talkChannelGroupFileStatus	`String`	Status. One of the followings: `WAITING`: Pending `COMPLETE`: Completed `DELETE`: Deleted `ERROR`: Failed to create
friendCount	`Long`	Number of friends.
createdDate	`String`	Date and time of target creation in `yyyy-MM-dd'T'HH:mm:ss` format.
populationUpdateDate	`String`	Date and time of target update in `yyyy-MM-dd'T'HH:mm:ss` format. Updated time of target population.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/talkChannelGroupFiles/availables?profileId=_Xxju" \
    -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": 1468,
    "profileId": "_Xxju",
    "name": "test",
    "talkChannelGroupFileStatus": "COMPLETE",
    "fileType": "MESSAGE_RETARGET",
    "groupKey": "bd7d86fc21464e46969f18a83857e0c2",
    "createdDate": "2022-07-25T16:12:43",
    "populationUpdateDate": "2022-07-25T16:50:30"
  },
  {
    "id": 1392,
    "profileId": "_Xxju",
    "name": "sample2",
    "talkChannelGroupFileStatus": "COMPLETE",
    "fileType": "PHONE_NUMBER",
    "groupKey": "17203315dfa944f8a29b4a622e98f790",
    "createdDate": "2022-06-10T13:57:49",
    "populationUpdateDate": "2022-06-10T14:33:30"
  },
  {
    "id": 528,
    "profileId": "_Xxju",
    "name": "multiple_message_ad_group",
    "talkChannelGroupFileStatus": "COMPLETE",
    "fileType": "MESSAGE_RETARGET",
    "groupKey": "422b3f1e3a7b4e4db0a5285000ef9150",
    "createdDate": "2020-08-10T15:28:05"
  }
]

See more

Kakao Moment API Reference

사이드 메뉴

Getting started

Kakao Developers

Login

Communication

Map

Navigation

Advertisement

Search

More

Targeting for ad group

View city / province

Basic information

Request

Header

Response

Body

Sample

Request

Response

View city / county / district

Basic information

Request

Header

Query parameter

Response

Body

Sample

Request

Response

Response: Fail

View neighborhood / town / township

Basic information

Request

Header

Query parameter

Response

Body

Sample

Request

Response

Response: Fail

View categories of Network for placements

Basic information

Request

Header

Response

Body

NetworkPlacement

Sample

Request

Response

View list of section categories

Basic information

Request

Header

Response

Body

SectionCategory

Sample

Request

Response

View targetable engagement targets

Basic information

Request

Header

Response

Body

CohortAvailable

Sample

Request

Response

View targetable Pixel & SDK events

Basic information

Request

Header

Path variable

Query parameter

Response

Body