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

Kakao Moment

Ad creation: Ad account

This document describes how to use the Ad account APIs.

There are two types of ad account — Business ad account and Personal ad account. An advertiser or an agency running ads for the advertiser can create a Business ad account.

View list of ad accounts

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

This API enables you to retrieve a list of ad accounts.

Send a GET request with the issued Business token in the request header. If the request is successful, the response includes a page of ad account information list in the body. To request the next page, increase the value of page. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
Query parameter
Name Type Description Required
config Array Pass the values of ON, OFF, andDEL in a comma-separate string.
(Default: ON, OFF)		 X
page Integer Page number(Default: 0) X
size Integer Number of ad accounts in a page(Default: 10) X

Response

Body
Name Type Description
content AdAccount[] List of ad account information.
number Integer Page number, same as page
size Integer Number of ad accounts in a page
totalElements Integer Total count
totalPages Integer Number of the pages
page Integer Page number
AdAccount
Name Type Description
id Long Ad account's ID.
name String Ad account's name.
memberType MemberType Member type.
Either MASTER (Master role) or MEMBER(Member role).
config Config Ad account's status.

Sample

Request
curl -v -G GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/pages" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -d "config=ON,OFF" \
    -d "page=0" \
    -d "size=2"
Response
{
    "content": [
        {
            "id": 111,
            "name": "TestAccount1",
            "memberType": "MASTER",
            "config": "ON"
        },
        {
            "id": 222,
            "name": "TestAccount2",
            "memberType": "MASTER",
            "config": "ON"
        }
    ],
    "number": 0,
    "size": 2,
    "totalElements": 92,
    "totalPages": 46,
    "page": 0
}

View ad account

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

This API enables you to retrieve detailed information of a specific ad account.

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

This API limits the number of calls you can make to every second per user account per app ID.

Depending on the ad account type, the response is passed differently.

Ad account type ownerCompany advertiser
BUSINESS (Business ad account created by advertiser) O O
BUSINESS (Business ad account created by agency) O Optional
INDIVIDUAL (Personal ad account) X X

Request

Header
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
Path variable
Name Type Description Required
AD_ACCOUNT_ID Long Ad account's ID. O

Response

Body
Name Type Description
id Long Ad account's ID.
name String Ad account's name.
ownerCompany Company Business information of the company that owns the ad account.
advertiser Company Advertiser's business information.
type String Ad account's type.
BUSINESS (Business ad account).
config String Ad account's status.
One of ON, OFF, or DEL (Deleted).
isAdminStop Boolean Whether or not the ad account's administrator is suspended.
isOutOfBalance Boolean Whether or not the account's balance is insufficient.
statusDescription String Status of the ad account.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/${AD_ACCOUNT_ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
Response
{
    "id": 1111,
    "name": "kakao_moment_ad_account",
    "ownerCompany": {
        "businessRegistrationNumber": "120-81-47521",
        "name": "kakao_corporation"
    },
    "advertiser": {
        "businessRegistrationNumber": "120-81-47521",
        "name": "kakao_corporation"
    },
    "type": "BUSINESS",
    "config":"ON",
    "isAdminStop": false,
    "isOutOfBalance": false,
    "statusDescription": "운영중"
}
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 21006,
        "detailMsg": "존재하지 않는 광고계정입니다."
    }
}

View real-time balance

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

This API enables you to retrieve the real-time balance of an ad account.

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

Request

Header
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

Response

Body
Name Type Description
id Long Ad account's ID.
cash Long Cash.
freeCash Long Free cash.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/balance" \
 -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
 -H "adAccountId: ${AD_ACCOUNT_ID}"
Response
{
    "id": 1111,
    "cash": 5000000,
    "freeCash": 100000
}
Response: Fail
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
      "detailCode": 21006,
      "detailMsg": "존재하지 않는 광고계정입니다."
  }
}

View business right

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

This API enables you to retrieve an ad account's business right.

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 name of the company that has a business right in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header
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

Response

Body
Name Type Description
id Long Ad account's ID.
bizRightCompanyName String Name of the company that has a business right.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/bizRight" \
 -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
 -H "AdAccountId: ${AD_ACCOUNT_ID}"
Response
{
  "id": 1111,
  "bizRightCompanyName": "kakao_corporation"
}
Response: Fail
{
 "code": -813,
 "msg": "KakaoMomentException",
 "extras": {
    "detailCode": 21006,
    "detailMsg": "존재하지 않는 광고계정입니다."
 }
}

View list of Kakao Talk Channel profiles

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

This API enables you to retrieve a list of the profiles of Kakao Talk Channels. You can use the value of id passed in the response when you create a campaign as:

  • The object of the campaign with the Conversion goal
  • The object of the campaign with Kakao Talk Channel type

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 a list of respective Kakao Talk Channels' profile information in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header
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

