카카오 모먼트 API

카카오 모먼트 API는 카카오 모먼트 플랫폼의 광고계정, 캠페인, 광고그룹, 소재와 관련된 설정 정보를 API를 통해 조회하고 이와 관련된 성과 지표를 확인할 수 있는 기능을 제공합니다. 또한, 광고계정, 캠페인, 광고그룹, 소재에 대한 ON/OFF 및 일예산, 입찰금액 등을 변경할 수 있는 기능을 제공합니다.
카카오 모먼트 API는 인증받은 카카오 계정이 광고계정의 마스터/멤버 권한을 가진 경우에 한해 사용할 수 있습니다.
현재 해당 API는 공식 대행사로 인증받은 대행사에서 사용하실 수 있습니다. 사용권한이 필요하신 대행사에서는 공식 대행사 계약을 진행한 카카오 담당자에게 문의부탁드립니다.

현재 제공되는 카카오 모먼트 API는 다음과 같습니다.

용어설명

용어
용어 설명
광고계정 광고계정은 광고집행을 관리하는 단위로, 광고주가 직접 생성하거나 광고 운영을 대행하는 대행사가 직접 생성할 수 있습니다. 대행사에서 광고계정을 생성할 경우 광고주 정보를 별도로 기입할 수 있습니다. 광고계정의 사업자 정보는 세금계산서 발행정보의 기준이 됩니다. 카카오 모먼트는 카카오계정으로 광고계정을 생성하며, 사업부서, 서비스종류 등 경우에 따라 하나의 카카오계정에 최대 1,000개의 광고계정을 생성할 수 있습니다.
캠페인 디스플레이광고의 광고목적 또는 메시지광고의 발송 방식을 선택할 수 있으며, 전략에 따라 다수의 캠페인을 운영할 수 있습니다.
광고그룹 캠페인 하위에 광고그룹을 생성할 수 있으며, 광고그룹별로 타겟, 게재설정, 입찰금액, 기간 등 상세한 전략 설정이 가능합니다.
소재 디스플레이광고는 네이티브/배너/동영상광고의 소재 등록이 가능하며, 소재 단위별로 입찰금액 및 프리퀀시 캡 설정이 가능합니다. 메시지 광고는 소재로 사용할 메시지를 선택할 수 있습니다.
디스플레이 네이티브, 배너, 동영상 등 다양한 크리에이티브를 원하는 사용자에게 노출할 수 있는 광고 유형입니다.
온타임 메시지 광고 집행기간 동안 설정한 타겟별로 현재 상황에 맞추어 발송하는 메시지입니다. 타겟 설정 시 모먼트, 데모그래픽(성, 연령)을 활용할 수 있으며 원하는 금액으로 입찰(최소 입찰 비용 20원)하여 다른 온타임 메시지와 실시간으로 경쟁하여 발송합니다.
다이렉트 메시지 일시를 지정하여 설정한 타겟에게 한 번에 발송하는 메시지입니다. 타겟 설정 시 맞춤타겟, 데모그래픽, 상세타겟을 활용할 수 있으며 타겟 설정 여부에 따라 단가가 달라집니다. 맞춤타겟과 데모그래픽 타게팅이 가능하며, 타게팅이 적용되지 않은 경우 건당 15원, 타게팅이 적용된 경우 건당 20원입니다.

사용하는 ID
이름 설명
adAccountId 광고계정 번호
campaignId 캠페인 번호
adGroupId 광고그룹 번호
creativeId 소재 번호

공통 에러 코드

에러 코드에 대한 정보는 카카오 디벨로퍼스 가이드 문서를 참고합니다.

HTTP 상태 코드

상태 코드 설명 비고
200 성공
400 실패 일반적인 오류. 주로 API에 필요한 필수 파라미터와 관련
401 실패 인증 오류. 주로 사용자 토큰과 관련
403 실패 권한/퍼미션등의 오류
500 실패 시스템 오류
502 실패 시스템 오류
503 실패 서비스 점검중

대표 상세 코드

코드 설명 HTTP 상태 코드
-2 잘못된 파라미터. 호출 인자값이 잘못되었거나 필수 인자가 포함되지 않은 경우 400
-3 지원되지 않는 서비스 API에 대한 호출. 해당 앱의 호출된 API가 설정에서 off되어 있을 경우 400
-5 해당 API에 대한 권한/퍼미션이 없는 경우 403
-10 허용된 요청 횟수가 초과된 경우 400
-101 해당 앱에 연결이 되지 않은 사용자의 요청. 로그인 기반 API의 경우 앱 연결이 선행되어야 함 400
-813 카카오 광고 API 호출시 에러가 있을 경우 400

예시

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

API 목록

1. 광고계정

1.1 광고계정 리스트 조회

[Request]

GET /v1/moment/adAccounts HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터 값과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
config 광고계정 상태, 복수선택 (default : [ON, OFF])
enum{ON, OFF, DEL}
X Array

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/adAccounts?config=ON,OFF,DEL' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 리스트로 포함합니다.

Key 설명 Type
id 광고계정 번호 Long
name 광고계정명 String
memberType 멤버 타입
MASTER(마스터 권한), MEMBER(멤버 권한) 중 하나
String
config 광고계정 상태
enum{ON, OFF, DEL}
String

예시

{
  "content": [
    {
      "id": 1111,
      "name": "카카오모먼트_광고계정1",
      "memberType": "MASTER",
      "config": "ON"
    },
    {
      "id": 1112,
      "name": "카카오모먼트_광고계정2",
      "memberType": "MEMBER",
      "config": "OFF"
    }
  ]
}

1.2. 광고계정 조회

[Request]

GET /v1/moment/adAccount HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
adAccountId 광고계정 번호 O Long

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/adAccount?adAccountId=1234' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 리스트로 포함합니다.

Key 설명 Type
id 광고계정 번호 Long
name 광고계정명 String
ownerCompany 광고계정 소유 사업자 정보 Company
advertiser 광고주 사업자 정보 Company
type 광고계정 유형
BUSINESS(사업자 광고계정), INDIVIDUAL(개인 광고계정) 중 하나
String
config 광고계정 상태
ON, OFF, DEL(삭제) 중 하나
String
isAdminStop 관리자 정지 여부 Boolean
isOutOfBalance 잔액부족 여부 Boolean
statusDescription 광고계정의 게재와 관련된 현재 상태 String

Company

Key 설명 Type
businessRegistrationNumber 사업자 번호 String
name 사업자명 String

예시

{
  "id": 1111,
  "name": "카카오모먼트_광고계정",
  "ownerCompany": {
    "businessRegistrationNumber": "120-81-47521",
    "name": "주식회사 카카오"
  },
  "advertiser": {
    "businessRegistrationNumber": "120-81-47521",
    "name": "주식회사 카카오"
  },
  "type": "BUSINESS",
  "config":"ON",
  "isAdminStop": false,
  "isOutOfBalance": false,
  "statusDescription": "운영중"
}

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
21006 존재하지 않는 광고계정입니다.

