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	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 ad accounts.

Send a GET request with the issued access 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 ${ACCESS_TOKEN} Access 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.
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 ${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"
        }
    ],
    "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}	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 a specific ad account.

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 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 ${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
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 ${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	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 real-time balance of an ad account.

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 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 ${ACCESS_TOKEN} Access 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 ${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	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 an ad account's business right.

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 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 ${ACCESS_TOKEN} Access 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 ${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	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 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 access 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 ${ACCESS_TOKEN} Access 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 ${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	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 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 access 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.

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
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 ${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	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 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 access 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 ${ACCESS_TOKEN} Access 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 ${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	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 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 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 second per user 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
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 ${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