사이드 메뉴
Getting started
Kakao Developers
Login
Communication
Advertisement
- Concepts
- Ad creation: Ad account
- Ad creation: Campaign
- Ad creation: Ad group
- Targeting for ad group
- Custom audience targeting for ad group
- Ad creation: Creative common
- Ad creation: Display creative
- Ad creation: Message creative
- Ad creation: Personalized message creative
- Bizboard landing settings
- Report
- Message management
- Personalized message management
- Message ad management
- Message ad operation
- Ad View management
- Business Form linkage management
- Pixel & SDK linkage management
- Audience management
- Engagement targeting management
- Customer file management
- Friend group management
- Ad account management
- Reference
- Type information
- Error code
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.
| 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 |
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| Name | Type | Description |
|---|---|---|
| - | Location[] | List of -si (city) or -do (province) information. |
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 OKContent-Type: application/json;charset=UTF-8[{"value": "A","description": "강원도","depth1Name": "강원도",},{"value": "B","description": "경기도","depth1Name": "경기도",},{"value": "C","description": "경상남도","depth1Name": "경상남도",},...]
| 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 |
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| keyword | String | Location you want to know its -si, -gun, or -gu information. | O |
| Name | Type | Description |
|---|---|---|
| - | Depth2Location[] | List of -si (city), -gun (county), or -gu information. |
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 requestContent-Type: application/json;charset=UTF-8{"code": -813,"msg": "KakaoMomentException","extras": {"detailCode": 75029,"detailMsg": "조회할 시/군/구 검색어를 입력해 주세요."}}
| 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 |
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| keyword | String | Location you want to know its -dong, -eup, or -myeon information. | O |
| Name | Type | Description |
|---|---|---|
| - | Depth3Location[] | List of -dong, -eup, or -myeon information. |
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 requestContent-Type: application/json;charset=UTF-8{"code": -813,"msg": "KakaoMomentException","extras": {"detailCode": 75528,"detailMsg": "조회할 동/읍/면 검색어를 입력해 주세요."}}
| 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 |
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| Name | Type | Description |
|---|---|---|
| - | NetworkPlacement[] | List of the category information for Network placement. |
| 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. |
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 OKContent-Type: application/json;charset=UTF-8[{"code": "IAB16","name": "애완동물"},{"code": "IAB8","name": "식음료"},{"code": "IAB15","name": "과학"},...]
| 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 |
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| Name | Type | Description |
|---|---|---|
| - | SectionCategory[] | List of section categories. |
| 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. |
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 OKContent-Type: application/json;charset=UTF-8[{"code": "KKO99-1","name": "채팅탭에만 노출"}...]
| 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 |
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.
| 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 |
| Name | Type | Description |
|---|---|---|
| - | CohortAvailable[] | List of engagement targets that can be used for custom audience targeting. |
| 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:
|
| 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. |
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 OKContent-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"}]
| 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 |
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.
| 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 |
| Name | Type | Description | Required |
|---|---|---|---|
| TRACK_ID | String | Tracker ID. Use the id that is retrieved through the Viewing Pixel & SDK API. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| term | Integer | Targeting period. (Min: 1, Max: 180) | O |
| Name | Type | Description |
|---|---|---|
| - | PixelAndSdkEvent[] | List of Pixel & SDK events that can be used for custom audience targeting. |
| 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. |
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 OKContent-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}]
| 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 |
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.
| 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 |
| Name | Type | Description |
|---|---|---|
| - | CustomerFile[] | List of customer files information that can be used for custom audience targeting. |
| 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:
|
| 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. |
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 OKContent-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"}]
| 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 |
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.
| 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 |
| Name | Type | Description |
|---|---|---|
| - | ChannelProfile[] | List of Kakao Talk Channel profile that can be used for custom audience targeting. |
| 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. |
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 OKContent-Type: application/json;charset=UTF-8[{"id": "_xbHxd","name": "first_friend","searchId": "first_friend"},{"id": "_ZQxd","name": "second_friend","searchId": "second_friend"}]
| 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 |
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.
| 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 |
| Name | Type | Description |
|---|---|---|
| - | SyncProfile[] | List of Kakao Login users that can be used for custom audience targeting. |
| 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. |
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 OKContent-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"}]
| 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 |
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.
| 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 |
| Name | Type | Description | Required |
|---|---|---|---|
| profileId | String | Kakao Talk Channel's profile ID. Campaign's objective value. | O |
| Name | Type | Description |
|---|---|---|
| - | TalkChannelGroupFiles[] | List of Friend groups that can be used for custom audience targeting. |
| 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:
|
| appId | Integer | App ID. |
| talkChannelGroupFileStatus | String | Status. One of the followings:
|
| 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. |
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 OKContent-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"}]