사이드 메뉴
Getting started
Kakao Developers
Login
Communication
Advertisement
- Concepts
- Ad creation: Ad account
- Ad creation: Campaign
- Ad creation: Ad group
- Targeting for ad group
- Custom audience targeting for ad group
- Ad creation: Creative common
- Ad creation: Display creative
- Ad creation: Message creative
- Ad creation: Personalized message creative
- Bizboard landing settings
- Report
- Message management
- Personalized message management
- Message ad management
- Message ad operation
- Ad View management
- Business Form+ management
- Business Form linkage management
- Pixel & SDK linkage management
- Audience management
- Engagement targeting management
- Customer file management
- Friend group management
- Ad account management
- Reference
- Type information
- Error code
Customer file management
This document describes how to use the Customer file management APIs.
| Method | URL | Authorization |
|---|---|---|
GET | https://apis.moment.kakao.com/openapi/v4/customerFiles |
| Requirements | See also | |
|---|---|---|
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description |
|---|---|---|
| - | CustomerFile[] | List of customer file. |
| Name | Type | Description |
|---|---|---|
| id | Long | Customer file ID. |
| adAccountId | Long | Ad account's ID. |
| name | String | Customer file's name. |
| adidListKey | String | Customer file's registration key. |
| customerFileStatus | Enum: CustomerFileStatus | Status. |
| populationScore | Long | Target 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. |
| ready | Boolean | Whether it is ready or not. |
| createdDate | String | Date and time of target registration Edited customer file creation date if the customer file is edited |
| lastModifyRequestDate | String | Last modified date and time. |
| originalCreatedDate | String | The initial registration date and time. If the customer file has been modified, the registration date and time of the first registered customer file. |
| populationUpdateDate | String | Date and time of target update. |
| type | String | Type of the customer file registration. |
| sourceUrl | String | Registration URL. |
| renewable | Boolean | Whether the renewal is available or not. |
| renewalExpireDateTime | String | Renewal validity period 90 days from the target population extraction. |
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles" \-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \-H "adAccountId: ${AD_ACCOUNT_ID}"
Response
// 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"}]
| Method | URL | Authorization |
|---|---|---|
GET | https://apis.moment.kakao.com/openapi/v4/customerFiles/${ID} |
| Requirements | See also | |
|---|---|---|
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| ID | Long | Customer file ID. | O |
| Name | Type | Description |
|---|---|---|
| id | Long | Customer file ID. |
| adAccountId | Long | Ad account's ID. |
| name | String | Customer file's name. |
| adidListKey | String | Customer file's registration key. |
| ready | Boolean | Whether it is ready or not. |
| customerFileStatus | Enum | Status.
|
| populationScore | Long | Target 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. |
| createdDate | String | Date and time of target registration. Edited customer file creation date if the customer file is edited. |
| lastModifyRequestDate | String | Last modified date and time. |
| originalCreatedDate | String | The initial registration date and time. If the customer file has been modified, the registration date and time of the first registered customer file. |
| populationUpdateDate | String | Date and time of target update. |
| type | String | The type of the registration. |
| sourceUrl | String | Registered URL. |
| renewable | Boolean | Whether to renew. |
| renewalExpireDateTime | String | Renewal period 90 days from the registration. |
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles/${ID}" \-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \-H "adAccountId: ${AD_ACCOUNT_ID}"
Response
// 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"}
| Method | URL | Authorization |
|---|---|---|
POST | https://apis.moment.kakao.com/openapi/v4/customerFiles |
| Requirements | See also | |
|---|---|---|
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| name | String | Customer file's name (Maximum: 120 characters). Allowed characters: Korean, English, special characters, space | O |
| files | Multipart File | Customer file with a .CSV file extension (Maximum: 10 files, 200 MB in total). Its MimeType is text/csv. | O |
| Name | Type | Description |
|---|---|---|
| id | Long | Customer file ID. |
| adAccountId | Long | Ad account's ID. |
| name | String | Customer file's name. |
| successCount | Integer | Number of successes |
| failedCount | Integer | Number of failures. |
| successFileUrl | String | URL of the data file uploaded successfully. |
| failedFileUrl | String | URL of the data file failed to be uploaded. |
| fileType | String | File identifier type. Fixed to ADID. |
| customerFileStatus | String | Status. Fixed to WAITING (pending). |
| createdDate | String | Date and time of registration. |
Request
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"
Response
// 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"}
| Method | URL | Authorization |
|---|---|---|
POST | https://apis.moment.kakao.com/openapi/v4/customerFiles/url |
| Requirements | See also | |
|---|---|---|
Registers a customer file URL for use in ad groups.
- The file URL must use
http://orhttps://, 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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| name | String | Customer file's name (Maximum: 120 characters). Allowed characters: Korean, English, special characters, space | O |
| fileType | String | File identifier type. Fixed to ADID. | O |
| sourceUrl | String | The URL to register. | O |
| renewable | Boolean | Whether to renew If true, the customer file will be renewed once a day. | O |
| Name | Type | Description |
|---|---|---|
| id | Long | Customer file ID. |
| adAccountId | Long | Ad account's ID. |
| name | String | Customer file's name. |
| customerFileStatus | String | Status. Fixed to WAITING (pending). |
| createdDate | String | Date and time of registration. |
| lastModifiedDate | String | Last modified date and time. |
| originalCreatedDate | String | The initial registration date and time. If the customer file has been modified, the registration date and time of the first registered customer file. |
| type | String | The type of the registration. |
| sourceUrl | String | Registered URL. |
| renewable | Boolean | Whether to renew. |
| renewalExpireDateTime | String | Renewal period 90 days from the registration. |
Request
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}'
Response
// 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}
| Method | URL | Authorization |
|---|---|---|
PUT | https://apis.moment.kakao.com/openapi/v4/customerFiles |
| Requirements | See also | |
|---|---|---|
Edits an existing customer file target.
- Only targets with
customerFileStatusset toCOMPLETEcan be edited. - Targets registered as files can only be edited as files.
- Only
filescan 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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| id | Long | Customer file ID that you want to edit. | O |
| files | Multipart File | Customer file with a .CSV file extension (Maximum: 10 files, 200 MB in total). Its MimeType is text/csv. | O |
| Name | Type | Description |
|---|---|---|
| id | Long | Customer file ID. |
| adAccountId | Long | Ad account's ID. |
| name | String | Customer file's name. |
| successCount | Integer | Number of successes |
| failedCount | Integer | Number of failures. |
| successFileUrl | String | URL of the data file uploaded successfully. |
| failedFileUrl | String | URL of the data file failed to be uploaded. |
| fileType | String | File identifier type. Fixed to ADID. |
| customerFileStatus | String | Status. Fixed to WAITING (pending). |
| createdDate | String | Date and time of registration. |
Request
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"
Response
// 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"}
| Method | URL | Authorization |
|---|---|---|
PUT | https://apis.moment.kakao.com/openapi/v4/customerFiles/url |
| Requirements | See also | |
|---|---|---|
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| id | Long | Customer file ID | O |
| fileType | String | File identifier type. Fixed to ADID. | O |
| sourceUrl | String | Registered URL. | O |
| renewable | Boolean | Whether to renew | O |
| Name | Type | Description |
|---|---|---|
| id | Long | Customer file ID. |
| adAccountId | Long | Ad account's ID. |
| name | String | Customer file name. |
| customerFileStatus | String | Status. Fixed to WAITING (pending). |
| createdDate | String | Date and time of registration. |
| lastModifiedDate | String | Last modified date and time. |
| originalCreatedDate | String | The initial registration date and time. If the customer file has been modified, the registration date and time of the first registered customer file. |
| type | String | The type of the registration. |
| sourceUrl | String | Registered URL. |
| renewable | Boolean | Whether to renew |
| renewalExpireDateTime | String | Renewal period 90 days from the registration. |
Request
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}'
Response
// 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"}
| Method | URL | Authorization |
|---|---|---|
PUT | https://apis.moment.kakao.com/openapi/v4/customerFiles/name |
| Requirements | See also | |
|---|---|---|
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.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| id | Long | Customer file ID. | O |
| name | String | New name that you want to change to (Maximum: 120 characters). Allowed characters: Korean, English, special characters, space | O |
| Name | Type | Description |
|---|---|---|
| id | Long | Customer file ID. |
| adAccountId | Long | Ad account's ID. |
| name | String | Customer file's name. |
| adidListKey | String | Customer file's registration key. |
| ready | Boolean | Whether it is ready or not. |
| customerFileStatus | Enum | Status.
|
| createdDate | String | Date and time of target registration. |
| lastModifiedDate | String | Last modified date and time. |
| originalCreatedDate | String | The initial registration date and time. If the customer file has been modified, the registration date and time of the first registered customer file. |
| populationUpdateDate | String | Date and time of target update. |
Request
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"}'
Response
// 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"}
| Method | URL | Authorization |
|---|---|---|
DELETE | https://apis.moment.kakao.com/openapi/v4/customerFiles/${ID} |
| Requirements | See also | |
|---|---|---|
Deletes a registered customer file.
If the customer file is being used in an ad group, you cannot delete the customer file.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| ID | Long | Customer file ID. | O |
Request
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/customerFiles/${ID}" \-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \-H "adAccountId: ${AD_ACCOUNT_ID}"
Response
HTTP/1.1 200 OKContent-Type: application/json;charset=UTF-8
| Method | URL | Authorization |
|---|---|---|
DELETE | https://apis.moment.kakao.com/openapi/v4/customerFiles |
| Requirements | See also | |
|---|---|---|
Deletes multiple customer files at once.
If the customer file is being used in an ad group, you cannot delete the customer file.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| customerFileIds | String | Customer file ID. To pass multiple Customer file IDs, separate them with a comma(,). | O |
Request
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}"
Response
// HTTP/1.1 200 OK// Content-Type: application/json;charset=UTF-8{"successCount": 1,"failCount": 1,"errorMessages": ["타겟을 사용 중인 오디언스가 있습니다."]}
| Method | URL | Authorization |
|---|---|---|
GET | https://apis.moment.kakao.com/openapi/v4/customerFiles/usages/${ID} |
| Requirements | See also | |
|---|---|---|
Returns the list of ad groups and campaigns that use the designated customer file.
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}Business token as a type of user authentication. | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}Ad account's ID. | O |
| Name | Type | Description | Required |
|---|---|---|---|
| ID | Long | Customer file ID. | O |
| Name | Type | Description |
|---|---|---|
| - | AdGroupAndCampaign[] | List of ad groups and campaigns using the customer file. |
| Name | Type | Description |
|---|---|---|
| adGroup | AdGroup | Information of the ad group. |
| campaign | Campaign | Information of the campaign. |
Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles/usages/${ID}" \-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \-H "adAccountId: ${AD_ACCOUNT_ID}"
Response
// 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"}}}]