예시

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

Note

  • 광고계정은 사업자 광고계정, 개인 광고계정 두 가지 종류가 있습니다.
광고계정 광고계정 소유 사업자 정보 광고계정 사업자 정보
사업자 광고계정
(광고주 생성)
O O
사업자 광고계정
(대행사 생성)
O optional
개인 광고계정 X X
  • 광고계정의 게재와 관련된 상태는 광고계정 상태(config), 관리자정지 여부(isAdminStop), 잔액부족 여부(isOutOfBalance) 조합으로 만들어집니다.
광고계정의 게재와 관련된 현재 상태 광고계정 상태 관리자정지 여부 잔액부족 여부
운영중 ON false false
잔액부족 ON false true
관리자정지 ON true false
관리자정지, 잔액부족 ON true true
사용자OFF OFF false false
사용자OFF, 잔액부족 OFF false true
사용자OFF, 관리자정지 OFF true false
사용자OFF, 잔액부족, 관리자정지 OFF true true
삭제됨 DEL - -

1.3. 광고계정 실시간 잔액 조회

[Request]

GET /v1/moment/adAccount/balance HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
adAccountId 광고계정 번호 O Long

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/adAccount/balance?adAccountId=1234' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 리스트로 포함합니다.

Key 설명 Type
id 광고계정 번호 Long
cash 유상캐시 Long
freeCash 무상캐시 Long

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

detailCode detailMsg
21006 존재하지 않는 광고계정입니다.

예시

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

1.4. 광고계정 영업권 조회

[Request]

GET /v1/moment/adAccount/bizRight HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
adAccountId 광고계정 번호 O Long

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/adAccount/bizRight?adAccountId=1234' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 리스트로 포함합니다.

Key 설명 Type
id 광고계정 번호 Long
bizRightCompanyName 영업권 가진 사업자명 String

예시

{
  "id": 1111,
  "bizRightCompanyName": "주식회사 카카오"
}

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

detailCode detailMsg
21006 존재하지 않는 광고계정입니다.

예시

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

1.5. 광고계정 ON/OFF 수정

[Request]

PUT /v1/moment/adAccount/onOff HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
adAccountId 광고계정 번호 O Long
config ON, OFF 중 하나 O String

예시

curl -X PUT "http://kapi.kakao.com/v1/moment/adAccount/onOff?adAccountId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"config\": \"ON\"}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
21400 광고계정이 삭제처리중입니다.
21006 존재하지 않는 광고계정입니다.
90001 잘못된 요청입니다.

예시

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

Note

  • 광고계정 상태가 ON 또는 OFF일 경우에만 변경 가능합니다.
  • 광고계정이 삭제 진행중인 경우 변경할 수 없습니다.
  • 광고계정을 OFF로 변경할 때 하위 다이렉트 메시지 광고 소재의 메시지 발송 상태가 발송준비인 경우 발송종료로 변경, 발송중인 경우 발송중지로 변경됩니다.

2. 캠페인

2.1. 캠페인 리스트 조회

[Request]

GET /v1/moment/campaigns HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
adAccountId 광고계정 번호 O Long
config 캠페인 상태, 복수선택 (default : [ON, OFF])
enum{ON, OFF, DEL}
X Array

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/campaigns?adAccountId=1234&config=ON' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 리스트로 포함합니다.

Key 설명 Type
id 캠페인 번호 Long
name 캠페인명 String
type 캠페인 타입
DISPLAY(디스플레이), ON_TIME_MESSAGE(온타임 메시지), DIRECT_MESSAGE(다이렉트 메시지) 중 하나
String
config 캠페인 상태
ON, OFF, DEL(삭제) 중 하나
String

예시

{
  "content": [
    {
      "id": 1111,
      "name": "캠페인 1",
      "type" : "DISPLAY",
      "config": "ON"
    },
    {
      "id": 1112,
      "name": "캠페인 2",
      "type": "DISPLAY",
      "config": "OFF"
    }
  ]
}

Note

  • 캠페인 타입은 디스플레이(DISPLAY), 온타임 메시지(ON_TIME_MESSAGE), 다이렉트 메시지(DIRECT_MESSAGE)가 있으며 광고 목적으로 정해집니다.
캠페인 타입 광고 목적
디스플레이(DISPLAY) 카카오 친구 늘리기(INCREASE_KAKAO_FRIENDS)
디스플레이(DISPLAY) 웹사이트 방문 늘리기(INCREASE_WEB_VISITING)
디스플레이(DISPLAY) 목적 설정 없이 광고하기(NO_PURPOSE)
디스플레이(DISPLAY) 동영상 홍보하기(PROMOTE_VIDEO)
온타임 메시지(ON_TIME_MESSAGE) 온타임 메시지 보내기(SENDING_ON_TIME_MESSAGE)
다이렉트 메시지(DIRECT_MESSAGE) 다이렉트 메시지 보내기(SENDING_DIRECT_MESSAGE)

2.2. 캠페인 조회

[Request]

GET /v1/moment/campaign HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
campaignId 캠페인 번호 O Long

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/campaign?campaignId=1234' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

Key 설명 Type
id 캠페인 번호 Long
name 캠페인명 String
adPurposeType 광고 목적
INCREASE_KAKAO_FRIENDS(카카오 친구 늘리기), INCREASE_WEB_VISITING(웹사이트 방문 늘리기), NO_PURPOSE(목적 설정 없이 광고하기), PROMOTE_VIDEO(동영상 홍보하기), SENDING_DIRECT_MESSAGE(다이렉트 메시지 보내기), SENDING_ON_TIME_MESSAGE(온타임 메시지 보내기) 중 하나
String
dailyBudgetAmount 일예산
입력하지 않은 경우 예산 "한도 없음"과 같은 의미
Long
config 캠페인 상태
ON, OFF, DEL(삭제) 중 하나
String
isDailyBudgetAmountOver 일예산초과 여부 Boolean
statusDescription 캠페인의 게재와 관련된 현재 상태 String

예시

{
  "id": 1111,
  "name": "캠페인 1",
  "adPurposeType": "PROMOTE_VIDEO",
  "dailyBudgetAmount": 1000000,
  "config":"ON",
  "isDailyBudgetAmountOver": false,
  "statusDescription": "운영중"
}

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
31001 캠페인이 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 31001,
        "detailMsg": "캠페인이 존재하지 않습니다."
    }
}

Note

  • 캠페인의 게재와 관련된 상태는 캠페인 상태(config), 일예산초과 여부(isDailyBudgetAmountOver) 조합으로 만들어집니다.
캠페인의 게재와 관련된 현재 상태 캠페인 상태 일예산초과 여부
운영중 ON false
일예산초과 ON true
사용자OFF OFF false
사용자OFF, 일예산초과 OFF true
삭제됨 DEL -

2.3. 캠페인 ON/OFF 수정

[Request]

PUT /v1/moment/campaign/onOff HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
campaignId 캠페인 번호 O Long
config ON, OFF 중 하나 O String

예시

