페이지 이동경로
  • Docs>
  • Kakao Moment>
  • Ad creation: Campaign

Kakao Moment

Ad creation: Campaign

This document describes how to use the campaign APIs.

View list of campaigns

This API enables you to retrieve a list of campaigns.

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 an array of each campaign's detailed information in JSON format. If failed, refer to Error code to figure out its failure cause.

Request
URL
GET /openapi/v4/campaigns HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
Name Type Description Required
config String Campaign's status.
Either ON or OFF.
O
Response
Name Type Description
content Campaign[] List of campaign information.
Campaign
Name Type Description
id Long Campaign's ID.
name String Campaign's name.
config String Campaign status.
One of ON, OFF, or DEL (Deleted).
adminStop Boolean Whether or not the administrator is suspended.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/campaigns?config=ON" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response
{
  "content": [
    {
      "id": 1111,
      "name": "Campaign1",
      "type" : "DISPLAY",
      "config": "ON",
      "adminStop": false
    },
    {
      "id": 1112,
      "name": "Campaign2",
      "type": "DISPLAY",
      "config": "OFF",
      "adminStop": false
    }
  ]
}

View campaign

This API enables you to retrieve the detailed information of the specified campaign.

A campaign's status (statusDescription) is determined by the combination of the campaign status(config) and whether the daily budget is exceeded(isDailyBudgetAmountOver).

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 of the campaign in JSON format. If failed, refer to Error code to figure out its failure cause.

Request
URL
GET /openapi/v4/campaigns/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter: Path
Name Type Description Required
id Long Campaign's ID. O
Response
Name Type Description
adAccountId Long Ad account's ID.
id Long Campaign's ID.
name String Campaign's name.
campaignTypeGoal CampaignTypeGoal Campaign Type X Goal.
objective Objective Objective of the advertising goal.
dailyBudgetAmount Long Daily budget.
If not specified, no limitation on the budget.
config String Campaign status.
One of ON, OFF, or DEL (Deleted).
isDailyBudgetAmountOver Boolean Whether or not the daily budget is exceeded.
status String[] Status.
Refer to Status.
statusDescription String Status of the campaign.
trackId String Conversion tracking ID.
adminStop Boolean Whether or not the administrator is suspended.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/campaigns/{id}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response: Success
{
  "id": 1234,
  "name": "Campaign1",
  "campaignType": "DISPLAY",
  "goal": "VIEW",
  "dailyBudgetAmount": 1000000,
  "config":"ON",
  "isDailyBudgetAmountOver": false,
  "status": "LIVE",
  "statusDescription": "운영중"
}
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 31001,
        "detailMsg": "캠페인이 존재하지 않습니다."
    }
}

Create campaign

This API enables you to create a new campaign.

Note that you cannot create the following types of campaign with this API:

  • Sponsored board
  • Daum Shopping
  • Video
  • Kakao Bizboard X Reach(도달)

If you want to create a campaign with the Conversion(전환) goal, first check the id value for the objective in the response of the Viewing list of Kakao Talk Channel profiles API and Viewing Pixel & SDK API.

For the 'Kakao Talk Channel X Reach(도달)' campaign, you must set the Conversion goal to the profile of the Kakao Talk Channel you want to send messages from.

For the campaign strategies, see below:

Tracking options by Type X Goal

Type X Goal Ad objective Conversion tracking settings (전환 추적 설정)
Display X
Visit(방문)
- Optional
Pixel & SDK
Display X
Conversion(전환)
Pixel & SDK Required
Automatically set with the same one set for Ad goal settings of the Pixel & SDK.
Not allowed to set ID manually when creating a campaign.
Required to enter the same ID that is automatically set when creating a campaign.
Display X
Conversion(전환)
Kakao Talk Channel Not allowed to set conversion tracking.
Kakao Bizboard X
Visit(방문)
- Optional
Pixel & SDK
Kakao Bizboard X
Conversion(전환)
Pixel & SDK Required
Automatically set with the same one set for Ad goal settings of the Pixel & SDK.
Not allowed to set ID manually when creating a campaign.
Required to enter the same ID that is automatically set when creating a campaign.
Kakao Bizboard X
Conversion(전환)
Kakao Talk Channel Not allowed to set conversion tracking.
Kakao Talk Channel X
Reach(도달)
Kakao Talk Channel Not allowed to set conversion tracking.

