본문 바로가기메인 메뉴 바로가기사이드 메뉴 바로가기

kakao developers

Related sites
  • Docs
  • Kakao Moment
  • Customer data management

사이드 메뉴

Search

This document describes how to use the Customer data APIs.

MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/customerData

Returns a list of uploaded customer data.

You can use customer data as a target for Display ads and Message ads.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
NameTypeDescription
-CustomerData[]List of uploaded customer data.
NameTypeDescription
idLongCustomer data ID.
adAccountIdLongAd account's ID.
nameStringCustomer data's name.
kuidListKeyStringCustomer data's registration key.
statusEnum: CustomerDataStatusStatus.
readyBooleanWhether it is ready or not.
fileTypeEnum: CustomerDataFileTypeFile identifier type.
typeEnum: CustomerDataTypeCustomer data registration type.
sourceUrlStringRegistered URL, partially masked in the response.
renewableBooleanWhether to renew.
renewalExpireDateTimeStringRenewal validity period
90 days from the target creation.
populationScoreLongTarget population.
populationUpdateDateStringDate and time of target update
The time when the target population was updated.
createdDateStringDate and time of registration
If the customer data has been modified, the creation date and time of the modified customer data.
originalCreatedDateStringThe initial registration date and time.
If the customer data has been modified, the creation date and time of the first registered customer data.
lastModifiedDateStringLast modified date and time.
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerData" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
{
"id": 2656,
"adAccountId": 27429,
"name": "first_customer_data",
"kuidListKey": "c8010decafde484eb33284b53a290c30",
"status": "COMPLETE",
"ready": true,
"fileType": "ADID",
"type": "URL",
"sourceUrl": "https://sample-url.com/*****valid1.csv",
"renewable": true,
"renewalExpireDateTime": "2026-09-01T00:03:58",
"populationScore": 7170,
"populationUpdateDate": "2026-06-03T00:13:59",
"createdDate": "2026-06-03T00:03:59",
"originalCreatedDate": "2026-06-01T00:03:59",
"lastModifiedDate": "2026-06-03T00:13:59"
}
]
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/customerData/${ID}

Returns the details of specific customer data.

This API limits the number of calls you can make to every five seconds per customer data.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
NameTypeDescriptionRequired
IDLongCustomer data ID.O
NameTypeDescription
idLongCustomer data ID.
adAccountIdLongAd account's ID.
nameStringCustomer data's name.
kuidListKeyStringCustomer data's registration key.
statusEnum: CustomerDataStatusStatus.
readyBooleanWhether it is ready or not.
fileTypeEnum: CustomerDataFileTypeFile identifier type.
typeEnum: CustomerDataTypeCustomer data registration type.
sourceUrlStringRegistered URL, partially masked in the response.
renewableBooleanWhether to renew.
renewalExpireDateTimeStringRenewal validity period.
populationScoreLongTarget population.
populationUpdateDateStringDate and time of target update
The time when the target population was updated.
createdDateStringDate and time of registration.
originalCreatedDateStringThe initial registration date and time.
If the customer data has been modified, the creation date and time of the first registered customer data.
lastModifiedDateStringLast modified date and time.
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerData/${ID}" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 2656,
"adAccountId": 27429,
"name": "first_customer_data",
"kuidListKey": "c8010decafde484eb33284b53a290c30",
"status": "COMPLETE",
"ready": true,
"fileType": "ADID",
"type": "URL",
"sourceUrl": "https://sample-url.com/*****valid1.csv",
"renewable": true,
"renewalExpireDateTime": "2026-09-01T00:03:58",
"populationScore": 7170,
"populationUpdateDate": "2026-06-03T00:13:59",
"createdDate": "2026-06-03T00:03:59",
"originalCreatedDate": "2026-06-01T00:03:59",
"lastModifiedDate": "2026-06-03T00:13:59"
}
MethodURLAuthorization
POSThttps://apis.moment.kakao.com/openapi/v4/customerData