curl -X PUT "http://kapi.kakao.com/v1/moment/campaign/onOff?campaignId=1234" \
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"config\": \"ON\"}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
31001 캠페인이 존재하지 않습니다.
90001 잘못된 요청입니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 31001,
        "detailMsg": "캠페인이 존재하지 않습니다."
    }
}

Note

  • 캠페인 상태가 ON 또는 OFF일 경우에만 변경 가능합니다.
  • 다이렉트 메시지 캠페인은 수정할 수 없습니다.

2.4. 캠페인 일예산 수정

[Request]

PUT /v1/moment/campaign/dailyBudgetAmount HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
campaignId 캠페인 번호 O Long
dailyBudgetAmount 캠페인 일예산
미설정 가능
설정하는 경우 최소 50,000원에서 최대 1,000,000,000원까지 설정 가능하며 10원 단위로 가능
O Long

캠페인 일예산 설정하는 예시

curl -X PUT "http://kapi.kakao.com/v1/moment/campaign/dailyBudgetAmount?campaignId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"dailyBudgetAmount\": 5000000}"

캠페인 일예산 미설정하는 예시

curl -X PUT "http://kapi.kakao.com/v1/moment/campaign/dailyBudgetAmount?campaignId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"dailyBudgetAmount\": null}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
31011 캠페인 일예산은 최소 50,000보다 크거나 같아야 합니다.
31012 캠페인 일예산은 최대 1,000,000,000 보다 작거나 같아야 합니다.
31001 캠페인이 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 31011,
        "detailMsg": "캠페인 일예산은 최소 50,000보다 크거나 같아야 합니다."
    }
}

Note

  • 캠페인 일예산을 입력하지 않은 경우 예산 "한도 없음"과 같은 의미입니다.
  • 캠페인 일예산 설정값은 최소 50,000원에서 최대 1,000,000,000원 까지 설정 가능하며 10원 단위로 가능
  • 단, 기존에 저장된 일예산보다 작은 값으로 수정 시, 하위의 광고그룹/소재 중 광고그룹 일예산/최대 입찰금액, 소재 입찰금액이 조건에 위배되는 광고그룹/소재는 일괄 변경됨
    • 광고그룹 일예산이 변경되는 캠페인 일예산을 초과하는 경우 → 변경되는 캠페인 일예산으로 수정함
    • 광고그룹 최대 입찰금액이 변경되는 광고그룹 일예산 50%를 초과하는 경우 → 변경되는 광고그룹 일예산 50% 로 수정함
    • 소재 입찰금액이 변경되는 광고그룹 최대 입찰금액을 초과하는 경우 → 변경되는 광고그룹 최대 입찰금액으로 수정함

3. 광고그룹

3.1. 광고그룹 리스트 조회

[Request]

GET /v1/moment/adGroups HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
campaignId 캠페인 번호 O Long
config 광고그룹 상태, 복수선택 (default : [ON, OFF])
enum{ON, OFF, DEL}
X Array

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/adGroups?campaignId=1234&config=ON' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 리스트로 포함합니다.

Key 설명 Type
id 광고그룹 번호 Long
name 광고그룹명 String
type 광고그룹 타입
DISPLAY(디스플레이), ON_TIME_MESSAGE(온타임 메시지), DIRECT_MESSAGE(다이렉트 메시지) 중 하나
String
config 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
String

예시

{
  "content": [
    {
      "id": 1111,
      "name": "광고그룹 1",
      "type": "DISPLAY",
      "config": "ON"
    },
    {
      "id": 1112,
      "name": "광고그룹 2",
      "type": "DISPLAY",
      "config": "OFF"
    }
  ]
}

Note

3.2. 광고그룹 조회

[Request]

GET /v1/moment/adGroup HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
adGroupId 광고그룹 번호 O Long

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/adGroup?adGroupId=1234' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

디스플레이 광고그룹

Key 설명 Type
id 광고그룹 번호 Long
name 광고그룹명 String
pricingType 과금방식
CPM, CPC, CPA 중 하나

CPC (Cost per Click)
광고를 클릭한 경우에 과금되며, 실시간으로 광고 입찰 경쟁에 참여하여 탄력적인 광고 운영이 가능합니다.

CPM (Cost Per Mile)
1,000회 노출당 과금되는 방식으로, 노출을 기준으로 입찰 경쟁에 참여가 가능합니다.

CPA (Cost Per Action)
'카카오 친구 늘리기' 광고목적 시 클릭으로부터 24시간 이내 발생한 전환(친구추가)에 대해서 과금되는 방식입니다.
String
pacing 게재방식
NONE, QUICK, NORMAL 중 하나
단, 과금전략이 MANUAL(수동)일 경우에만 설정 가능합니다.

NONE(설정 해제)
설정을 해제합니다

QUICK(빠른게재)
가능한 한 빨리 광고 결과를 얻을 수 있도록 예산을 최대한 사용하여 광고 노출을 유도합니다.

NORMAL(일반게재)
일예산을 시간대별로 분할하여 시간대별 분할된 예산만큼 사용할 수 있도록 광고 노출을 제어합니다.
String
bidStrategy 과금전략
MANUAL(수동), AUTOBID(자동입찰), OPTIMIZATION(목적 최적화) 중 하나
String
dailyBudgetAmount 일예산 Long
bidAmount 최대 입찰금액 Integer
config 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
String
isDailyBudgetAmountOver 일예산초과 여부 Boolean
isValidPeriod 집행기간 유효 여부 Boolean
statusDescription 광고그룹의 게재와 관련된 현재 상태 String

예시

{
  "id": 1111,
  "name": "광고그룹 1",
  "pricingType": "CPC",
  "pacing": "NORMAL",
  "bidStrategy": "MANUAL",
  "dailyBudgetAmount": 1000000,
  "bidAmount": 10000,
  "config":"ON",
  "isDailyBudgetAmountOver": false,
  "isValidPeriod": true,
  "statusDescription": "운영중"
}

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
32001 광고그룹이 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 32001,
        "detailMsg": "광고그룹이 존재하지 않습니다."
    }
}

Note

  • 디스플레이 광고그룹의 게재와 관련된 상태는 광고그룹 상태(config), 일예산초과 여부(isDailyBudgetAmountOver), 집행기간 유효 여부(isValidPeriod) 조합으로 만들어집니다.
디스플레이 광고그룹의 게재와 관련된 현재 상태 광고그룹 상태 일예산초과 여부 집행기간 유효 여부
운영중 ON false true
일예산초과 ON true true
기간외 ON false false
일예산초과, 기간외 ON true false
사용자OFF OFF false true
사용자OFF, 일예산초과 OFF true true
사용자OFF, 기간외 OFF false false
사용자OFF, 일예산초과, 기간외 OFF true false
삭제됨 DEL - -

온타임 메시지 광고그룹

