kakao developers

Customer file management

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

View list of customer files

This API enables you to retrieve a list of the uploaded customer files. You can use the data in [맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] when creating or editing an ad group.

Send a GET request with the issued access token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the list of customer files in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

URL

GET /openapi/v4/customerFiles HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

Header

Name	Type	Description	Required
Authorization	String	Pass an access token in Bearer ${ACCESS_TOKEN} format.	O
adAccountId	Long	Ad account's ID.	O

Response

Name	Type	Description
-	CustomerFile[]	List of customer file.

CustomerFile

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	String	Status. One of the followings: - 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.
createdDate	String	Date and time of target creation in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate	String	Date and time of target modification in yyyy-MM-dd'T'HH:mm:ss format.
originalCreatedDate	String	Date and time of target creation in yyyy-MM-dd'T'HH:mm:ss format. If the customer file is edited, its inital creation time is returned.
populationUpdateDate	String	Date and time of target update in yyyy-MM-dd'T'HH:mm:ss format. Updated time of target population.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"

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",
        "lastModifiedDate": "2020-01-01 00:00",
        "originalCreatedDate": "2020-01-01 00:00",
        "populationUpdateDate": "2020-01-01 14:00"
    }
]

View details of customer file

This API enables you to retrieve the detailed information of a specific customer file.

Send a GET request with the issued access token and an ad account ID (adAccountId) in the request header. You must also pass the customer file ID that you want to retrieve when you request. If the request is successful, this API returns the detailed information of the customer file in JSON format. If failed, refer to Error code to figure out its failure cause.

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

Request

URL

GET /openapi/v4/customerFiles/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

Header

Name	Type	Description	Required
Authorization	String	Pass an access token in Bearer ${ACCESS_TOKEN} format.	O
adAccountId	Long	Ad account's ID.	O

Parameter

Name	Type	Description	Required
id	Long	Customer file' ID.	O

Response

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	String	Status. One of the followings: - 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.
populationScore	Long	Target population. Number of Kakao users extracted from the registered customer file. If a customer file's status is WAITING, you cannot use the customer file for targeting because population has not been extracted yet. Population is extracted within 6 hours after a customer file is registered.
createdDate	String	Date and time of target creation in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate	String	Date and time of target modification in yyyy-MM-dd'T'HH:mm:ss format.
originalCreatedDate	String	Date and time of target creation in yyyy-MM-dd'T'HH:mm:ss format. If the customer file is edited, its inital creation time is returned.
populationUpdateDate	String	Date and time of target update in yyyy-MM-dd'T'HH:mm:ss format. Updated time of target population.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles/{id}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"

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",
    "populationScore": 100,
    "ready": true,
    "createdDate": "2020-01-01 00:00",
    "lastModifiedDate": "2020-01-01 00:00",
    "originalCreatedDate": "2020-01-01 00:00",
    "populationUpdateDate": "2020-01-01 14:00"
}

Register customer file

This API enables you to upload the data that can be used when you create or edit an ad group in a customer file format. This API only supports the Multipart/form-data method. A single customer file can consist of up to 10 CSV files, and the total file size of the customer file should be 200 MB or less. You can upload up to 50 customer files per account. Target population is extracted within 12 hours after the customer file is created.

You can add users' ADIDs only to a customer file in a CSV file format. To see the sample of the CSV file, download the template.

You can also download the template and register a customer file by referring to the teamplate in [Kakao Moment] > [Ad account] > [Target management] > [Customer file management] on the Kakao Business website. To see how to upload a Friend group file in detail, read Kakao Business Guide > Kakao Moment.

Send a POST request with the issued access token and an ad account ID (adAccountId) in the request header. You must also pass the name and path of the customer file when you request. If the request is successful, this API returns the detailed information of the created customer file in JSON format. If failed, refer to Error code to figure out its failure cause.

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

Request

URL

POST /openapi/v4/customerFiles HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

Header

Name	Type	Description	Required
Authorization	String	Pass an access token in Bearer ${ACCESS_TOKEN} format.	O
adAccountId	Long	Ad account's ID.	O

Parameter

Name	Type	Description	Required
name	String	Customer file's name. Allowed characters: Korean, English, special characters, space Character limits: 50 characters	O
files	MultipartFile	Customer file with a .CSV file extension. Number of files to be uploaded: up to 10 Total size of uploaded files: up to 200 MB Its MimeType is text/csv.	O

Response

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 type. ADID
customerFileStatus	String	Status. WAITING (Pending)
dataRegStatusTargeting	String	Targeting status with the extracted target population. STANDBY (Pending)
dataRegStatusPopluation	String	Status of extracting target population. STANDBY (Pending)
createdDate	String	Date and time of creation in yyyy-MM-dd'T'HH:mm:ss format.

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/v4/customerFiles" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -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",
    "dataRegStatusTargeting": "STANDBY",
    "dataRegStatusPopulation": "STANDBY",
    "createDate": "2020-01-01 00:00:00"
}

Edit customer file

To edit a customer file, you need to upload a new file to replace the previous file. You can upload the data that will be used when you create or edit an ad group in a customer file format. This API only supports the Multipart/form-data method. A single customer file can consist of up to 10 CSV files, and the total file size of the customer file should be 200 MB or less. You can upload up to 30 customer files per account. Target population is extracted within 12 hours after the customer file is created.

Send a PUT request with the issued access token and an ad account ID (adAccountId) in the request header. You must also pass the name and path of the customer file when you request. If the request is successful, this API returns the detailed information of the modified customer file in JSON format. If failed, refer to Error code to figure out its failure cause.

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

