페이지 이동경로
  • Docs>
  • Kakao Moment>
  • Targeting for ad group

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 Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve a list of -si (city) or -do (province) information you can use for region targeting.

Send a GET request with the issued access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access token as a type of user authentication.
O

Response

Body
Name Type Description
- 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 ${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 Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve 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 access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/location/depth2?keyword=서울" \
    -H "Authorization: Bearer ${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 Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve 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 access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/location/depth3?keyword=논현" \
    -H "Authorization: Bearer ${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 Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve a list of placements.

Send a GET request with the issued access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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 ${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 Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve 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 access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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 ${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 Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve 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 access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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.
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 ${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} Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve 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 access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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 Viewing 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 Additional description for the event.
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 ${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,
        "eventExtraName": ""
    },
    {
        "trackRule": {
            "trackRuleId": "*",
            "trackId": "3830610710806837838",
            "eventCode": "PageView",
            "name": "visit",
            "ruleSetStr": "[]"
        },
        "lastEventDate": "2019.10.16 19:36",
        "eventCode": "PageView",
        "eventName": "visit",
        "trackRuleId": "*",
        "population": 15290918,
        "eventExtraName": ""
    }
]

View list of targetable customer files

Basic information
Method URL Authorization
GET https://apis.moment.kakao.com/openapi/v4/adGroups/targetings/customerFiles/availables Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve 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 access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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.
lastModifiedDate 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 ${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",
        "lastModifiedDate": "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 Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve 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 access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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 ${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 Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve 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 access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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.
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 ${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 Access token
Permission Prerequisite Kakao Login User consent
Required Register platforms
Activate Kakao Login
Switch to a Biz app
Required -

This API enables you to retrieve 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 access 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
Name Description Required
Authorization Authorization: Bearer ${ACCESS_TOKEN}
Access 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
createdDate String Date and time of target creation in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate String Date and time of target modification 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 ${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",
        "lastModifiedDate": "2022-07-25T16:50:30",
        "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",
        "lastModifiedDate": "2022-06-10T14:33:30",
        "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",
        "lastModifiedDate": "2020-08-10T17:50:36"
    }
]

See more