Key 설명 Type
id 광고그룹 번호 Long
name 광고그룹명 String
pricingType 과금방식
CPMS (Cost Per Message)
메시지 캠페인을 통해 메시지 발송 시 발송 건당 과금됩니다.
String
bidStrategy 과금전략
MANUAL(수동), AUTOBID(자동입찰), OPTIMIZATION(목적 최적화) 중 하나
String
dailyBudgetAmount 일예산 Long
bidAmount 최대 입찰금액 Integer
config 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
String
isDailyBudgetAmountOver 일예산초과 여부 Boolean
isValidPeriod 집행기간 유효 여부 Boolean
statusDescription 광고그룹의 게재와 관련된 현재 상태 String

예시

{
  "id": 1111,
  "name": "광고그룹 1",
  "pricingType": "CPMS",
  "bidStrategy": "MANUAL",
  "dailyBudgetAmount": 1000000,
  "bidAmount": 10000,
  "config":"ON",
  "isDailyBudgetAmountOver": false,
  "isValidPeriod": true,
  "statusDescription": "운영중"
}

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
32001 광고그룹이 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 32001,
        "detailMsg": "광고그룹이 존재하지 않습니다."
    }
}

Note

  • 온타임 메시지 광고그룹의 게재와 관련된 상태는 광고그룹 상태(config), 일예산초과 여부(isDailyBudgetAmountOver), 집행기간 유효 여부(isValidPeriod) 조합으로 만들어집니다.
온타임 메시지 광고그룹의 게재와 관련된 현재 상태 광고그룹 상태 일예산초과 여부 집행기간 유효 여부
운영중 ON false true
일예산초과 ON true true
기간외 ON false false
일예산초과, 기간외 ON true false
사용자OFF OFF false true
사용자OFF, 일예산초과 OFF true true
사용자OFF, 기간외 OFF false false
사용자OFF, 일예산초과, 기간외 OFF true false
삭제됨 DEL - -

다이렉트 메시지 광고그룹

Key 설명 Type
id 광고그룹 번호 Long
name 광고그룹명 String
pricingType 과금방식
CPMS
String
config 광고그룹 상태
ON, DEL(삭제) 중 하나
String
statusDescription 광고그룹의 게재와 관련된 현재 상태
운영중, 삭제 중 하나
String

예시

{
  "id": 1111,
  "name": "광고그룹 1",
  "pricingType": "CPMS",
  "config":"ON",
  "statusDescription": "운영중"
}

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
32001 광고그룹이 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 32001,
        "detailMsg": "광고그룹이 존재하지 않습니다."
    }
}

Note

3.3. 광고그룹 ON/OFF 수정

[Request]

PUT /v1/moment/adGroup/onOff HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
adGroupId 광고그룹 번호 O Long
config ON, OFF 중 하나 O String

예시

curl -X PUT "http://kapi.kakao.com/v1/moment/adGroup/onOff?adGroupId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"config\": \"ON\"}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
90001 잘못된 요청입니다.
32001 광고그룹이 존재하지 않습니다.

응답 예제

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 32001,
        "detailMsg": "광고그룹이 존재하지 않습니다."
    }
}

Note

  • 광고그룹 상태가 ON 또는 OFF일 경우에만 변경 가능합니다.
  • 디스플레이 광고그룹, 온타임 메시지 광고그룹만 가능합니다.

3.4. 광고그룹 일예산 수정

[Request]

PUT /v1/moment/adGroup/dailyBudgetAmount HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
adGroupId 광고그룹 번호 O Long
dailyBudgetAmount 광고그룹 일예산
광고그룹 일예산은 최소 10,000원에서 최대 1,000,000,000원까지 설정 가능하며 10원 단위로 가능
캠페인 일예산이 설정되어 있는 경우, 광고그룹 일예산은 캠페인 일예산보다 작거나 같아야함
O Long

예시

curl -X PUT "http://kapi.kakao.com/v1/moment/adGroup/dailyBudgetAmount?adGroupId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"dailyBudgetAmount\": 5000000}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
32021 광고그룹 일예산은 최소 50,000보다 크거나 같아야 합니다.
32022 광고그룹 일예산은 최대 1,000,000,000 보다 작거나 같아야 합니다.
32019 광고그룹 일예산은 캠페인 일예산을 초과할 수 없습니다.
32013 관련 작업을 지원하지 않는 광고그룹입니다.
32001 광고그룹이 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 32021,
        "detailMsg": "광고그룹 일예산은 최소 50,000보다 크거나 같아야 합니다."
    }
}

Note

  • 일예산은 최소 10,000원에서 최대 1,000,000,000원까지 설정 가능하며 10원 단위로 가능합니다.
  • 캠페인 일예산이 설정되어 있는 경우, 광고그룹 일예산은 캠페인 일예산보다 작거나 같아야 합니다.

3.5. 광고그룹 최대 입찰금액 수정

[Request]

PUT /v1/moment/adGroup/bidAmount HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
adGroupId 광고그룹 번호 O Long
bidAmount 최대 입찰금액
광고그룹 입찰금액은 광고그룹에서 설정한 일예산의 50% 또는 최대값인 1,000,000원을 넘을 수 없습니다.
입찰금액 최소값은 광고그룹 타입, 광고 목적, 과금방식에 따라 다릅니다.
O Integer

예시

curl -X PUT "http://kapi.kakao.com/v1/moment/adGroup/bidAmount?adGroupId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"bidAmount\": 5000}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
32008 CPM의 최소 입찰금액 오류
32010 CPC의 최소 입찰금액 오류
32011 CPA의 최소 입찰금액 오류
32014 CPMS의 최소 입찰금액 오류
32009 현재 지원하지 않는 과금 타입입니다.
32013 관련 작업을 지원하지 않는 광고그룹입니다.
32001 광고그룹이 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 32013,
        "detailMsg": "관련 작업을 지원하지 않는 광고그룹입니다."
    }
}

Note

  • 디스플레이 광고그룹, 온타임 메시지 광고그룹만 가능합니다.
  • 입찰금액은 광고그룹에서 설정한 일예산의 50% 또는 최대값인 1,000,000원을 넘을 수 없습니다.
  • 입찰금액 최소값은 광고그룹 타입, 광고 목적, 과금방식에 따라 다릅니다.
광고그룹 타입 광고목적 CPC CPM CPA CPMS
디스플레이 카카오 친구 늘리기 10원 100원 100원 -
디스플레이 웹사이트 방문 늘리기 10원 100원 - -
디스플레이 목적 설정 없이 광고하기 10원 100원 - -
디스플레이 동영상 홍보하기 - 1000원 - -
온타임 메시지 온타임 메시지 보내기 - - - 20원

3.6. 광고그룹 게재방식 수정

[Request]

PUT /v1/moment/adGroup/pacing HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
adGroupId 광고그룹 번호 O Long
pacing 게재방식
NORMAL(일반게재), QUICK(빠른게재) 중 하나
단, 과금전략이 MANUAL(수동)일 경우에만 설정 가능합니다. 그외의 과금전략은 게재방식을 설정할 수 없습니다.

NORMAL(일반게재)
'일반 게재'는 광고그룹에 설정된 일예산을 바탕으로 시간대별로 고려된 예산을 초과 사용하지 않도록 예산을 분할하여 광고 노출을 제어합니다.

