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

Kakao Moment

Ad creation: Creative

This document describes how to use the Creative APIs.

View list of creatives

Basic information
Method URL Authorization
GET https://apis.moment.kakao.com/openapi/v4/creatives 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 creatives.

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 detailed information on creatives 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
Query parameter
Name Type Description Required
adGroupId Long Ad group's ID. O
config Array Creative's status.
Use one or more of the followings:
ON
OFF
DEL
(Default: [ON, OFF])		 X

Response

Body
Name Type Description
content Creative[] List of creative information.
Creative
Name Type Description
id Long Creative's ID which is assigned to a creative when the creative is initially created.
name String Creative's name.
config String Creative's status.
One of ON, OFF, or DEL (Deleted).
systemConfig String Creative's system status.
One of ON, VOID, or ADMIN_STOP.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives?adGroupId=1234&config=ON" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
Response
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
  "content": [
    {
      "id": 1111,
      "name": "creative1",
      "type": "DISPLAY",
      "config": "ON"
    },
    {
      "id": 1112,
      "name": "creative2",
      "type": "DISPLAY",
      "config": "OFF"
    }
  ]
}

View creative

Basic information
Method URL Authorization
GET https://apis.moment.kakao.com/openapi/v4/creatives/${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 detailed information of the specified creative.

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 ad creatives by type in JSON format. It may take a while for the materials for verification to get the response due to syncing with review processing. If syncing is not completed, null is returned. If failed, refer to Error code to figure out its failure cause.

A new field 'hasExpandable' added

On August 3, 2021, a new field that checks if Expandable is included in a creatvie information. You can create an Expandable component only with the permitted ad account. This field is supported only in the response of the Viewing creative and Report APIs.

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
ID Long Creative's representative ID, which is assigned to a creative when the creative is initially created. O

Response

