Kakao Moment
Customer data management
This document describes how to use the Customer data APIs.
View list of customer data
Method URL Authorization 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.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Name Type Description id LongCustomer data ID. adAccountId LongAd account's ID. name StringCustomer data's name. kuidListKey StringCustomer data's registration key. status Enum: CustomerDataStatusStatus. ready BooleanWhether it is ready or not. fileType Enum: CustomerDataFileTypeFile identifier type. type Enum: CustomerDataTypeCustomer data registration type. sourceUrl StringRegistered URL, partially masked in the response. renewable BooleanWhether to renew. renewalExpireDateTime StringRenewal validity period 90 days from the target creation. populationScore LongTarget population. populationUpdateDate StringDate and time of target update The time when the target population was updated. createdDate StringDate and time of registration If the customer data has been modified, the creation date and time of the modified customer data. originalCreatedDate StringThe initial registration date and time. If the customer data has been modified, the creation date and time of the first registered customer data. lastModifiedDate StringLast modified date and time.
View details of customer data
Method URL Authorization 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.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Name Type Description Required ID LongCustomer data ID. O
Name Type Description id LongCustomer data ID. adAccountId LongAd account's ID. name StringCustomer data's name. kuidListKey StringCustomer data's registration key. status Enum: CustomerDataStatusStatus. ready BooleanWhether it is ready or not. fileType Enum: CustomerDataFileTypeFile identifier type. type Enum: CustomerDataTypeCustomer data registration type. sourceUrl StringRegistered URL, partially masked in the response. renewable BooleanWhether to renew. renewalExpireDateTime StringRenewal validity period. populationScore LongTarget population. populationUpdateDate StringDate and time of target update The time when the target population was updated. createdDate StringDate and time of registration. originalCreatedDate StringThe initial registration date and time. If the customer data has been modified, the creation date and time of the first registered customer data. lastModifiedDate StringLast modified date and time.
Register customer data with file
Method URL Authorization 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.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Either files or adGroupIds is required.
Name Type Description Required name StringCustomer data's name (Maximum: 120 characters). Allowed characters: Korean, English, special characters, space O fileType Enum: CustomerDataFileTypeFile identifier type. O files Multipart File[]Customer data with a .CSV file extension (Maximum: 10 files, 200 MB in total). Its MimeType is text/csv. X* adGroupIds Long[]List of message ad group IDs. X*
Name Type Description id LongCustomer data ID. adAccountId LongAd account's ID. name StringCustomer data's name. fileType Enum: CustomerDataFileTypeFile identifier type. adGroupIds Long[]List of message ad group IDs. status StringStatus. Fixed to WAITING (pending). successCount IntegerNumber of successes. failedCount IntegerNumber of failures. duplicationCount IntegerNumber of duplicates. createdDate StringDate and time of registration.
Register customer data with URL
Method URL Authorization 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 extraction and renewal
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.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Name Type Description Required name StringCustomer data's name (Maximum: 120 characters). Allowed characters: Korean, English, special characters, space O fileType Enum: CustomerDataFileTypeFile identifier type. Message recipients are excluded from URL registration. O sourceUrl StringRegistered URL. O renewable BooleanWhether to renew. If set to true, renewal runs once a day. O
Name Type Description id LongCustomer data ID. adAccountId LongAd account's ID. name StringCustomer data's name. fileType Enum: CustomerDataFileTypeFile identifier type. status StringStatus. Fixed to WAITING (pending). createdDate StringDate and time of registration. sourceUrl StringRegistered URL, partially masked in the response. renewable BooleanWhether to renew. renewalExpireDateTime StringRenewal validity period 90 days from the target creation.
Edit customer data with file
Method URL Authorization 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.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Either files or adGroupIds is required.
Name Type Description Required id LongCustomer data ID. O fileType Enum: CustomerDataFileTypeFile identifier type. O files Multipart File[]Customer data with a .CSV file extension (Maximum: 10 files, 200 MB in total). Its MimeType is text/csv. X* adGroupIds Long[]List of message ad group IDs. X*
Name Type Description id LongCustomer data ID. adAccountId LongAd account's ID. name StringCustomer data's name. fileType Enum: CustomerDataFileTypeFile identifier type. adGroupIds Long[]List of message ad group IDs. status StringStatus. Fixed to WAITING (pending). successCount IntegerNumber of successes. failedCount IntegerNumber of failures. duplicationCount IntegerNumber of duplicates. createdDate StringDate and time of registration.
Edit customer data with URL
Method URL Authorization 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.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Name Type Description Required id LongCustomer data ID. O sourceUrl StringRegistered URL. O fileType Enum: CustomerDataFileTypeFile identifier type.MESSAGE_RETARGET is excluded. O renewable BooleanWhether to renew. If set to true, renewal runs once a day. O
Name Type Description id LongCustomer data ID. adAccountId LongAd account's ID. name StringCustomer data's name. fileType Enum: CustomerDataFileTypeFile identifier type. status StringStatus. Fixed to WAITING (pending). createdDate StringDate and time of registration. sourceUrl StringRegistered URL, partially masked in the response. renewable BooleanWhether to renew. renewalExpireDateTime StringRenewal validity period 90 days from the target creation.
Method URL Authorization PUThttps://apis.moment.kakao.com/openapi/v4/customerData/name
Edits the name of customer data.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Name Type Description Required id LongCustomer data ID. O name StringCustomer data's name to be changed (Maximum: 120 characters). Allowed characters: Korean, English, special characters, space O
Name Type Description id LongCustomer data ID. adAccountId LongAd account's ID. name StringCustomer data's name. kuidListKey StringCustomer data's registration key. ready BooleanWhether it is ready or not. status Enum: CustomerDataStatusStatus. fileType Enum: CustomerDataFileTypeFile identifier type. type Enum: CustomerDataTypeCustomer data registration type. sourceUrl StringRegistered URL, partially masked in the response. renewable BooleanWhether to renew. renewalExpireDateTime StringRenewal validity period. populationScore LongTarget population. createdDate StringDate and time of registration. lastModifiedDate StringLast modified date and time. originalCreatedDate StringThe initial registration date and time. If the customer data has been modified, the creation date and time of the first registered customer data. populationUpdateDate StringDate and time of target update The time when the target population was updated.
Method URL Authorization 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.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Name Type Description Required ID LongCustomer data ID. O
Delete multiple customer data
Method URL Authorization 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.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Name Type Description Required customerDataIds StringCustomer data ID. To pass multiple customer data IDs, separate them with a comma(,). O
Name Type Description successCount IntegerNumber of successful deletions. failCount IntegerNumber of failed deletions. errorMessages String[]List of failure reasons.
View usage of customer data
Method URL Authorization GEThttps://apis.moment.kakao.com/openapi/v4/customerData/usages/${ID}
Returns the list of ad groups and campaigns that use the designated customer data.
Name Description Required Authorization Business token as a type of user authentication.Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}O adAccountId Ad account's ID.adAccountId: ${AD_ACCOUNT_ID} O
Name Type Description Required ID LongCustomer data ID. O