페이지 이동경로
  • 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

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

Request
URL
GET /openapi/v4/adAccounts 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
Parameter
Name Type Description Required
config Array Status of ad accounts to be retrieved.
enum{ON, OFF, DEL}
Allowed to request multiple status.
(Default: [ON, OFF])
X
Response
Name Type Description
content AdAccount[] List of ad account information.
AdAccount
Name Type Description
id Long Ad account's ID.
name String Ad account's name.
memberType String<MemberType> Member type.
Either MASTER (Master role) or MEMBER(Member role).
config String<Config> Ad account's status.
businessAccount BusinessAccount Business Account Information.
Not returned if there is no associated business account.
Sample
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts?config=ON,OFF,DEL" \
 -H "Authorization: Bearer ${ACCESS_TOKEN}"
Response
{
  "content": 
  [
    {
      "id": 1111,
      "name": "kakao_moment_ad_account1",
      "memberType": "MASTER",
      "config": "ON"
    },
    {
      "id": 1112,
      "name": "kakao_moment_ad_account2",
      "memberType": "MEMBER",
      "config": "OFF"
    }
  ]
}

View ad account

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
URL
GET /openapi/v4/adAccount 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
Response
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).
businessAccount BusinessAccount Business Account Information.
Not returned if there is no associated business 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/{adAccountId}" \
 -H "Authorization: Bearer ${ACCESS_TOKEN}" \
 -H "adAccountId: {adAccountId}"
Response: Success
{
  "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",
  "businessAccount": {
    "businessId": 12345,
    "businessName": "Kakao"
  },
  "config":"ON",
  "isAdminStop": false,
  "isOutOfBalance": false,
  "statusDescription": "운영중"
}
Response: Fail
{
 "code": -813,
 "msg": "KakaoMomentException",
 "extras": {
    "detailCode": 21006,
    "detailMsg": "존재하지 않는 광고계정입니다."
 }
}

View real-time balance

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
URL
GET /openapi/v4/adAccounts/balance 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

  • None
Response
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: {adAccountId}"
Response: Success
{
  "id": 1111,
  "cash": 5000000,
  "freeCash": 100000
}
Response: Fail
{
 "code": -813,
 "msg": "KakaoMomentException",
 "extras": {
    "detailCode": 21006,
    "detailMsg": "존재하지 않는 광고계정입니다."
 }
}

View business right

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
URL
GET /openapi/v4/adAccounts/bizRight 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

  • None
Response
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: {adAccountId}"
Response: Success
{
  "id": 1111,
  "bizRightCompanyName": "kakao_corporation"
}
Response: Fail
{
 "code": -813,
 "msg": "KakaoMomentException",
 "extras": {
    "detailCode": 21006,
    "detailMsg": "존재하지 않는 광고계정입니다."
 }
}

View list of Kakao Talk Channel profiles

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
URL
GET /openapi/v4/adAccounts/channel/profiles 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

  • None
Response
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: {adAccountId}"
Response
[
  {
    "id": "_ZQxd",
    "name": "kakao_channel",
    "searchId": "kakao_channel"
  },
  {
    "id": "_Xxju",
    "name": "kakao_channel2",
    "searchId": "kakao_channel2"
  }
]

View Pixel & SDK

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.

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

URL

GET /openapi/v4/adAccounts/trackers 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
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
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/tracker?campaignType=TALK_BIZ_BOARD&goal=VISITING" \
 -H "Authorization: Bearer ${ACCESS_TOKEN}" \
 -H "adAccountId: {adAccountId}"
Response
[
  {
    "id": "1",
    "name": "tracker1"
  },
  {
    "id": "2",
    "name": "tracker2"
  }
]

Create ad account

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
URL
POST /openapi/v4/adAccounts 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
Parameter
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
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

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
URL
PUT /openapi/v4/adAccounts/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
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: {adAccountId}" \
 -H "Content-Type: application/json" \
 -d '{
      "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": 21400,
    "detailMsg": "광고계정이 삭제처리중입니다."
  }
}   

See more