Body: Display creative
Key Type Description
id Long Creative's representative ID.
Identification number assigned to a creative when the creative is initially created.
creativeId Long Creative's ID.
Identification number assigned to a creative when the creative is modified, which is used for delivery.
name String Creative's name.
format String Creative's type.
One of IMAGE_BANNER, IMAGE_NATIVE, VIDEO_NATIVE, or SERVICE_CONTENT.
pcLandingUrl String Landing URL for PC.
mobileLandingUrl String Landing URL for mobile.
rspvLandingUrl String Responsive landing URL.
frequencyCap Integer Frequency capping.
config String Creative's status.
One of ON, OFF, or DEL (Deleted).
systemConfig String Creative's system status.
One of ON, VOID, or ADMIN_STOP.
reviewStatus String Review status.
One of the followings:
- APPROVED: Review approved.
- WAITING Review in progress.
- REJECTED: Review rejected.
- MODIFICATION_WAITING: Review for modification in progress.
- MODIFICATION_REJECTED: Review for modification rejected.
creativeStatus String Creative's operation status.
One of the followings:
OPERATING: Possible to opearate
UNAPPROVED: Unapproved
INVALID_DATE: Invalid date
MONITORING_REJECTED: Rejected while monitoring.
OFF: User OFF
DELETED: Deleted
ADGROUP_UNAVAILABLE: Impossible to operate ad group
SYSTEM_CONFIG_VOID: Impossible to operate content.
SYSTEM_CONFIG_ADMIN_STOP: Admin suspended.
statusDescription String Current status of creative.
image Image Information about the main image of the IMAGE_BANNER, IMAGE_NATIVE, and VIDEO_NATIVE type of creative.
landingInfo LandingInfo Specified data for landing.
serviceContent ServiceContent Content information about the SERVICE_CONTENT type of creative.
altText String Alternative description of the IMAGE_NATIVE type of creative.
title String Title of the IMAGE_NATIVE or VIDEO_NATIVE type of creative.
description String Promotional text of the IMAGE_NATIVE or VIDEO_NATIVE type of creative.
actionButton String Call-to-action button of the IMAGE_NATIVE and VIDEO_NATIVE type of creative.
profileName String Profile name of the IMAGE_NATIVE or VIDEO_NATIVE type of creative.
profileImage Image Uploaded profile image.
video Video Video of the VIDEO_NATIVE type of creative.
videoSkippableType String Video display type of the VIDEO_INSTREAM type of creative.
SECONDS_5: Impressed for 5 seconds at most.
SECONDS_15: Impressed for 15 seconds at most.
rejectedReason RejectedReason[] Reasons for rejection of creative.
assetGroups AssetGroup[] Slide item information.
hasExpandable Boolean Whether or not Expandable component is included.
opinion String Opinion for ad verification.
opinionProof OpinionFile[] List of materials for ad verification.
createdDate String Date and time when the creative is created.
lastModifiedDate String Date and time when the creative is lastly modified.
ageVerification Boolean Whether to use age verification messages.
true: Age verification message used.
false: General message used.
Body: Message creative
Name Type Description
id Long Creative's representative ID.
Identification number assigned to a creative when the creative is initially created.
creativeId Long Creative's ID.
Identification number assigned to a creative when the creative is modified, which is used for delivery.
name String Creative's name.
adGroupId Long Ad group's ID.
format String Creative's type.
One of the followings:
BASIC_TEXT_MESSAGE
WIDE_MESSAGE
WIDE_LIST_MESSAGE
CAROUSEL_COMMERCE_MESSAGE
CAROUSEL_FEED_MESSAGE
PREMIUM_VIDEO_MESSAGE
config String Creative's status.
One of ON, OFF, or DEL (Deleted).
systemConfig String Creative's system status.
One of ON, VOID, or ADMIN_STOP.
statusDescription String Current status of a KakaoTalkChannel X Reach ad group.
One of the followings:- 발송 대기: Ready
- 발송중: Sending
- 발송중지: Paused
- 발송종료: Finished.
creativeStatus String Creative's operation status.
One of the followings:
- OPERATING: Possible to opearate.
- UNAPPROVED: Unapproved.
- INVALID_DATE: Invalid date.
- MONITORING_REJECTED: Admin suspended.
- OFF: User OFF.
- DELETED: Deleted.
- ADGROUP_UNAVAILABLE: Impossible to operate ad group.
createdDate String Date and time when the creative is created.
lastModifiedDate String Date and time when the creative is lastly modified.
messageElement MessageElement Detailed information about Message creative.
ageVerification Boolean Whether to use age verification messages.
true: Age verification message used.
false: General message used.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
Response
Display creative
Message creative
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1111,
    "name": "Display Ad Creative",
    "landingInfo": {
        "landingType": "AD_VIEW",
        "communicatorAdViewId": 1
    },
    "format": "IMAGE_BANNER",
    "landingUrl": "http://www.daum.net",
    "frequencyCapType": "DAY_IMP",
    "frequencyCap": 3,
    "config": "ON",
    "image": {
        "url": "http://xxx.kakao.co.kr/sample.jpg",
        "fileName": "sample.jpeg",
        "width": 640,
        "height": 100,
        "size": 50000
    },
    "reviewStatus": "REJECTED",
    "creativeStatus": "UNAPPROVED",
    "statusDescription": "심사보류",
    "rejectedReason": [
        {
            "rejectedTitle": "공통1>가격 불일치",
            "rejectedContent": "등록하신 광고 소재 내 가격 정보가 랜딩페이지 내 실제 판매금액과 일치하지 않아 광고 등록이 보류되었습니다.\n* 광고 소재 내 가격 정보 : 39,800\n* 랜딩 페이지 내 가격 정보 : 49,800\n - 수정방법 : 모든 이용자가 구매 가능한 정확한 가격을 기재해 주시기 바랍니다."
        }
    ],
    "createdDate": "2020-01-01T00:00:00",
    "lastModifiedDate": "2020-01-01T01:00:00",
    "hasExpandable" : false
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 12345,
    "creativeId": 12345,
    "name": "KakaoTalkChannel_Reach_20210623",
    "adGroupId": 39656,
    "format": "WIDE_LIST_MESSAGE",
    "config": "ON",
    "statusDescription": "발송 종료",
    "creativeStatus": "OPERATING",
    "createdDate": "2021-06-23T13:26:53",
    "lastModifiedDate": "2021-06-23T13:26:54",
    "messageElement": {
        "id": 12345,
        "adAccountId": 123,
        "profileId": "_xbHxd",
        "name": "KakaoTalkChannel_Reach_20210623",
        "creativeFormat": "WIDE_LIST_MESSAGE",
        "title": "widelist_promotional_text",
        "shareFlag": true,
        "adFlag": true,
        "buttonAssetGroups": [
            {
                "ordering": 0,
                "title": "button1",
                "pcLandingUrl": "http://www.daum.net",
                "mobileLandingUrl": "https://www.kakaocorp.com",
                "landingType": "LANDING_URL"
            }
        ],
        "itemAssetGroups": [
            {
                "ordering": 0,
                "image": {
                    "fileSize": 168816,
                    "url": "//beta.daumcdn.net/b2/creative/759/dca51ee4c3fc2248999e7a770563b98d.jpg",
                    "imageWidth": 1280,
                    "imageHeight": 720,
                    "mimeType": "image/jpeg",
                    "imageHash": "35156f0c1393434ced4be21423d08a6a"
                },
                "title": "title1",
                "mobileLandingUrl": "https://www.kakaocorp.com",
                "landingType": "LANDING_URL"
            },
            {
                "ordering": 1,
                "image": {
                    "fileSize": 168816,
                    "url": "//beta.daumcdn.net/b2/creative/759/03b324a5e0a5fc29a8df001af6737279.jpg",
                    "imageWidth": 1280,
                    "imageHeight": 720,
                    "mimeType": "image/jpeg",
                    "imageHash": "35156f0c1393434ced4be21423d08a6a"
                },
                "title": "title2",
                "mobileLandingUrl": "https://www.kakaocorp.com",
                "landingType": "LANDING_URL"
            },
            {
                "ordering": 2,
                "image": {
                    "fileSize": 168816,
                    "url": "//beta.daumcdn.net/b2/creative/759/9248be0ea852f655b03294ea7435d09d.jpg",
                    "imageWidth": 1280,
                    "imageHeight": 720,
                    "mimeType": "image/jpeg",
                    "imageHash": "35156f0c1393434ced4be21423d08a6a"
                },
                "title": "title3",
                "mobileLandingUrl": "https://www.kakaocorp.com",
                "landingType": "LANDING_URL"
            }
        ],
        "thumbnailUrl": "//beta.daumcdn.net/b2/creative/759/dca51ee4c3fc2248999e7a770563b98d.jpg",
        "messageThumbnail": {
            "fileSize": 168816,
            "url": "//beta.daumcdn.net/b2/creative/759/dca51ee4c3fc2248999e7a770563b98d.jpg",
            "imageWidth": 1280,
            "imageHeight": 720,
            "mimeType": "image/jpeg",
            "imageHash": "35156f0c1393434ced4be21423d08a6a"
        },
        "createdDate": "2021-06-23T13:26:53",
        "lastModifiedDate": "2021-06-23T13:26:54"
    }
}
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33003,
        "detailMsg": "소재가 존재하지 않습니다."
    }
}