Registers customer data as a file for use when creating or editing an ad group.

  • Supports only Multipart/form-data.
  • Customer data can consist of up to 10 CSV files.
  • The total file size is 200 MB or less.
  • Up to 50 customer data per account.
  • Target population is extracted within 1 hour after registration.
  • For the file content format, refer to File identifier type.

This API limits the number of calls you can make to every five seconds per user account and ad account.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
  • Either files or adGroupIds is required.
NameTypeDescriptionRequired
nameStringCustomer data's name (Maximum: 120 characters).
Allowed characters: Korean, English, special characters, space
O
fileTypeEnum: CustomerDataFileTypeFile identifier type.O
filesMultipart File[]Customer data with a .CSV file extension (Maximum: 10 files, 200 MB in total).
Its MimeType is text/csv.
X*
adGroupIdsLong[]List of message ad group IDs.X*
* adGroupIds is required if fileType is MESSAGE_RETARGET; files in other cases.
NameTypeDescription
idLongCustomer data ID.
adAccountIdLongAd account's ID.
nameStringCustomer data's name.
fileTypeEnum: CustomerDataFileTypeFile identifier type.
adGroupIdsLong[]List of message ad group IDs.
statusStringStatus.
Fixed to WAITING (pending).
successCountIntegerNumber of successes.
failedCountIntegerNumber of failures.
duplicationCountIntegerNumber of duplicates.
createdDateStringDate and time of registration.
curl -X POST "https://apis.moment.kakao.com/openapi/v4/customerData" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: multipart/form-data" \
-F "files=@local/sample1.csv" \
-F "files=@local/sample2.csv" \
-F "name=first_customer_data" \
-F "fileType=ADID"
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 2656,
"adAccountId": 27429,
"name": "first_customer_data",
"fileType": "ADID",
"status": "WAITING",
"successCount": 980,
"failedCount": 15,
"duplicationCount": 5,
"createdDate": "2026-06-03T00:03:59"
}
MethodURLAuthorization
POSThttps://apis.moment.kakao.com/openapi/v4/customerData/url

Registers customer data as a URL for use in an ad group.

  • The URL must use http:// or https://, be publicly accessible, and allow an identifier list to be downloaded.
  • Unlike the Register customer data with file API, CSV files have no size limit.
  • For the file content format, refer to File identifier type.
  • The MESSAGE_RETARGET type cannot be registered with a URL.
  • Target population is extracted within 1 hour after target registration.
  • If the renewal option is included, Kakao Moment calls the URL once daily to renew the identifier list. Until renewal is complete, the ad group target works with the file before renewal.
  • Renewal is valid for 90 days from initial target registration. After the validity period ends, create a new target.

This API limits the number of calls you can make to every five seconds per user account and ad account.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
NameTypeDescriptionRequired
nameStringCustomer data's name (Maximum: 120 characters).
Allowed characters: Korean, English, special characters, space
O
fileTypeEnum: CustomerDataFileTypeFile identifier type.
Message recipients are excluded from URL registration.
O
sourceUrlStringRegistered URL.O
renewableBooleanWhether to renew.
If set to true, renewal runs once a day.
O
NameTypeDescription
idLongCustomer data ID.
adAccountIdLongAd account's ID.
nameStringCustomer data's name.
fileTypeEnum: CustomerDataFileTypeFile identifier type.
statusStringStatus.
Fixed to WAITING (pending).
createdDateStringDate and time of registration.
sourceUrlStringRegistered URL, partially masked in the response.
renewableBooleanWhether to renew.
renewalExpireDateTimeStringRenewal validity period
90 days from the target creation.
curl -X POST "https://apis.moment.kakao.com/openapi/v4/customerData/url" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"name": "customer_data_url",
"fileType": "ADID",
"sourceUrl": "https://sample-url.com/audience.csv",
"renewable": true
}'
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 2657,
"adAccountId": 27429,
"name": "customer_data_url",
"fileType": "ADID",
"status": "WAITING",
"createdDate": "2026-06-03T00:03:59",
"sourceUrl": "https://sample-url.com/*****ience.csv",
"renewable": true,
"renewalExpireDateTime": "2026-09-01T00:03:58"
}
MethodURLAuthorization
PUThttps://apis.moment.kakao.com/openapi/v4/customerData

