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.

Retrieves 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.

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"

{
  "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
}

Retrieves 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.

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}"

{
  "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
}

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 21006,
    "detailMsg": "존재하지 않는 광고계정입니다."
  }
}

Retrieves 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.

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

{
  "id": 1111,
  "bizWalletId": 1111,
  "cash": 5000000,
  "freeCash": 100000
}

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 21006,
    "detailMsg": "존재하지 않는 광고계정입니다."
  }
}

Retrieves 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.

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

{
  "id": 1111,
  "bizRightCompanyName": "kakao_corporation"
}

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 21006,
    "detailMsg": "존재하지 않는 광고계정입니다."
  }
}

Approves business rights for an ad account.

Send a POST request with the business token and ad account ID (adAccountId) of the approval target. Upon success, the response body returns a JSON object containing business right information. On failure, check the cause in Error codes.

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}"

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

Retrieves 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.

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/channel/profiles" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"

[
  {
    "id": "_ZQxd",
    "name": "kakao_channel",
    "searchId": "kakao_channel"
  },
  {
    "id": "_Xxju",
    "name": "kakao_channel2",
    "searchId": "kakao_channel2"
  }
]

Retrieves 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.

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}"

[
  {
    "id": "1",
    "name": "tracker1"
  },
  {
    "id": "2",
    "name": "tracker2"
  }
]

Creates 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.

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
    }'

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

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

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.

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"
    }'

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 21400,
    "detailMsg": "광고계정이 삭제처리중입니다."
  }
}

• Kakao Moment API Reference