QUICK(빠른게재)
'빠른 게재'는 가능한 빨리 광고 결과를 얻을 수 있도록 예산을 최대한 사용하여 광고 노출을 유도합니다.
O String

예시

curl -X PUT "http://kapi.kakao.com/v1/moment/adGroup/pacing?adGroupId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"pacing\": \"QUICK\"}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
90001 잘못된 요청입니다.
32017 지원하지 않는 게재방식입니다.
32016 게재방식을 선택할 수 없습니다.
32001 광고그룹이 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 32016,
        "detailMsg": "게재방식을 선택할 수 없습니다."
    }
}

Note

  • 디스플레이 광고그룹만 가능합니다.
  • 과금전략이 수동(MANUAL)일 경우에만 설정 가능합니다. 그외의 과금전략은 게재방식을 설정할 수 없습니다.

4. 소재

4.1. 소재 리스트 조회

[Request]

Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
adGroupId 광고그룹 번호 O Long
config 소재 상태, 복수선택 (default : [ON, OFF])
enum{ON, OFF, DEL}
X Array

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/creatives?adGroupId=1234&config=ON' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 리스트로 포함합니다.

Key 설명 Type
id 소재 번호 Long
name 소재명 String
type 소재 타입

DISPLAY(디스플레이), ON_TIME_MESSAGE(온타임 메시지), DIRECT_MESSAGE(다이렉트 메시지) 중 하나
String
config 소재 상태

ON, OFF, DEL(삭제) 중 하나
String

예시

{
  "content": [
    {
      "id": 1111,
      "name": "소재 1",
      "type": "DISPLAY",
      "config": "ON"
    },
    {
      "id": 1112,
      "name": "소재 2",
      "type": "DISPLAY",
      "config": "OFF"
    }
  ]
}

Note

4.2. 소재 조회

[Request]

GET /v1/moment/creative HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값과 함께 GET으로 요청합니다.

Parameter

Key 설명 필수 Type
creativeId 소재 번호 O Long

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/creative?creativeId=1234' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

디스플레이 광고 소재

Key 설명 Type
id 소재 번호 Long
name 소재명 String
format 소재 유형
SINGLE_BANNER(단일 이미지), IMAGE_FEED(이미지 피드), THUMBNAIL_FEED(썸네일 피드), NATIVE_INTERSTITIAL(전면), VIDEO_BANNER(동영상 배너), VIDEO_FEED(동영상 피드) 중 하나
String
bidAmount 입찰금액 Integer
landingUrl 랜딩 URL String
frequencyCap 프리퀀시 캡 횟수 Integer
config 소재 상태
ON, OFF, DEL(삭제) 중 하나
String
reviewStatus 심사 상태
APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MONITORING_REJECTED(관리자정지) 중 하나
String
modifyReviewStatus 수정소재 심사 상태
NONE(수정소재 없음), WAITING(심사중), REJECTED(심사보류) 중 하나
String
statusDescription 소재의 게재와 관련된 현재 상태 String

예시

{
  "id": 1111,
  "name": "디스플레이 광고 소재",
  "format": "SINGLE_BANNER",
  "bidAmount": 50000,
  "landingUrl": "http://www.daum.net",
  "frequencyCap": 3,
  "config":"ON", 
  "reviewStatus": "APPROVED",
  "modifyReviewStatus": "NONE",
  "statusDescription": "운영중"
}

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
33003 소재가 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33003,
        "detailMsg": "소재가 존재하지 않습니다."
    }
}

Note

  • 디스플레이 광고 소재는 4가지의 심사 상태가 있습니다.
    • 승인(APPROVED)
    • 심사중(WAITING)
    • 보류(REJECTED)
    • 관리자정지(MONITORING_REJECTED)
  • 수정소재 심사는 심사 상태가 승인, 관리자정지일 경우에만 값이 있으며 수정소재 심사 상태는 심사중, 보류 중 하나입니다.
  • 디스플레이 광고 소재의 게재와 관련된 상태는 소재 상태(config), 심사 상태(reviewStatus), 수정소재 심사 상태(modifyReviewStatus) 조합으로 만들어집니다.
디스플레이 광고 소재의 게재와 관련된 현재 상태 소재 상태 심사 상태 수정소재 심사 상태
운영중 ON APPROVED NONE
운영중(수정사항 심사중) ON APPROVED WAITING
운영중(수정사항 심사보류) ON APPROVED REJECTED
심사중 ON WAITING NONE
심사보류 ON REJECTED NONE
관리자정지 ON MONITORING_REJECTED NONE
관리자정지(수정사항 심사중) ON MONITORING_REJECTED WAITING
관리자정지(수정사항 심사보류) ON MONITORING_REJECTED REJECTED
사용자OFF OFF APPROVED NONE
사용자OFF, 수정사항 심사중 OFF APPROVED WAITING
사용자OFF, 수정사항 심사보류 OFF APPROVED REJECTED
사용자OFF, 심사중 OFF WAITING NONE
사용자OFF, 심사보류 OFF REJECTED NONE
사용자OFF, 관리자정지 OFF MONITORING_REJECTED NONE
사용자OFF, 관리자정지(수정사항 심사중) OFF MONITORING_REJECTED WAITING
사용자OFF, 관리자정지(수정사항 심사보류) OFF MONITORING_REJECTED REJECTED
삭제됨 DEL - -

온타임 메시지 광고 소재

Key 설명 Type
id 소재 번호 Long
name 소재명 String
format 소재 유형
WIDE_MESSAGE(와이드형), WIDE_LIST_MESSAGE(와이드 리스트형) 중 하나
String
bidAmount 입찰금액 Integer
config 소재 상태
ON, OFF, DEL(삭제) 중 하나
String
statusDescription 소재의 게재와 관련된 현재 상태
운영중, 사용자OFF, 삭제 중 하나
String

예시

{
  "id": 1111,
  "name": "온타임 메시지 광고",
  "format": "WIDE_MESSAGE",
  "bidAmount": 40,
  "config":"ON",
  "statusDescription": "운영중"
}

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
33003 소재가 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33003,
        "detailMsg": "소재가 존재하지 않습니다."
    }
}

Note

다이렉트 메시지 광고 소재

Key 설명 Type
id 소재 번호 Long
name 소재명 String
format 소재 유형
WIDE_MESSAGE(와이드형), WIDE_LIST_MESSAGE(와이드 리스트형) 중 하나
String
messageSendingInfo 메시지 발송 상태
SAVE(임시저장), READY(발송준비), SENDING(발송중), PAUSE(발송중지), FINISHED(발송종료) 중 하나
String
statusDescription 소재의 게재와 관련된 현재 상태
임시저장, 발송준비, 발송중, 발송중지, 발송종료 중 하나
String

예시

{
  "id": 1111,
  "name": "다이렉트 메시지 광고",
  "format": "WIDE_MESSAGE",
  "messageSendingInfo": "SAVE",
  "statusDescription": "임시저장"
}

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
33003 소재가 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33003,
        "detailMsg": "소재가 존재하지 않습니다."
    }
}

