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

kakao developers

Related sites
  • Docs
  • Kakao Moment
  • Customer file management

사이드 메뉴

Search

This document describes how to use the Customer file management APIs.

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

Returns a list of uploaded customer files.

You can use the data in [맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] when creating or editing an ad group.

NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescription
-CustomerFile[]List of customer file.
NameTypeDescription
idLongCustomer file ID.
adAccountIdLongAd account's ID.
nameStringCustomer file's name.
adidListKeyStringCustomer file's registration key.
customerFileStatusEnum: CustomerFileStatusStatus.
populationScoreLongTarget population
Number of Kakao users extracted from the registered customer file.
Customer file in WAITING status cannot be used for targeting.
Extraction is completed within 6 hours after registering the customer file.
readyBooleanWhether it is ready or not.
createdDateStringDate and time of target registration
Edited customer file creation date if the customer file is edited
lastModifyRequestDateStringLast modified date and time.
originalCreatedDateStringThe initial registration date and time.
If the customer file has been modified, the registration date and time of the first registered customer file.
populationUpdateDateStringDate and time of target update.
typeStringType of the customer file registration.
sourceUrlStringRegistration URL.
renewableBooleanWhether the renewal is available or not.
renewalExpireDateTimeStringRenewal validity period
90 days from the target population extraction.
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
{
"id": 1,
"adAccountId": 1234,
"name": "first_customer_file",
"adidListKey": "a1234b567890123cde45f6g7890hij23",
"customerFileStatus": "COMPLETE",
"ready": true,
"createdDate": "2020-01-01 00:00",
"lastModifyRequestDate": "2020-01-01 00:00",
"originalCreatedDate": "2020-01-01 00:00",
"populationUpdateDate": "2020-01-01 14:00"
}
]
MethodURLAuthorization
GEThttps://apis.moment.kakao.com/openapi/v4/customerFiles/${ID}

Returns the details of a specific customer file.

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

NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescriptionRequired
IDLongCustomer file ID.O
NameTypeDescription
idLongCustomer file ID.
adAccountIdLongAd account's ID.
nameStringCustomer file's name.
adidListKeyStringCustomer file's registration key.
readyBooleanWhether it is ready or not.
customerFileStatusEnumStatus.
  • WAITING: Waiting for extracting target population from customer file.
  • COMPLETE: Target population has been extracted from a customer file.
  • DELETE: Deleted or deleting.
  • ERROR: Other abnormal cases.
  • MODIFYING: Preparing for the modified target population.
  • TRANSFORM_ERROR: Failed to register the CSV file with a URL.
populationScoreLongTarget population
Number of Kakao users extracted from the registered customer file.
Customer file in WAITING status cannot be used for targeting.
Extraction is completed within 6 hours after registering the customer file.
createdDateStringDate and time of target registration.
Edited customer file creation date if the customer file is edited.
lastModifyRequestDateStringLast modified date and time.
originalCreatedDateStringThe initial registration date and time.
If the customer file has been modified, the registration date and time of the first registered customer file.
populationUpdateDateStringDate and time of target update.
typeStringThe type of the registration.
sourceUrlStringRegistered URL.
renewableBooleanWhether to renew.
renewalExpireDateTimeStringRenewal period
90 days from the registration.
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles/${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": "고객파일 등록",
"adidListKey": "c8010decafde484eb33284b53a290c30",
"customerFileStatus": "MODIFYING",
"populationScore": 7170,
"ready": true,
"createdDate": "2024-02-06T00:03:59",
"lastModifyRequestDate": "2024-02-06T15:35:44",
"originalCreatedDate": "2024-02-05T16:58:20",
"populationUpdateDate": "2024-02-06T01:34:00",
"type": "URL",
"sourceUrl": "https://sample-url.com/*****valid1.csv",
"renewable": true,
"renewalExpireDateTime": "2024-05-06T00:03:58",
"transformStatus": "COMPLETED",
"transformDateTime": "2024-02-06T00:16:19"
}
MethodURLAuthorization
POSThttps://apis.moment.kakao.com/openapi/v4/customerFiles

Registers customer files for use when creating or editing ad groups.

  • Supports only Multipart/form-data.
  • A customer file can consist of up to 10 CSV files, with a total size of 200 MB or less.
  • Up to 50 customer files per account.
  • Target population is extracted within 6 hours after registration.
  • For the file format, refer to the guide and sample.

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

NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescriptionRequired
nameStringCustomer file's name (Maximum: 120 characters).
Allowed characters: Korean, English, special characters, space
O
filesMultipart FileCustomer file with a .CSV file extension (Maximum: 10 files, 200 MB in total).
Its MimeType is text/csv.
O
NameTypeDescription
idLongCustomer file ID.
adAccountIdLongAd account's ID.
nameStringCustomer file's name.
successCountIntegerNumber of successes
failedCountIntegerNumber of failures.
successFileUrlStringURL of the data file uploaded successfully.
failedFileUrlStringURL of the data file failed to be uploaded.
fileTypeStringFile identifier type.
Fixed to ADID.
customerFileStatusStringStatus.
Fixed to WAITING (pending).
createdDateStringDate and time of registration.
curl -X POST "https://apis.moment.kakao.com/openapi/v4/customerFiles" \
-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 "files=@local/sample3.csv" \
-F "name=first_customer_file"
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 1,
"adAccountId": 1234,
"name": "first_customer_file",
"successCount": 100,
"failedCount": 0,
"successFileUrl": "https://stwg.kakaocdn.net/success.csv",
"fileType": "ADID",
"customerFileStatus": "WAITING",
"createDate": "2020-01-01 00:00:00"
}
MethodURLAuthorization
POSThttps://apis.moment.kakao.com/openapi/v4/customerFiles/url

Registers a customer file URL for use in ad groups.

  • The file URL must use http:// or https://, be publicly accessible, and allow an ADID (Advertiser ID) list to be downloaded.
  • Unlike the Register with file API, CSV files have no size limit. For the file format, refer to the guide and sample.
  • Target population is extracted within 6 hours after registration.
  • If renewal is enabled, Kakao Moment calls the URL once daily to renew the ADID list. Until renewal is complete, the ad group continues to use the previous target.
  • 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
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescriptionRequired
nameStringCustomer file's name (Maximum: 120 characters).
Allowed characters: Korean, English, special characters, space
O
fileTypeStringFile identifier type.
Fixed to ADID.
O
sourceUrlStringThe URL to register.O
renewableBooleanWhether to renew
If true, the customer file will be renewed once a day.
O
NameTypeDescription
idLongCustomer file ID.
adAccountIdLongAd account's ID.
nameStringCustomer file's name.
customerFileStatusStringStatus.
Fixed to WAITING (pending).
createdDateStringDate and time of registration.
lastModifiedDateStringLast modified date and time.
originalCreatedDateStringThe initial registration date and time.
If the customer file has been modified, the registration date and time of the first registered customer file.
typeStringThe type of the registration.
sourceUrlStringRegistered URL.
renewableBooleanWhether to renew.
renewalExpireDateTimeStringRenewal period
90 days from the registration.
curl -X POST "https://apis.moment.kakao.com/openapi/v4/customerFiles/url" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"name": "test9",
"fileType": "ADID",
"sourceUrl": "https://sample-url.com/this-is-sample-file.csv",
"renewable": true
}'
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 1234,
"adAccountId": 12345,
"name": "test9",
"adidListKey": "1be324a5e8314cec9ddc526e2e9858a7",
"customerFileStatus": "WAITING",
"ready": false,
"createdDate": "2024-01-25T19:31:41.571411",
"lastModifiedDate": "2024-01-25T19:31:41.571411",
"originalCreatedDate": "2024-01-25T19:31:41.489213",
"populationUpdateDate": null,
"type": "URL",
"sourceUrl": "https://sample-url.com/*****e-file.csv",
"renewable": false,
"renewalExpireDateTime": null,
"transformStatus": "STANDBY",
"transformDateTime": null
}
MethodURLAuthorization
PUThttps://apis.moment.kakao.com/openapi/v4/customerFiles

Edits an existing customer file target.

  • Only targets with customerFileStatus 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.
  • Target population is extracted within 6 hours 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 file.

NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescriptionRequired
idLongCustomer file ID that you want to edit.O
filesMultipart FileCustomer file with a .CSV file extension (Maximum: 10 files, 200 MB in total).
Its MimeType is text/csv.
O
NameTypeDescription
idLongCustomer file ID.
adAccountIdLongAd account's ID.
nameStringCustomer file's name.
successCountIntegerNumber of successes
failedCountIntegerNumber of failures.
successFileUrlStringURL of the data file uploaded successfully.
failedFileUrlStringURL of the data file failed to be uploaded.
fileTypeStringFile identifier type.
Fixed to ADID.
customerFileStatusStringStatus.
Fixed to WAITING (pending).
createdDateStringDate and time of registration.
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerFiles" \
-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 "files=@local/sample3.csv" \
-F "id=1234"
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 1,
"adAccountId": 1234,
"name": "first_customer_file",
"successCount": 100,
"failedCount": 0,
"successFileUrl": "https://stwg.kakaocdn.net/success.csv",
"fileType": "ADID",
"customerFileStatus": "WAITING",
"createDate": "2020-01-01 00:00:00"
}
MethodURLAuthorization
PUThttps://apis.moment.kakao.com/openapi/v4/customerFiles/url

Edits a registered customer file 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 6 hours 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 file.

NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescriptionRequired
idLongCustomer file IDO
fileTypeStringFile identifier type.
Fixed to ADID.
O
sourceUrlStringRegistered URL.O
renewableBooleanWhether to renewO
NameTypeDescription
idLongCustomer file ID.
adAccountIdLongAd account's ID.
nameStringCustomer file name.
customerFileStatusStringStatus.
Fixed to WAITING (pending).
createdDateStringDate and time of registration.
lastModifiedDateStringLast modified date and time.
originalCreatedDateStringThe initial registration date and time.
If the customer file has been modified, the registration date and time of the first registered customer file.
typeStringThe type of the registration.
sourceUrlStringRegistered URL.
renewableBooleanWhether to renew
renewalExpireDateTimeStringRenewal period
90 days from the registration.
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerFiles/url" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"id": 9999,
"sourceUrl": "https://sample-url.com/customer_file_invalid1.csv",
"renewable": false
}'
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 2611,
"version": 0,
"createdDate": "2024-01-31T18:24:32",
"lastModifiedDate": "2024-01-31T18:24:32",
"adAccountId": 27429,
"name": "test1",
"fileUrl": null,
"payloadFileUrl": null,
"status": "WAITING",
"adidListKey": "df3078a4a3f44cb6bc9041d1ca77c73f",
"fileType": "ADID",
"type": "URL",
"sourceUrl": "ttps://sample-url.com/*****e-file.csv",
"renewable": false,
"renewalExpireDateTime": null,
"payloadFileUploadDate": null,
"dataRegStatusTargeting": "STANDBY",
"dataRegStatusPopulation": "STANDBY",
"transformStatus": "STANDBY",
"transformDateTime": null,
"originalCreatedDate": "2024-01-30T14:34:22",
"populationUpdateDate": null,
"modifyStatus": "WAITING",
"lastModifiedDate": "2024-01-31T18:24:32.234037",
"maskedSourceUrl": "https://sample-url.com/*****e-file.csv"
}
MethodURLAuthorization
PUThttps://apis.moment.kakao.com/openapi/v4/customerFiles/name

Enables you to edit the customer file's name.

You cannot edit the customer file that has already been registered but can edit its name only.

NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescriptionRequired
idLongCustomer file ID.O
nameStringNew name that you want to change to (Maximum: 120 characters).
Allowed characters: Korean, English, special characters, space
O
NameTypeDescription
idLongCustomer file ID.
adAccountIdLongAd account's ID.
nameStringCustomer file's name.
adidListKeyStringCustomer file's registration key.
readyBooleanWhether it is ready or not.
customerFileStatusEnumStatus.
  • WAITING: Waiting for extracting target population from customer file.
  • COMPLETE: Target population has been extracted from a customer file.
  • DELETE: The customer file has been deleted or will be deleted.
  • MODIFYING: Target population will be modified.
  • ERROR: Other abnormal cases.
  • TRANSFORM_ERROR: Failed to register the CSV file with the URL.
createdDateStringDate and time of target registration.
lastModifiedDateStringLast modified date and time.
originalCreatedDateStringThe initial registration date and time.
If the customer file has been modified, the registration date and time of the first registered customer file.
populationUpdateDateStringDate and time of target update.
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerFiles/name" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-d '{
"id": 123,
"name": "new_name_of_customer_file"
}'
// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
"id": 2687,
"adAccountId": 27429,
"name": "CHANGED_FILE_NAME",
"adidListKey": "da4a57899e43428bb7e47b09ac9c4311",
"customerFileStatus": "COMPLETE",
"ready": true,
"createdDate": "2024-02-07T00:03:38",
"lastModifiedDate": "2024-02-07T17:58:11.591512",
"originalCreatedDate": "2024-02-06T17:12:15",
"populationUpdateDate": "2024-02-07T01:34:00",
"type": "URL",
"sourceUrl": "https://sample-url.com/*****valid1.csv",
"renewable": true,
"renewalExpireDateTime": "2024-05-07T00:03:38",
"transformStatus": "COMPLETED",
"transformDateTime": "2024-02-07T00:16:23"
}
MethodURLAuthorization
DELETEhttps://apis.moment.kakao.com/openapi/v4/customerFiles/${ID}

Deletes a registered customer file.

If the customer file is being used in an ad group, you cannot delete the customer file.

NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescriptionRequired
IDLongCustomer file ID.O
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/customerFiles/${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/customerFiles

Deletes multiple customer files at once.

If the customer file is being used in an ad group, you cannot delete the customer file.

NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescriptionRequired
customerFileIdsStringCustomer file ID.
To pass multiple Customer file IDs, separate them with a comma(,).
O
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/customerFiles?customerFileIds=${CUSTOMER_FILE_ID},${CUSTOMER_FILE_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/customerFiles/usages/${ID}

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

NameDescriptionRequired
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.
O
NameTypeDescriptionRequired
IDLongCustomer file ID.O
NameTypeDescription
-AdGroupAndCampaign[]List of ad groups and campaigns using the customer file.
NameTypeDescription
adGroupAdGroupInformation of the ad group.
campaignCampaignInformation of the campaign.
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles/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": 56,
"name": "first_ad_group",
"adGroupStatus": ["LIVE"],
"adGroupType": "DISPLAY"
},
"campaign": {
"id": 78,
"name": "first_campaign",
"campaignTypeGoal": {
"campaignType": "DISPLAY",
"goal": "VISITING"
}
}
}
]

Was this helpful?

    Kakao Moment > Customer file management - Kakao Developers | Docs