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

Returns a list of ad accounts.

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`, and`DEL` in a comma-separate string. (Default: `ON, OFF`)	X
page	`Integer`	Page number(Default: 0) Increase the value by 1 to retrieve each next page.	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

Returns detailed information about a specific ad account.

Ad account type

There are two types of ad accounts: business and personal ad accounts.

Ad account	Business information
Business ad account	O
Personal ad account	X

Ad account status

The delivery status of an ad account is determined by the combination of ad account status (config), whether it is suspended by an administrator (isAdminStop), and whether its balance is insufficient (isOutOfBalance).

Current delivery status	Ad account status	Administrator suspension	Insufficient balance
Active	ON	false	false
Insufficient balance	ON	false	true
Suspended by administrator	ON	true	false
Suspended by administrator, insufficient balance	ON	true	true
User OFF	OFF	false	false
User OFF, insufficient balance	OFF	false	true
User OFF, suspended by administrator	OFF	true	false
User OFF, insufficient balance, suspended by administrator	OFF	true	true
Deleted	DEL	-	-

Rate limit

This API limits calls to once per second per user account and app ID.

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.
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.
bizWalletId	`Long`	Business wallet ID linked to 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",
  "advertiser": {
    "businessRegistrationNumber": "120-81-47521",
    "name": "kakao_corporation"
  },
  "type": "BUSINESS",
  "config": "ON",
  "isAdminStop": false,
  "isOutOfBalance": false,
  "statusDescription": "운영중",
  "bizWalletId": 1111
}

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

Returns the real-time balance of an ad 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

Response

Body

Name	Type	Description
id	`Long`	Ad account's ID.
bizWalletId	`Long`	Business wallet ID linked to the ad account.
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,
  "bizWalletId": 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

Returns an ad account's business right.

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": "존재하지 않는 광고계정입니다."
  }
}

Auto-approve business rights

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/${AD_ACCOUNT_ID}/bizRight`	Business token

Permission	Prerequisites	Business authentication	Business consent items
Required: Request permission	Convert to Biz app Register business redirect URI Business consent items	Required	Required

Approves business rights for an ad account.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Authentication method using Business token	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account ID	O

Path variable

Name	Type	Description	Required
AD_ACCOUNT_ID	`Long`	Ad account ID	O

Response

Body

Name	Type	Description
id	`Long`	Ad account number
bizRightCompanyName	`String`	Company name holding the business rights

Example

Request

curl -X POST "https://apis.moment.kakao.com/openapi/v4/adAccounts/${AD_ACCOUNT_ID}/bizRight" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "AdAccountId: ${AD_ACCOUNT_ID}"

Response

{
  "id": 1111,
  "bizRightCompanyName": "Kakao Corp."
}

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

Returns a list of the user's Kakao Talk Channel profiles.

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

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

Returns a list of authorized Pixel & SDKs by type and goal.

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.

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

Creates a new ad account of an advertiser or agency.

Only a business account can use this API.

Rate limit

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
advertiserCompanyId	`Long`	Advertiser's business registration number. ID retrieved through the View 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.
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",
      "advertiserCompanyId": 34
    }'

Response

{
  "id": 123,
  "name": "test_ad_account",
  "advertiser": {
    "businessRegistrationNumber": "678-67-67890",
    "name": "business_of_advertiser"
  },
  "type": "BUSINESS",
  "config": "ON",
  "isAdminStop": false,
  "isOutOfBalance": true,
  "statusDescription": "잔액부족"
}

Response: Fail

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 75105,
    "detailMsg": "ownerCompanyId 정보를 전달하지 않아야 합니다."
  }
}

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

Enables you to change the status of an ad account to ON or OFF.

Conditions for use

The ad account status can be changed only when it is ON or OFF.
The status cannot be changed while the ad account is being deleted.
When the ad account is changed to OFF, the delivery status of its Direct Message Ad creatives changes from ready to delivery ended, or from delivering to delivery paused.

Rate limit

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 API Reference

사이드 메뉴

Getting started

Kakao Developers

Login

Communication

Map

Navigation

Advertisement

Search

More

Ad creation: Ad account

View list of ad accounts

Basic information

Request

Header

Query parameter

Response

Body

AdAccount

Sample

Request

Response

View ad account

Basic information

Ad account type

Ad account status

Rate limit

Request

Header

Path variable

Response

Body

Sample

Request

Response

Response: Fail

View real-time balance

Basic information

Request

Header

Response

Body

Sample

Request

Response

Response: Fail

View business right

Basic information

Request

Header

Response

Body

Sample

Request

Response

Response: Fail

Auto-approve business rights

Basic information

Request

Header

Path variable

Response

Body

Example

Request

Response

View list of Kakao Talk Channel profiles

Basic information

Request

Header

Response

Body

ChannelProfile

Sample

Request

Response

View Pixel & SDK

Basic information

Request

Header