Note

4.3. 소재 ON/OFF

[Request]

PUT /v1/moment/creative/onOff HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
creativeId 소재 번호 O Long
config ON, OFF 중 하나 O String

예시

curl -X PUT "http://kapi.kakao.com/v1/moment/creative/onOff?creativeId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"config\": \"ON\"}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
90001 잘못된 요청입니다.
33003 소재가 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33003,
        "detailMsg": "소재가 존재하지 않습니다."
    }
}

Note

  • 소재 상태가 ON 또는 OFF일 경우에만 변경 가능합니다.
  • 디스플레이 광고 소재, 온타임 메시지 광고 소재만 가능합니다.

4.4. 소재 입찰금액 수정

[Request]

PUT /v1/moment/creative/bidAmount HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
creativeId 소재 번호 O Long
bidAmount 입찰금액
입찰금액 최대값은 1,000,000원을 넘을 수 없습니다.
입찰금액 최소값은 소재 타입, 광고 목적, 과금방식에 따라 다릅니다.
O Integer

예시

curl -X PUT "http://kapi.kakao.com/v1/moment/creative/bidAmount?creativeId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"bidAmount\": 5000}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
33104 CPM의 최소 입찰금액 오류
33107 CPC의 최소 입찰금액 오류
33108 CPA의 최소 입찰금액 오류
33112 CPMS의 최소 입찰금액 오류
33116 소재 입찰금액이 광고그룹 최대 입찰금액보다 큽니다. 광고그룹 최대 입찰금액 이하로 설정하세요.
33003 소재가 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33116,
        "detailMsg": "소재 입찰금액이 광고그룹 최대 입찰금액보다 큽니다. 광고그룹 최대 입찰금액 이하로 설정하세요."
    }
}

Note

  • 디스플레이 광고 소재, 온타임 메시지 광고 소재만 가능합니다.

  • 입찰금액 최소값은 소재 타입, 광고 목적, 과금방식에 따라 다릅니다.

소재 타입 광고목적 CPC CPM CPA CPMS
디스플레이 카카오 친구 늘리기 10원 100원 100원 -
디스플레이 웹사이트 방문 늘리기 10원 100원 - -
디스플레이 목적 설정 없이 광고하기 10원 100원 - -
디스플레이 동영상 홍보하기 - 1000원 - -
온타임 메시지 온타임 메시지 보내기 - - - 20원

4.5. 소재 프리퀀시 캡 수정

[Request]

PUT /v1/moment/creative/frequencyCap HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

아래 파라미터의 값들과 함께 PUT으로 요청합니다.

Parameter

Key 설명 필수 Type
creativeId 소재 번호 O Long
frequencyCap 프리퀀시 캡 횟수 O Integer

예시

curl -X PUT "http://kapi.kakao.com/v1/moment/creative/frequencyCap?creativeId=1234" \ 
    -H 'Authorization: Bearer {access_token}' \
    -H "Content-Type: application/json" \
    -d "{ \"frequencyCap\": 5}"

[Response]

요청이 성공하면 Http Status가 200으로 오고 응답 바디는 없습니다.

예시

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

요청이 실패하면 응답 바디에 JSON객체로 아래의 값을 포함합니다.

DetailCode 설명
90001 잘못된 요청입니다.
33003 소재가 존재하지 않습니다.

예시

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 33003,
        "detailMsg": "소재가 존재하지 않습니다."
    }
}

Note

  • 디스플레이 광고 소재만 가능합니다.

5. 보고서

5.1. 광고계정 보고서 조회

[Request]

GET /v1/moment/adAccount/report HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

Parameter

Key 설명 필수 Type
adAccountId 광고계정 번호
해당 광고계정 번호에 대한 보고서가 조회됩니다.
O Long
datePreset 사전 정의된 보고서 조회기간
enum{TODAY, YESTERDAY}
X(option) DatePreset
level 보고서 조회 레벨 기준 (default: AD_ACCOUNT)
보고서 조회시 데이터가 그룹화 될 레벨 기준을 지정합니다.
광고계정 레벨의 보고서에서는 광고계정 혹은 광고계정 하위의 캠페인별 보고서 조회가 가능합니다.
enum{AD_ACCOUNT, CAMPAIGN}
O Dimension
dimension 보고서 조회 기준
보고서 조회시 데이터가 그룹화 될 기준을 지정합니다.
enum{CREATIVE_SIZE, CREATIVE_FORMAT, CREATIVE_TYPE, PLACEMENT, AGE, GENDER, AGE_GENDER, LOCATION, DEVICE_TYPE, HOUR}
X Dimension
metricsGroup 보고서 지표 그룹
보고서 조회 지표들을 지정합니다.
지표 그룹별 상세 지표리스트는 MetricGroup 정의 테이블을 참조해주세요.
enum{BASIC, ADDITION, MESSAGE, MESSAGE_ADDITION, MESSAGE_CLICK, PLUS_FRIEND, PIXEL_CONVERSION, SDK_CONVERSION, VIDEO}
O MetricsGroup

DatePreset (Enum)

Value 설명
TODAY 오늘, 00시 부터 현재 전 시간까지
YESTERDAY 어제, 00시 부터 24시 까지

Dimension - Level (Enum)

Value 설명 Code
AD_ACCOUNT 광고계정 ad_account_id
CAMPAIGN 캠페인 campaign_id
AD_GROUP 광고그룹 ad_group_id
CREATIVE 소재 creative_id

Dimension (Enum)

Value 설명 Code
CREATIVE_SIZE 소재 사이즈
- total
- 250x250
- 200x200
- 120x600
- 130x250
- 160x600
- 978x60
- 970x90
- 728x90
- 655x120
- 468x60
- 336x280
- 320x100
- 320x80
- 320x50
- 300x250
- 300x150
- 170x128
- 326x56
- 1190x48
- 320x160

- total
- SIZE_250x250
- SIZE_200x200
- SIZE_120x600
- SIZE_130x250
- SIZE_160x600
- SIZE_978x60
- SIZE_970x90
- SIZE_728x90
- SIZE_655x120
- SIZE_468x60
- SIZE_336x280
- SIZE_320x100
- SIZE_320x80
- SIZE_320x50
- SIZE_300x250
- SIZE_300x150
- SIZE_170x128
- SIZE_326x56
- SIZE_1190x48
- SIZE_320x160
CREATIVE_FORMAT 소재 형식
Display
- 이미지 피드
- 썸네일 피드
- 전면형 네이티브
- SINGLE 배너
- 비디오 배너
- 비디오 피드
Message
- 와이드 리스트 메세지
- 와이드 메세지

Display
- IMAGE_FEED
- THUMBNAIL_FEED
- NATIVE_INTERSTITIAL
- SINGLE_BANNER
- VIDEO_BANNER
- VIDEO_FEED
Message
- WIDE_LIST_MESSAGE
- WIDE_MESSAGE
CREATIVE_TYPE 소재 유형
- total
- 네이티브
- 배너
- 동영상
- 메시지