Edits a registered customer data target.

  • Only targets with status set to COMPLETE can be edited.
  • Targets registered as files can only be edited as files.
  • Only files can be edited.
  • Supports only Multipart/form-data.
  • Editing is not allowed if the target is in use for a message ad in an ad group.
  • Target population is extracted within 1 hour after the edit.
  • Until the edit is complete, the ad group uses the previous target population. After completion, it switches to the edited target.

This API limits the number of calls you can make to every five seconds per customer data.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
  • Either files or adGroupIds is required.
NameTypeDescriptionRequired
idLongCustomer data ID.O
fileTypeEnum: CustomerDataFileTypeFile identifier type.O
filesMultipart File[]Customer data with a .CSV file extension (Maximum: 10 files, 200 MB in total).
Its MimeType is text/csv.
X*
adGroupIdsLong[]List of message ad group IDs.X*
* adGroupIds is required if fileType is MESSAGE_RETARGET; files in other cases.
NameTypeDescription
idLongCustomer data ID.
adAccountIdLongAd account's ID.
nameStringCustomer data's name.
fileTypeEnum: CustomerDataFileTypeFile identifier type.
adGroupIdsLong[]List of message ad group IDs.
statusStringStatus.
Fixed to WAITING (pending).
successCountIntegerNumber of successes.
failedCountIntegerNumber of failures.
duplicationCountIntegerNumber of duplicates.
createdDateStringDate and time of registration.
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerData" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: multipart/form-data" \
-F "id=2656" \
-F "fileType=ADID" \
-F "files=@audience_new.csv"
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 2658,
"adAccountId": 27429,
"name": "first_customer_data",
"fileType": "ADID",
"status": "WAITING",
"successCount": 1200,
"failedCount": 0,
"duplicationCount": 3,
"createdDate": "2026-06-05T09:00:00"
}
MethodURLAuthorization
PUThttps://apis.moment.kakao.com/openapi/v4/customerData/url

Edits a registered customer data target.

  • Targets registered as URLs can only be edited as URLs.
  • Only the URL (sourceUrl) and renewal option (renewable) can be edited.
  • Target population is extracted within 1 hour after the target edit.
  • Until the edit is complete, the ad group uses the previous target population. After completion, it switches to the edited target.

This API limits the number of calls you can make to every five seconds per customer data.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
NameTypeDescriptionRequired
idLongCustomer data ID.O
sourceUrlStringRegistered URL.O
fileTypeEnum: CustomerDataFileTypeFile identifier type.
MESSAGE_RETARGET is excluded.
O
renewableBooleanWhether to renew.
If set to true, renewal runs once a day.
O
NameTypeDescription
idLongCustomer data ID.
adAccountIdLongAd account's ID.
nameStringCustomer data's name.
fileTypeEnum: CustomerDataFileTypeFile identifier type.
statusStringStatus.
Fixed to WAITING (pending).
createdDateStringDate and time of registration.
sourceUrlStringRegistered URL, partially masked in the response.
renewableBooleanWhether to renew.
renewalExpireDateTimeStringRenewal validity period
90 days from the target creation.
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerData/url" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"id": 2657,
"sourceUrl": "https://sample-url.com/audience_v2.csv",
"renewable": false
}'
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 2659,
"adAccountId": 27429,
"name": "customer_data_url",
"fileType": "ADID",
"status": "WAITING",
"createdDate": "2026-06-05T09:00:00",
"sourceUrl": "https://sample-url.com/*****e_v2.csv",
"renewable": false,
"renewalExpireDateTime": "2026-09-01T00:03:58"
}
MethodURLAuthorization
PUThttps://apis.moment.kakao.com/openapi/v4/customerData/name