Request

URL

PUT /openapi/v4/customerFiles HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

Header

Name	Type	Description	Required
Authorization	String	Pass an access token in Bearer ${ACCESS_TOKEN} format.	O
adAccountId	Long	Ad account's ID.	O

Parameter

Name	Type	Description	Required
id	Long	Customer file ID that you want to edit.	O
files	MultipartFile	Customer file with a .CSV file extension. Number of files to be uploaded: up to 10 Total size of uploaded files: up to 200 MB Its MimeType is text/csv.	O

Response

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 type. ADID
customerFileStatus	String	Status. WAITING (Pending)
dataRegStatusTargeting	String	Targeting status with the extracted target population. STANDBY (Pending)
dataRegStatusPopluation	String	Status of extracting target population. STANDBY (Pending)
createdDate	String	Date and time of creation in yyyy-MM-dd HH:mm:ss format.

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerFiles" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -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",
    "dataRegStatusTargeting": "STANDBY",
    "dataRegStatusPopulation": "STANDBY",
    "createDate": "2020-01-01 00:00:00"
}

Edit customer file name

This API 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.

Send a PUT request with the issued access token and an ad account ID (adAccountId) in the request header. You must also pass the customer file's ID and a new name to be changed to when you request. If the request is successful, this API returns the detailed information of the modified customer file in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

URL

PUT /openapi/v4/customerFiles/name HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

Header

Name	Type	Description	Required
Authorization	String	Pass an access token in Bearer ${ACCESS_TOKEN} format.	O
adAccountId	Long	Ad account's ID.	O

Parameter

Name	Type	Description	Required
id	Long	Customer file' ID.	O
name	String	New name that you want to change to. Allowed characters: Korean, English, special characters, space Character limits: 50 characters	O

Response

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	String	Status. One of the followings: - WAITING: Waiting for extracting target population from customer file. - COMPLETE: Target population has been extracted from a customer file. - ERROR: Other abnormal cases.
createdDate	String	Date and time of target creation in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate	String	Date and time of target modification in yyyy-MM-dd'T'HH:mm:ss format.
originalCreatedDate	String	Date and time of target creation in yyyy-MM-dd'T'HH:mm:ss format. If the customer file is edited, its inital creation time is returned.
populationUpdateDate	String	Date and time of target update in yyyy-MM-dd'T'HH:mm:ss format. Updated time of target population.

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerFiles/name" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -d '{
            "id": 123,
            "name": "new_name_of_customer_file"
        }'

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1,
    "adAccountId": 27429,
    "name": "new_name_of_customer_file",
    "adidListKey": "a1234b567890123cde45f6g7890hij23",
    "customerFileStatus": "WAITING",
    "ready": false,
    "createdDate": "2020-01-01 00:00",
    "lastModifiedDate": "2020-01-01 00:00",
    "originalCreatedDate": "2020-01-01 00:00",
    "populationUpdateDate": "2020-01-01 14:00"
}

Delete customer file

This API enables you to delete a registered customer file. If the customer file is being used in an ad group, you cannot delete the customer file.

Send a DELETE request with the issued access token and an ad account ID (adAccountId) in the request header. You must pass the customer file ID to be deleted as a parameter when you request. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

URL

DELETE /openapi/v4/customerFiles/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

Header

Name	Type	Description	Required
Authorization	String	Pass an access token in Bearer ${ACCESS_TOKEN} format.	O
adAccountId	Long	Ad account's ID.	O

Parameter

Name	Type	Description	Required
id	Long	Customer file' ID.	O

Sample

Request

curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/customerFiles/{id}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

Delete multiple customer files

This API enables you to delete multiple customer files at once. If the customer file is being used in an ad group, you cannot delete the customer file.

Send a DELETE request with the issued access token and an ad account ID (adAccountId) in the request header. You must pass the customer file IDs to be deleted as a parameter when you request. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

URL

DELETE /openapi/v4/customerFiles?customerFileIds=${customerFileIds} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

Header

Name	Type	Description	Required
Authorization	String	Pass an access token in Bearer ${ACCESS_TOKEN} format.	O
adAccountId	Long	Ad account's ID.	O

Parameter

Name	Type	Description	Required
customerFileIds	String	Customer file' ID. To pass multiple Customer file IDs, separate them with a comma(,).	O

Sample

Request

curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/customerFiles?customerFileIds=${customerFileId},${customerFileId}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "successCount": 1,
    "failCount": 1,
    "errorMessages": [
        "타겟을 사용 중인 오디언스가 있습니다."
    ]
}

View usage of customer file

This API enables you to retrieve the list of ad groups and campaigns that use the designated customer file.

Send a GET request with the issued access token and an ad account ID (adAccountId) in the request header. You must pass the customer file's ID as a parameter when you request. If the request is successful, this API returns the list of ad groups and campaigns that use the corresponding customer file in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

URL

GET /openapi/v4/customerFiles/usages/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

Header

Name	Type	Description	Required
Authorization	String	Pass an access token in Bearer ${ACCESS_TOKEN} format.	O
adAccountId	Long	Ad account's ID.	O

Parameter

Name	Type	Description	Required
id	Long	Customer file' ID.	O

Response

Name	Type	Description
-	AdGroupAndCampaign[]	List of ad groups and campaigns using the customer file.

AdGroupAndCampaign

Name	Type	Description
adGroup	AdGroup	Information of the ad group.
campaign	Campaign	Information of the campaign.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles/usages/{id}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"

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"
            }
        }
    }
]

See more

• Kakao Moment API Reference