- total
- NATIVE
- BANNER
- VIDEO
- MESSAGE
PLACEMENT 게재지면
- total
- 카카오톡
- 다음
- 카카오스토리
- 카카오서비스
- 네트워크

- total
- KAKAO_TALK
- DAUM
- KAKAO_STORY
- KAKAO_SERVICE
- NETWORK
AGE 연령
- total
- 15~19
- 20~25
- 26~30
- 31~40
- 41~50
- 51~70
- 알 수 없음

- total
- 15
- 20
- 26
- 31
- 41
- 51
- -1
GENDER 성별
- total
- 남
- 여
- 알 수 없음

- total
- M
- F
- N
AGE_GENDER 연령+성별
LOCATION 지역
- total
- 서울특별시
- 인천광역시
- 경기도
- 강원도
- 세종특별자치시
- 대전광역시
- 충청북도
- 충청남도
- 광주광역시
- 전라북도
- 전라남도
- 대구광역시
- 울산광역시
- 경상북도
- 경상남도
- 부산광역시
- 제주틀별자치도
- 해외
- 알수없음

- total
- I
- K
- B
- A
- Q
- G
- P
- O
- E
- M
- L
- F
- J
- D
- C
- H
- N
- Z
- U
DEVICE_TYPE 디바이스
- total
- PC
- Android
- iOS
- 기타

- total
- PC
- Android
- iOS
- N/A
HOUR 시간대
- total
- 00:00~00:59
- 01:00~01:59
- 02:00~02:59
- 03:00~03:59
- 04:00~04:59
- 05:00~05:59
- 06:00~06:59
- 07:00~07:59
- 08:00~08:59
- 09:00~09:59
- 10:00~10:59
- 11:00~11:59
- 12:00~12:59
- 13:00~13:59
- 14:00~14:59
- 15:00~15:59
- 16:00~16:59
- 17:00~17:59
- 18:00~18:59
- 19:00~19:59
- 20:00~20:59
- 21:00~21:59
- 22:00~22:59
- 23:00~23:59

- total
- 00
- 01
- 02
- 03
- 04
- 05
- 06
- 07
- 08
- 09
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23

MetricsGroup (Enum)

Value 설명 Code
BASIC 기본지표
- 노출수
- 클릭수
- 클릭률
- 비용

- imp
- click
- ctr
- cost
ADDITION 추가지표
- 도달수
- 노출당 비용
- 클릭당 비용
- 도달당 비용

- reach
- cost_per_imp
- cost_per_click
- cost_per_reach
MESSAGE 메세지 기본지표
- 발송수
- 열람수
- 전체 클릭수
- 비용

- msg_send
- msg_open
- msg_click
- cost
MESSAGE_ADDITION 메세지 추가지표
- 발송당 비용
- 열람당 비용
- 전체 클릭당 비용

- cost_per_msg_send
- cost_per_msg_open
- cost_per_msg_click
MESSAGE_CLICK 메세지 클릭지표
- 이미지/동영상 클릭수
- 타이틀 클릭수
- 텍스트 클릭수
- 리스트1 클릭수
- 리스트2 클릭수
- 리스트3 클릭수
- 리스트4 클릭수
- 버튼1 클릭수
- 버튼2 클릭수
- 기타 클릭수

- msg_click_media
- msg_click_title
- msg_click_text
- msg_click_list1
- msg_click_list2
- msg_click_list3
- msg_click_list4
- msg_click_button1
- msg_click_button2
- msg_click_others
PLUS_FRIEND 카카오친구 지표
- 플러스친구 추가수
- 플러스친구 추가당 비용

- conv_kf_pf_add
- cost_per_conv_kf_pf_add
PIXEL_CONVERSION 픽셀 전환 지표
- 가입완료(직접)
- 장바구니 보기(직접)
- 구매(직접)
- 구매금액(직접)
- 가입완료(간접)
- 장바구니 보기(간접)
- 구매(간접)
- 구매금액(간접)

- conv_px_cmpt_reg_dir
- conv_px_view_cart_dir
- conv_px_purchase_dir
- conv_px_purchase_p_dir
- conv_px_cmpt_reg_indir
- conv_px_view_cart_indir
- conv_px_purchase_indir
- conv_px_purchase_p_indir
SDK_CONVERSION SDK 전환 지표
- 앱 설치(직접)
- 가입완료(직접)
- 장바구니 보기(직접)
- 구매(직접)
- 구매금액(직접)
- 앱 내 구매(직접)
- 앱 내 구매금액(직접)
- 앱 설치(간접)
- 가입완료(간접)
- 장바구니 보기(간접)
- 구매(간접)
- 구매금액(간접)
- 앱 내 구매(간접)
- 앱 내 구매금액(간접)

- conv_sdk_app_install_dir
- conv_sdk_cmpt_reg_dir
- conv_sdk_view_cart_dir
- conv_sdk_purchase_dir
- conv_sdk_purchase_p_dir
- conv_sdk_iap_dir
- conv_sdk_iap_p_dir
- conv_sdk_app_install_indir
- conv_sdk_cmpt_reg_indir
- conv_sdk_view_cart_indir
- conv_sdk_purchase_indir
- conv_sdk_purchase_p_indir
- conv_sdk_iap_indir
- conv_sdk_iap_p_indir
VIDEO 동영상 지표
- 재생수
- 재생당 비용
- 자동 재생수
- 터치 재생수
- 사운드 ON수
- 3초 재생수
- 10초 재생수
- 15초 재생수
- 30초 재생수
- 60초 재생수
- 25% 재생수
- 50% 재생수
- 75% 재생수
- 100% 재생수

- video_play
- cost_per_video_play
- video_play_auto
- video_play_touch
- video_unmute
- video_play_3s
- video_play_10s
- video_play_15s
- video_play_30s
- video_play_60s
- video_play_25p
- video_play_50p
- video_play_75p
- video_play_100p

예시

curl -X GET 'https://kapi.kakao.com/v1/moment/adAccount/report?adAccountId=27450&level=AD_ACCOUNT&metricsGroup=BASIC&datePreset=TODAY' \
    -H 'Authorization: Bearer {access_token}'

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래의 값을 리스트로 포함합니다.

Key 설명 Type
start 시작일 (yyyyMMdd) String
end 종료일 (yyyyMMdd) String
dimensions 보고서 기준과 값 List
metrics 보고서 지표와 값 List

예시

{
  "content": [
    {
      "start": "2018-09-01",
      "end": "2018-09-01",
      "dimensions": {
        "ad_account_id": "27450"
      },
      "metrics": {
        "click": 0,
        "cost": 33,
        "ctr": 0,
        "imp": 3
      }
    },
    {

    }
  ]
}

보고서 데이터가 없을 경우 예시

{
  "content": [
    {
      "start": "2018-09-01",
      "end": "2018-09-01",
      "dimensions": {},
      "metrics": {}
    },
    {

    }
  ]
}