Send a PUT 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 of the created campaign in JSON format. If failed, refer to Error code to figure out its failure cause.

Request
URL
POST /openapi/v4/campaigns HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
Name Type Description Required
name String Campaign's ID.
Character limits: 50 characters
If not specified, the name is automatically set in yyyyMMddHHmm_{TYPE}_{GOAL} format according to the default naming rule of Kakao Moment.
X
campaignTypeGoal CampaignTypeGoal Campaign Type X Goal O
objective Objective Objective of the advertising goal.
Refer to Tracking options by Type X Goal.
O*
dailyBudgetAmount Long Campaign's daily budget.
If not specified, no limitation on the budget.
Not allowed to set for the 'Kakao Talk Channel X Reach' type of campaign.
X
trackId String Conversion tracking ID.
If the campaign's goal is 'Visit(방문)', you can use id that is passed in the response of the Viewing Pixel & SDK API for trackId.
X

* objective: Required only when the corresponding objective type is set.

CampaignTypeGoal
Name Type Description Required
campaignType CampaignType Campaign's type. O
goal Goal Campaign's goal. O
Response
Name Type Description
adAccountId Long Ad account's ID.
id Long Campaign's ID.
name String Campaign's name.
campaignTypeGoal CampaignTypeGoal Campaign Type X Goal.
objective Objective Objective of the advertising goal.
dailyBudgetAmount Long Daily budget.
If not specified, no limitation on the budget.
config String Campaign status.
One of ON, OFF, or DEL (Deleted).
isDailyBudgetAmountOver Boolean Whether or not the daily budget is exceeded.
status String[] Status.
Refer to Status.
statusDescription String Status of the campaign.
trackId String Conversion tracking ID.
adminStop Boolean Whether or not the administrator is suspended.
Sample
Request
curl -X POST "https://apis.moment.kakao.com/openapi/v4/campaigns" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
            "name": "first_campaign",
            "campaignTypeGoal" : {
                "campaignType" : "DISPLAY",
                "goal" : "CONVERSION"
            },
            "objective" : {
                "type" : "TALK_CHANNEL",
                "value" : "abcd1234"
            },
            "dailyBudgetAmount" : 200000
        }'
Response: Success
{
    "id": 54321,
    "name": "Display_Conversion_202006291438",
    "campaignTypeGoal": {
        "campaignType": "DISPLAY",
        "goal": "CONVERSION"
    },
    "objective": {
        "type": "TALK_CHANNEL",
        "value": "_ababc"
    },
    "dailyBudgetAmount": 200000,
    "config": "ON",
    "status": "LIVE",
    "statusDescription": "운영중",
    "trackId": null,
    "adAccountId": 12345,
    "adminStop": false
}
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "status": 400,
        "message": "존재하지 않는 광고계정입니다."
    }
}

Edit campaign

This API enables you to edit the campaign information. You can only edit campaigns except for the 'Sponsored board', 'Daum Shopping', 'Video', or 'Kakao Talk Channel X Reach(도달)' type of campaigns.

To edit a campaign whose goal is set as Conversion, you can edit the campaign after requesting the Viewing list of Kakao Talk Channel profiles and Viewing Pixel & SDK APIs.

In the case of the 'Kakao Talk Channel X Reach(도달)' campaign, you can only change the campaign's name, and the changes in other fields are not applied.

Send a PUT 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 changed information of the campaign in JSON format. If failed, refer to Error code to figure out its failure cause.