Edits the name of customer data.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
NameTypeDescriptionRequired
idLongCustomer data ID.O
nameStringCustomer data's name to be changed (Maximum: 120 characters).
Allowed characters: Korean, English, special characters, space
O
NameTypeDescription
idLongCustomer data ID.
adAccountIdLongAd account's ID.
nameStringCustomer data's name.
kuidListKeyStringCustomer data's registration key.
readyBooleanWhether it is ready or not.
statusEnum: CustomerDataStatusStatus.
fileTypeEnum: CustomerDataFileTypeFile identifier type.
typeEnum: CustomerDataTypeCustomer data registration type.
sourceUrlStringRegistered URL, partially masked in the response.
renewableBooleanWhether to renew.
renewalExpireDateTimeStringRenewal validity period.
populationScoreLongTarget population.
createdDateStringDate and time of registration.
lastModifiedDateStringLast modified date and time.
originalCreatedDateStringThe initial registration date and time.
If the customer data has been modified, the creation date and time of the first registered customer data.
populationUpdateDateStringDate and time of target update
The time when the target population was updated.
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerData/name" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"id": 2656,
"name": "customer_data_name_change"
}'
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 2656,
"adAccountId": 27429,
"name": "customer_data_name_change",
"kuidListKey": "c8010decafde484eb33284b53a290c30",
"ready": true,
"status": "COMPLETE",
"fileType": "ADID",
"type": "URL",
"sourceUrl": "https://sample-url.com/*****valid1.csv",
"renewable": true,
"renewalExpireDateTime": "2026-09-01T00:03:58",
"populationScore": 7170,
"createdDate": "2026-06-03T00:03:59",
"lastModifiedDate": "2026-06-03T00:13:59",
"originalCreatedDate": "2026-06-01T00:03:59",
"populationUpdateDate": "2026-06-03T00:13:59"
}
MethodURLAuthorization
DELETEhttps://apis.moment.kakao.com/openapi/v4/customerData/${ID}

Deletes registered customer data.

If the customer data is being used in an ad group, you cannot delete the customer data. When you delete customer data, the uploaded original file and success file are deleted together.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
NameTypeDescriptionRequired
IDLongCustomer data ID.O
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/customerData/${ID}" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
MethodURLAuthorization
DELETEhttps://apis.moment.kakao.com/openapi/v4/customerData

Deletes multiple customer data at once.

If the customer data is being used in an ad group or a message, you cannot delete the customer data.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
NameTypeDescriptionRequired
customerDataIdsStringCustomer data ID.
To pass multiple customer data IDs, separate them with a comma(,).
O
NameTypeDescription
successCountIntegerNumber of successful deletions.
failCountIntegerNumber of failed deletions.
errorMessagesString[]List of failure reasons.
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/customerData?customerDataIds=${CUSTOMER_DATA_ID},${CUSTOMER_DATA_ID}" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"successCount": 1,
"failCount": 1,
"errorMessages": ["타겟을 사용 중인 오디언스가 있습니다."]
}
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/customerData/usages/${ID}

Returns the list of ad groups and campaigns that use the designated customer data.

NameDescriptionRequired
AuthorizationBusiness token as a type of user authentication.
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountIdAd account's ID.
adAccountId: ${AD_ACCOUNT_ID}
O
NameTypeDescriptionRequired
IDLongCustomer data ID.O
NameTypeDescription
-AdGroupAndCampaign[]List of ad groups and campaigns that use the customer data.
NameTypeDescription
campaignCampaignCampaign.
adGroupAdGroupAd group.
messageAdMessageAdMessage.
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerData/usages/${ID}" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
{
"adGroup": {
"id": 105488,
"name": "first_ad_group",
"adGroupStatus": ["LIVE"],
"adGroupType": "DISPLAY"
},
"campaign": {
"id": 62286,
"name": "first_campaign",
"campaignTypeGoal": {
"campaignType": "DISPLAY",
"goal": "VISITING"
}
}
},
{
"messageAd": {
"id": "msg-ad-1362737813386051585",
"name": "first_message",
"opStatus": ["READY"]
}
}
]

Was this helpful?

    Kakao Moment > Customer data management - Kakao Developers | Docs