metrixGroup 지정이 안되었을 경우 예시

curl -X GET 'https://kapi.kakao.com/v1/moment/adAccount/report?adAccountId=27450&level=AD_ACCOUNT&datePreset=TODAY' \
    -H 'Authorization: Bearer {access_token}'
{
  "content": [
    {
      "start": "2018-09-01",
      "end": "2018-09-01",
      "dimensions": {
        "ad_account_id": "27450"
      },
      "metrics": {}
    },
    {

    }
  ]
}

Note

  • 특정일자에 해당하는 보고서는 그 다음날 오전 8시 이전까지는 변동가능한 실시간성 지표로 참고해주시기 바랍니다.

  • 오늘(실시간) 보고서가 궁금하다면 datePreset=TODAY를 사용하세요.

  • 시간대별 데이터가 궁금하다면 dimension=HOUR를 사용하세요.
  • 보고서 조회 기준(dimension) 중 연령, 성별, 연령 및 성별, 지역, 디바이스, 게재지면, 사이즈는 디스플레이 타입일 때만 값이 있습니다.
  • 광고계정 보고서는 디스플레이 캠페인, 메시지 캠페인을 포함한 값을 확인할 수 있습니다.
    • 보고서 지표 그룹(metricsGroup)은 복수 선택이 가능합니다.
    • 디스플레이 캠페인만 있는 광고계정의 경우 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.
    • 메시지 캠페인만 있는 광고계정의 경우 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 픽셀 전환 지표(PIXEL_CONVERSION), SDK 전환 지표(SDK_CONVERSION), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.

5.2. 캠페인 보고서 조회

[Request]

GET /v1/moment/campaign/report HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

Parameter

Key 설명 필수 Type
campaignId 캠페인 번호
해당 캠페인 번호에 대한 보고서가 조회됩니다.
O Long
datePreset 사전 정의된 보고서 조회기간
enum{TODAY, YESTERDAY}
X(option) DatePreset
level 보고서 조회 레벨 기준 (default: CAMPAIGN)
보고서 조회시 데이터가 그룹화 될 레벨 기준을 지정합니다.
광고계정 레벨의 보고서에서는 광고계정 혹은 광고계정 하위의 캠페인별 보고서 조회가 가능합니다.
enum{CAMPAIGN, AD_GROUP}
O Dimension
dimension 보고서 조회 기준
보고서 조회시 데이터가 그룹화 될 기준을 지정합니다.
enum{CREATIVE_SIZE, CREATIVE_FORMAT, CREATIVE_TYPE, AD_PURPOSE_TYPE, PLACEMENT, AGE, GENDER, AGE_GENDER, LOCATION, DEVICE_TYPE, HOUR}
O Dimension
metricsGroup 보고서 지표 그룹
보고서 조회 지표들을 지정합니다.
지표 그룹별 상세 지표리스트는 Metric 정의 테이블을 참조해주세요.
enum{BASIC, ADDITION, MESSAGE, MESSAGE_ADDITION, MESSAGE_CLICK, PLUS_FRIEND, PIXEL_CONVERSION, SDK_CONVERSION, VIDEO}
X MetricsGroup

Note

  • 디스플레이 캠페인은 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.
  • 메시지 캠페인은 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 픽셀 전환 지표(PIXEL_CONVERSION), SDK 전환 지표(SDK_CONVERSION), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
  • 그 외 자세한 설명은 광고계정 보고서 조회를 참고하세요.

5.3. 광고그룹 보고서 조회

[Request]

GET /v1/moment/adGroup/report HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

Parameter

Key 설명 필수 Type
adGroupId 광고그룹 번호
해당 광고그룹 번호에 대한 보고서가 조회됩니다.
O Long
datePreset 사전 정의된 보고서 조회기간
enum{TODAY, YESTERDAY}
X(option) DatePreset
level 보고서 조회 레벨 기준 (default: AD_GROUP)
보고서 조회시 데이터가 그룹화 될 레벨 기준을 지정합니다.
광고계정 레벨의 보고서에서는 광고계정 혹은 광고계정 하위의 캠페인별 보고서 조회가 가능합니다.
enum{AD_GROUP, CREATIVE}
O Dimension
dimension 보고서 조회 기준
보고서 조회시 데이터가 그룹화 될 기준을 지정합니다.
enum{CREATIVE_SIZE, CREATIVE_FORMAT, CREATIVE_TYPE, AD_PURPOSE_TYPE, PLACEMENT, AGE, GENDER, AGE_GENDER, LOCATION, DEVICE_TYPE, HOUR}
O Dimension
metricsGroup 보고서 지표 그룹
보고서 조회 지표들을 지정합니다.
지표 그룹별 상세 지표리스트는 Metric 정의 테이블을 참조해주세요.
enum{BASIC, ADDITION, MESSAGE, MESSAGE_ADDITION, MESSAGE_CLICK, PLUS_FRIEND, PIXEL_CONVERSION, SDK_CONVERSION, VIDEO}
X MetricsGroup

Note

  • 디스플레이 광고그룹은 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.
  • 메시지 광고그룹은 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 픽셀 전환 지표(PIXEL_CONVERSION), SDK 전환 지표(SDK_CONVERSION), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
  • 그 외 자세한 설명은 광고계정 보고서 조회를 참고하세요.

5.4. 소재 보고서 조회

[Request]

GET /v1/moment/creative/report HTTP/1.1 
Host: kapi.kakao.com 
Authorization: Bearer {access_token}

Parameter

Key 설명 필수 Type
creativeId 소재 번호
해당 광고소재 번호에 대한 보고서가 조회됩니다.
O Long
datePreset 사전 정의된 보고서 조회기간
enum{TODAY, YESTERDAY}
X(option) DatePreset
dimension 보고서 조회 기준
보고서 조회시 데이터가 그룹화 될 기준을 지정합니다.
enum{CREATIVE_SIZE, CREATIVE_FORMAT, CREATIVE_TYPE, AD_PURPOSE_TYPE, PLACEMENT, AGE, GENDER, AGE_GENDER, LOCATION, DEVICE_TYPE, HOUR}
O Dimension
metricsGroup 보고서 지표 그룹
보고서 조회 지표들을 지정합니다.
지표 그룹별 상세 지표리스트는 Metric 정의 테이블을 참조해주세요.
enum{BASIC, ADDITION, MESSAGE, MESSAGE_ADDITION, MESSAGE_CLICK, PLUS_FRIEND, PIXEL_CONVERSION, SDK_CONVERSION, VIDEO}
X MetricsGroup

Note

  • 소재단위의 보고서 요청은 소재 Level만 조회되므로 Level 지정이 별도로 필요 없습니다.
  • 디스플레이 광고 소재는 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.
  • 메시지 광고 소재는 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 픽셀 전환 지표(PIXEL_CONVERSION), SDK 전환 지표(SDK_CONVERSION), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
  • 그 외 자세한 설명은 광고계정 보고서 조회를 참고하세요.

Last Modified : 2018-11-06