본문 바로가기메인 메뉴 바로가기사이드 메뉴 바로가기

kakao developers

Related sites
  • Docs
  • Kakao Moment
  • Targeting for ad group

사이드 메뉴

Kakao Map

Search

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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/targetings/location/depth1Business token

Retrieves a list of -si (city) or -do (province) information you can use for region targeting.

Send a GET request with the issued business token in the request header. If the request is successful, this API returns the list of -si (city) or -do (province) information and key values of the corresponding location. You can use the values of description and depth1Name passed in the response for targeting.locations when you create or edit an ad group.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O

Response

Body
NameTypeDescription
-Location[]List of -si (city) or -do (province) information.

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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/targetings/location/depth2Business token

Retrieves a list of -si (city), -gun (county), or -gu (district) information of a specific location.

You can use the information for region targeting when creating or editing an ad group.

Send a GET request with the issued business token in the request header. You must pass the location name you want to search for through the keyword parameter. If the request is successful, this API returns the list of -si (city), -gun (county), or -gu (district) information and key values of the corresponding location. You can use the values of description, depth1Name and depth2Name passed in the response for targeting.depth2Locations when you create or edit an ad group. If you do not pass keyword when you request, the request fails and an error is returned.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
Query parameter
NameTypeDescriptionRequired
keywordStringLocation you want to know its -si, -gun, or -gu information.O

Response

Body
NameTypeDescription
-Depth2Location[]List of -si (city), -gun (county), or -gu information.

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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/targetings/location/depth3Business token

Retrieves a list of -dong (neighborhood), -eup (town), or -myeon (townships) information of a specific location.

You can use the information for region targeting when creating or editing an ad group.

Send a GET request with the issued business token in the request header. You must pass the location name you want to search for through the keyword parameter. If the request is successful, this API returns the list of -dong, -eup, or -myeon information and key values of the corresponding location. You can use the values of description, depth1Name and depth2Name passed in the response for targeting.depth3Locations when you create or edit an ad group. If you do not pass keyword when you request, the request fails and an error is returned.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
Query parameter
NameTypeDescriptionRequired
keywordStringLocation you want to know its -dong, -eup, or -myeon information.O

Response

Body
NameTypeDescription
-Depth3Location[]List of -dong, -eup, or -myeon information.

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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/targetings/placement/adServingCategoriesBusiness token

Retrieves a list of placements.

Send a GET request with the issued business token in the request header. If the request is successful, this API returns the name and code of the sub-categories of the Network placement. You can use the values of code passed in the response for the value of adServingCategories as an array when you create or edit an ad group. You cannot set the Network placement for the Display X Conversion(전환) type of campaign.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O

Response

Body
NameTypeDescription
-NetworkPlacement[]List of the category information for Network placement.
NetworkPlacement
NameTypeDescription
codeStringCategory 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.
nameStringCategory 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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/targetings/placement/sectionCategoriesBusiness token

Retrieves 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.

Send a GET request with the issued business token in the request header. If the request is successful, this API returns the list of selectable section categories. You can use the values of code for the value of sectionCategories as an array when creating or editing an ad group.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O

Response

Body
NameTypeDescription
-SectionCategory[]List of section categories.
SectionCategory
NameTypeDescription
codeStringCode 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.
nameStringName 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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/targetings/cohort/availablesBusiness token

Retrieves a list of engagement targets for custom audience targeting, which you can use as a targeting option when you create or edit an ad group.

Send a GET 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 detailed information and status of available engagement targets. If failed, refer to Error code to figure out its failure cause.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O

Response

Body
NameTypeDescription
-CohortAvailable[]List of engagement targets that can be used for custom audience targeting.
CohortAvailable
NameTypeDescription
idLongEngagement target's ID.
Pass this value through cohortId as the array of targeting.cohortTargetings when creating or editing an ad group.
audienceTypeStringEngagement 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.
adAccountIdLongAd account's ID.
nameStringEngagement target's name.
baseAdsBaseAd[]List of ad response data.
collectDurationIntegerCollecting 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.
statusStringStatus 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.
populationScoreLongTarget population.
createdDateStringDate and time of creation in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDateStringDate 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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/targetings/trackers/eventCreatables/${TRACK_ID}Business token