Request
URL
PUT /openapi/v4/campaigns HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
Name Type Description Required
id Long Campaign's ID. O
name String Campaign's ID.
If not specified, the previous name is used.
X
dailyBudgetAmount Long Daily budget. X
trackId String Conversion tracking ID.
If the campaign's goal is 'Visit(방문)', use the id that is passed in the response of the Viewing Pixel & SDK API for trackId.
For the campaigns with the other goals, use the existing ID of the campaign to be edited.
* Not required if the existing campaign to be edited does not have an ID.
X
Response
Name Type Description
adAccountId Long Ad account's ID.
id Long Campaign's ID.
name String Campaign's name.
campaignTypeGoal CampaignTypeGoal Campaign Type X Goal.
objective Objective Objective of the advertising goal.
dailyBudgetAmount Long Daily budget.
If not specified, no limitation on the budget.
config String Campaign status.
One of ON, OFF, or DEL (Deleted).
isDailyBudgetAmountOver Boolean Whether or not the daily budget is exceeded.
status String[] Status.
Refer to Status.
statusDescription String Status of the campaign.
trackId String Conversion tracking ID.
adminStop Boolean Whether or not the administrator is suspended.
Sample
Request
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/campaigns" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
            "id": 5678,
            "name" : "edit_first_campaign",
            "dailyBudgetAmount":100000,
            "trackId":null
        }'
Response
{
    "adAccountId": 1234,
    "id": 5678,
    "name": "OpenApiCampaign",
    "campaignTypeGoal": {
        "campaignType": "DISPLAY",
        "goal": "VISITING"
    },
    "dailyBudgetAmount": 400000,
    "config": "ON",
    "status": "LIVE",
    "statusDescription": "운영중",
    "trackId": 54321234567890,
    "adminStop": false
}

Edit daily budget for Display campaign

This API enables you to change the daily budget for a Display campaign. You cannot change the daily budget of the following types of campaign:

  • 'Kakao Talk Channel' or 'Daum Shopping' type of campaign whose goal is set to 'Reach(도달)'
  • 'Video' type of campaign
  • 'Kakao Bizboard X Reach(도달)' type of campaign

You can set the campaign's daily budget from 50,000 to 1 billion won (South Korean won) in multiples of 10 won. If you change the daily budget to a lower value than the daily budget saved previously, the following rules are applied:

  • If the ad group's daily budget exceeds the changed daily budget for campaign,
    → the changed campaign daily budget is applied.
  • If the ad group's maximum bid amount exceeds 50 % of the daily budget of the ad group to be changed,
    → 50% of the changed ad group's daily budget is applied.
  • If the creative's bid amount exceeds the changed ad group's maximum bid amount,
    → the maximum bid amount of the changed ad group is applied.

Send a PUT request with the issued access token and an ad account ID (adAccountId) in the request header. If you do not set the daily budget for a campaign, there is no limitation on the budget. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

This API limits the number of calls you can make to every five seconds per user account and ad account.

Request
URL
PUT /openapi/v4/campaigns/dailyBudgetAmount HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
Name Type Description Required
id Long Campaign's ID. O
dailyBudgetAmount Long Campaign's daily budget.
Allowed to set a value between 50,000 and 1 billion won in multiples of 10 won.
Allowed to set to null.
X
Sample
Request: Setting campaign daily budget
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/campaigns/dailyBudgetAmount" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
            "id": 5678,
            "dailyBudgetAmount": 5000000
        }'
Request: Setting campaign daily budget to null
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/campaigns/dailyBudgetAmount" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
            "dailyBudgetAmount" : null
        }'
Response: Success
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 31011,
        "detailMsg": "캠페인 일예산은 최소 50,000보다 크거나 같아야 합니다."
    }
}

Change campaign status

This API enables you to change the status of the specified campaign. You can only change its status if the campaign status is ON or OFF. You cannot change the status of the 'Daum Shopping', 'Video', or 'Kakao Bizboard X Reach(도달)' type of campaign.

In the case of the 'Kakao Talk Channel X Reach(도달)' campaign, all ad groups under the campaign must be 'OFF' or 'Contract canceled'. If you request to change the status of the campaign with the 'Kakao Talk Channel X Reach(도달)' type, the messages being sent are stopped and the messages scheduled to be sent are canceled.

Send a PUT 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 HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

This API limits the number of calls you can make to every five seconds per user account and ad account.