Change creative status

Basic information
Method URL Authorization
PUT https://apis.moment.kakao.com/openapi/v4/creatives/onOff 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 change a creative's status. You can only change the status of display creatives. You cannot change the status of creatives under the 'Kakao Talk Channel' type of campaign.

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

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
Body
Name Type Description Required
id Long Creative's ID which is assigned to a creative when the creative is initially created. O
config String Creative's status.
Either ON or OFF.		 O

Sample

Request
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/creatives/onOff" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "Content-Type: application/json" \
    -d '{
            "id": 1234,
            "config": "ON"
        }'
Response
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8
Response: Fail
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33003,
       "detailMsg": "소재가 존재하지 않습니다."
    }
}

Delete creative

Basic information
Method URL Authorization
DELETE https://apis.moment.kakao.com/openapi/v4/creatives/${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 delete a creative.

Send a DELETE request with the issued access token and an ad account ID (adAccountId) in the request header. You must pass the creative'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.

Note

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

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
ID Long Creative's ID which is assigned to a creative when the creative is initially created. O

Sample

Request
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "Content-Type: application/json"
Response
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 75008,
        "detailMsg": "카카오톡 채널_도달 소재는 삭제할 수 없습니다.",
        "path": "/v2/moment/creatives",
        "timestamp": "2020-04-01T10:16:14.294+0000"
    }
}

View reason for system stop

Basic information
Method URL Authorization
GET https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistory 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 the reason why the specified creatvie's system is stopped. Only when the creative's systemConfig is ADMIN_STOP or VOID, 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 system suspension reason and details 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
ID Long Creative's ID which is assigned to a creative when the creative is initially created. O

Response

Body
Name Type Description
id Long System suspension ID.
systemConfig String System suspension status.
One of the followings:
ON: Normal
VOID: Content error
ADMIN_STOP: Admin suspended
reason String System suspension reason.
createdDate String Date and time when the system suspension reason is created in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate String Date and time when the system 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/creatives/${ID}/systemConfigHistory" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
Response
{
    "id": 1234,
    "systemConfig": "ADMIN_STOP",
    "adminStopReason": "has been suspended due to the end of the creative landing.",
    "createdDate": "2021-01-01T00:00:00",
    "lastModifiedDate": "2021-01-01T00:00:00"
}
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33003,
        "detailMsg": "Creative does not exist."
    }
}

View list of reasons for system stop

Basic information
Method URL Authorization
GET https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistories 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 the list of reasons why the specified creatvie's system is stopped. Only when the creative's systemConfig is ADMIN_STOP or VOID, 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 admin suspension reasons and details 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
ID Long Creative's ID which is assigned to a creative when the creative is initially created. O

Response

Body
Name Type Description
- SystemStopReason[] List of system suspension reason.
SystemStopReason
Name Type Description
id Long System suspension ID.
systemConfig String System suspension status.
One of the followings:
ON: Normal
VOID: Content error
ADMIN_STOP: Admin suspended
reason String System suspension reason.
createdDate String Date and time when the system suspension reason is created in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate String Date and time when the system 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/creatives/${ID}/systemConfigHistories" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
Response
[
    {
        "id": 1235,
        "systemConfig": "ADMIN_STOP",
        "adminStopReason": "has been suspended due to the end of the creative landing.",
        "createdDate": "2021-01-01T00:00:00",
        "lastModifiedDate": "2021-01-01T00:00:00"
    },
    {
        "id": 1234,
        "systemConfig": "ADMIN_STOP",
        "adminStopReason": "has been suspended due to the end of the creative landing.",
        "createdDate": "2021-01-01T00:00:00",
        "lastModifiedDate": "2021-01-01T00:00:00"
    }
]
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33003,
        "detailMsg": "Creative does not exist."
    }
}

See more

Kakao Moment> Ad creation: Creative common