Retrieves a list of Pixel & SDK events for custom audience targeting, which you can use as a targeting option when you create or edit an ad group.

Send a GET request with the issued business token and an ad account ID (adAccountId) in the request header. You must pass a tracker ID (trackID) and a targeting period (dimensions) when you request. If the request is successful, this API returns the list of tracker information about each event in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
Path variable
NameTypeDescriptionRequired
TRACK_IDStringTracker ID.
Use the id that is retrieved through the Viewing Pixel & SDK API.
O
Query parameter
NameTypeDescriptionRequired
termIntegerTargeting period. (Min: 1, Max: 180)O

Response

Body
NameTypeDescription
-PixelAndSdkEvent[]List of Pixel & SDK events that can be used for custom audience targeting.
PixelAndSdkEvent
NameTypeDescription
eventCodeStringEvent code.
eventNameStringEvent name.
eventExtraNameStringCustom event name.
trackRuleIdStringTracker information ID.
trackRuleTrackRuleTracker rule.
It has no value when eventCode is '모든 이벤트(All events)'.
populationIntegerCollected target population.
lastEventDateStringDate 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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/targetings/customerFiles/availablesBusiness token

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

Send a GET 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 list of customer files in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O

Response

Body
NameTypeDescription
-CustomerFile[]List of customer files information that can be used for custom audience targeting.
CustomerFile
NameTypeDescription
idLongCustomer file's ID.
adAccountIdLongAd account's ID.
nameStringCustomer file's name.
adidListKeyStringCustomer file's registration key.
statusStringStatus.
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.
populationScoreStringTarget 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.
readyBooleanWhether it is ready or not.
createdDateStringDate and time of target creation in yyyy-MM-dd'T'HH:mm:ss format.
lastModifyRequestDateStringDate 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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/targetings/talkChannels/availablesBusiness token

Retrieves a list of Kakao Talk Channel information you can use for the targeting option when you create or edit an ad group.

Send a GET 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 retrieved Kakao Talk Channel information. If failed, refer to Error code to figure out its failure cause.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O

Response

Body
NameTypeDescription
-ChannelProfile[]List of Kakao Talk Channel profile that can be used for custom audience targeting.
ChannelProfile
NameTypeDescription
idStringKakao Talk Channel's profile ID.
nameStringKakao Talk Channel's profile name.
searchIdStringKakao 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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/targetings/syncProfiles/availablesBusiness token

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

Send a GET request with the issued business token and an ad account ID (adAccountId) in the request header. You can use id that is passed in the response for Kakao Login user targeting when creating or editing an ad group. If failed, refer to Error code to figure out its failure cause.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O

Response

Body
NameTypeDescription
-SyncProfile[]List of Kakao Login users that can be used for custom audience targeting.
SyncProfile
NameTypeDescription
idStringKakao Talk Channel's profile ID.
nameStringKakao Talk Channel's profile name.
searchIdStringKakao 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
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/targetings/talkChannelGroupFiles/availablesBusiness token

Retrieves a list of Friend groups that you can use for the targeting option when you create or edit an ad group.

Send a GET 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 list of Friend group information. If failed, refer to Error code to figure out its failure cause.

Request

Header
NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
Query parameter
NameTypeDescriptionRequired
profileIdStringKakao Talk Channel's profile ID.
Campaign's objective value.
O

Response

Body
NameTypeDescription
-TalkChannelGroupFiles[]List of Friend groups that can be used for custom audience targeting.
TalkChannelGroupFiles
NameTypeDescription
idLongFriend group's ID.
nameStringFriend group's name.
profileIdStringKakao Talk Channel's profile ID.
groupKeyStringFriend group file's group key.
fileTypeStringFriend group's type.
One of the followings:
  • APP_USER_ID: Service user ID
  • PHONE_NUMBER: Phone number
  • MESSAGE_RETARGET: Message recipients
appIdIntegerApp ID.
talkChannelGroupFileStatusStringStatus.
One of the followings:
  • WAITING: Pending
  • COMPLETE: Completed
  • DELETE: Deleted
  • ERROR: Failed to create
friendCountLongNumber of friends.
createdDateStringDate and time of target creation in yyyy-MM-dd'T'HH:mm:ss format.
populationUpdateDateStringDate 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

Was this helpful?