Request
URL
PUT /openapi/v4/campaigns/onOff HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
Name Type Description Required
id Long Campaign's ID. O
config String Campaign's status.
Either ON or OFF.
O
Sample
Request
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/campaigns/onOff" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
            "id": 5678,
            "config" : "ON"
        }'
Response: Success
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 31001,
        "detailMsg": "캠페인이 존재하지 않습니다."
    }
}

Delete campaign

This API enables you to delete a campaign.

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

IMPORTANT

Deleting a campaign means giving up the operation of sub-campaigns, not deleting its data. You cannot delete the 'Sponsored board', 'Kakao Bizboard X Reach(도달)', 'Daum Shopping', or 'Video' type of campaigns.

After deleting a campaign: - You cannot use all functions related to the campaign, such as editing and suspending campaigns. - All ads in the campaign are stopped running and displaying. - All creatives under the campaign are deleted. - However, you can still view the statistics in the past operation time.

Request
URL
DELETE /openapi/v4/campaigns/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter: Path
Name Type Description Required
id Long Campaign's ID. O
Sample
Request
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/campaigns/{id}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json"
Response: Success
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8
Response: Fail
HTTP/1.1 400 Bad request
Content-Type: application/json;charset=UTF-8
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 75006,
        "detailMsg": "카카오톡 채널_도달 캠페인은 삭제할 수 없습니다.",
        "path": "/v2/moment/campaigns",
        "timestamp": "2018-10-01T10:16:14.294+0000"
    }
}

View reason for admin suspension

This API enables you to retrieve the suspension reason of a specified campaign's administrator. Only when the campaign's administrator is suspended, the response is returned. If there are multiple reasons for admin suspension, the most recent admin suspension reason is returned.

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 admin's suspension reason and details in JSON format. If failed, refer to Error code to figure out its failure cause.

Request
URL
GET /openapi/v4/campaigns/{id}/adminStopHistory HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter: Path
Name Type Description Required
id Long Campaign's ID. O
Response
Name Type Description
id Long Admin suspension ID.
adminStopReason String Admin suspension reason.
createdDate String Date and time when the admin suspension reason is created in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate String Date and time when the admin suspension reason is lastly updated in yyyy-MM-dd'T'HH:mm:ss format.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/campaigns/{id}/adminStopHistory" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response: Success
{
  "id": 1234,
  "adminStopReason": "기존에 설정된 소재 입찰금액 상세 설정이 지원종료되어 광고등록이 보류되었습니다"
}
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 31001,
        "detailMsg": "캠페인이 존재하지 않습니다."
    }
}

View list of reasons for admin suspension

This API enables you to retrieve the suspension reasons of a specified campaign's administrator. Only when the campaign's admin is suspended, the response is returned.

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 the admin's suspension reasons and details in JSON format. If failed, refer to Error code to figure out its failure cause.

Request
URL
GET /openapi/v4/campaigns/{id}/adminStopHistories HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter: Path
Name Type Description Required
id Long Campaign's ID. O
Response
Name Type Description
- AdminStopReason[] List of admin suspension reason.
AdminStopReason
Name Type Description
id Long Admin suspension ID.
adminStopReason String Admin suspension reason.
createdDate String Date and time when the admin suspension reason is created in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate String Date and time when the admin suspension reason is lastly updated in yyyy-MM-dd'T'HH:mm:ss format.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/campaigns/{id}/adminStopHistory" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response: Success
[
  {
    "id": 1235,
    "adminStopReason": "기존에 설정된 소재 입찰금액 상세 설정이 지원종료되어 광고등록이 보류되었습니다",
    "createdDate": "2021-01-02T00:00:00",
    "lastModifiedDate": "2021-01-02T00:00:00"
  },
  {
    "id": 1234,
    "adminStopReason": "기존에 설정된 소재 입찰금액 상세 설정이 지원종료되어 광고등록이 보류되었습니다",
    "createdDate": "2021-01-01T00:00:00",
    "lastModifiedDate": "2021-01-01T00:00:00"
  }
]
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 31001,
        "detailMsg": "캠페인이 존재하지 않습니다."
    }
}

See more