Response

Body
Name Type Description
- ChannelProfile[] List of Kakao Talk Channel profile information.
ChannelProfile
Name Type Description
id String Kakao Talk Channel's profile ID.
name String Kakao Talk Channel's name.
searchId String ID (UUID) used for search on Kakao Talk.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/channel/profiles" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
Response
[
    {
        "id": "_ZQxd",
        "name": "kakao_channel",
        "searchId": "kakao_channel"
    },
    {
        "id": "_Xxju",
        "name": "kakao_channel2",
        "searchId": "kakao_channel2"
    }
]

View Pixel & SDK

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

This API enables you to retrieve a list of Pixel & SDKs linked to your ad account. You can use the value of id passed in the response when you create a campaign with 'Display X Conversion' or 'Kakao Bizboard X Conversion. If the campaign is 'Display X Visit' or 'Kakao Bizboard X Visit', the id is used for conversion tracking.

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

What is Pixel & SDK?

When you install a Pixel & SDK on your website or app, Pixel & SDK collects event logs as you define. Collecting event logs is regardless of the inflows through ad click. You can use the log data for the following purposes:
- Used for a report by separating the inflow through ad clicks. - Used for re-targeting per event. - Used as data to help increase advertising efficiency. (Example: ctr, cvr)

Request

Header
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
Query parameter
Name Type Description Required
campaignType String Value used to set a campaign type.
Use one of CampaignType.		 X
goal String Value used to set a goal.
Use one of Goal.		 X

Response

Body
Name Type Description
id String Pixel & SDK's ID.
name String Pixel & SDK's name.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/trackers?campaignType=TALK_BIZ_BOARD&goal=VISITING" \
 -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
 -H "adAccountId: ${AD_ACCOUNT_ID}"
Response
[
    {
        "id": "1",
        "name": "tracker1"
    },
    {
        "id": "2",
        "name": "tracker2"
    }
]

Create ad account

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

This API enables you to create a new ad account of an advertiser or agency. Only a business account can use this API.

Send a POST request with the issued Business token in the request header. If the request is successful, this API returns the created ad account information. If failed, refer to Error code to figure out its failure cause.

This API limits the number of calls you can make to every second per user account.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
Body
Name Type Description Required
name String Name of the ad account to be created. O
ownerCompanyId Long Business registration number of the company that owns the ad account.
ID retrieved through the Viewing business information API.
In the case of an agency, the agency's business registration number.		 O
advertiserCompanyId Long Advertiser's business registration number.
ID retrieved through the Viewing business information API.		 O*

* In the case of an advertiser, advertiserCompanyId is not required.

Response

Body
Name Type Description
id Long Ad account's ID.
name String Ad account's name.
ownerCompany Company Business information of the company that owns the ad account.
advertiser Company Advertiser's business information.
type String Ad account's type.
Either BUSINESS (Business ad account) or INDIVIDUAL (Personal ad account).
config String Ad account's status.
One of ON, OFF, or DEL (Deleted).
isAdminStop Boolean Whether or not the account's administrator is suspended.
isOutOfBalance Boolean Whether or not the account's balance is insufficient.
statusDescription String Status of the ad account.

Sample

Request
curl -X POST "https://apis.moment.kakao.com/openapi/v4/adAccounts" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
      "name":"test_ad_account",
      "ownerCompanyId": 12,
      "advertiserCompanyId": 34
    }'
Response
{
    "id": 123,
    "name": "test_ad_account",
    "ownerCompany": {
        "businessRegistrationNumber": "123-12-12345",
        "name": "business_owned_by_ad_account"
    },
    "advertiser": {
        "businessRegistrationNumber": "678-67-67890",
        "name": "business_of_advertiser"
    },
    "type": "BUSINESS",
    "config": "ON",
    "isAdminStop": false,
    "isOutOfBalance": true,
    "statusDescription": "잔액부족"
}

Change ad account status

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

This API enables you to change the status of an ad account to ON or OFF. You can only change its status if the ad account's status is ON or OFF. If the requested ad account is in the process of being deleted, you cannot change its status.

If you change the ad account's status to OFF, the delivery status of messages under a Message creative changes as follows:

  • If messages are ready to be sent, the status is changed to 'Sent'.
  • If messages are being sent, the status is changed to 'Paused'.

Send a PUT 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 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 second per user account.

Request

Header
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
Body
Name Type Description Required
config String Ad account's status.
Either ON or OFF.		 O

Sample

Request
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adAccounts/onOff" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "AdAccountId: ${AD_ACCOUNT_ID}" \
    -H "Content-Type: application/json" \
    -d '{
        "config":"ON"
    }'
Response
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8
Response: Fail
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 21400,
        "detailMsg": "광고계정이 삭제처리중입니다."
    }
}

See more

Kakao Moment> Ad creation: Ad account