이 문서는 고객파일 API 사용 방법을 안내합니다.
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/customerFiles |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
업로드된 고객파일 목록을 조회합니다. 광고그룹 생성 및 수정 시 [맞춤 타겟] > [내 데이터]에서 활용 가능합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 JSON
객체로 생성한 고객파일 목록 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 |
---|---|---|
- | CustomerFile[] |
업로드된 고객파일 목록 |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
고객파일 번호 |
adAccountId | Long |
광고계정 번호 |
name | String |
고객파일 이름 |
adidListKey | String |
고객파일 등록 Key |
ready | Boolean |
준비완료 여부 |
customerFileStatus | String |
상태WAITING (고객파일 모수추출 대기중)COMPLETE (모수추출 완료)DELETE (삭제 또는 삭제중인 상태)ERROR (그 외 비정상적인 경우)MODIFYING (수정된 모수 준비중) 중 하나 |
createdDate | String |
타겟 생성일시yyyy-MM-dd HH:mm:ss 형식 |
lastModifiedDate | String |
타겟 마지막 수정일시yyyy-MM-dd HH:mm:ss 형식 |
originalCreatedDate | String |
타겟 생성일시 고객파일을 수정한 경우 최초 등록한 고객파일의 생성일시 yyyy-MM-dd HH:mm:ss 형식 |
populationUpdateDate | String |
타겟 업데이트 일시 타겟모수가 업데이트된 시간 yyyy-MM-dd HH:mm:ss 형식 |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
{
"id": 1,
"adAccountId": 1234,
"name": "첫번째_고객파일",
"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"
}
]
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/customerFiles/${ID} |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
고객파일 상세 정보를 조회합니다.
사용자 액세스 토큰(Access token)을 헤더에 담아 GET
으로 고객파일 번호를 전달하여 요청합니다. 요청 성공 시 응답은 대상 고객파일의 상세 정보를 포함합니다.
이 API는 고객파일마다 5초에 한 번씩 요청이 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ID | Long |
고객파일 번호 | O |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
고객파일 번호 |
adAccountId | Long |
광고계정 번호 |
name | String |
고객파일 이름 |
adidListKey | String |
고객파일 등록 Key |
ready | Boolean |
준비완료 여부 |
customerFileStatus | String |
상태WAITING (고객파일 모수추출 대기중),COMPLETE (모수추출 완료),DELETE (삭제 또는 삭제중인 상태),MODIFYING (수정된 모수 준비중),ERROR (그 외 비정상적인 경우) 중 하나 |
populationScore | Long |
타겟 모수 등록한 고객파일에서 추출된 카카오 사용자 수로 준비 중인 고객파일은 모수 추출 이전 단계로 타게팅에 사용할 수 없으며, 고객파일을 등록 후 최대 6시간 이내에 모수 추출이 완료됨 |
createdDate | String |
타겟 생성일시yyyy-MM-dd HH:mm:ss 형식 |
lastModifiedDate | String |
타겟 마지막 수정일시yyyy-MM-dd HH:mm:ss 형식 |
originalCreatedDate | String |
타겟 생성일시 고객파일을 수정한 경우 최초 등록한 고객파일의 생성일시 yyyy-MM-dd HH:mm:ss 형식 |
populationUpdateDate | String |
타겟 업데이트 일시 타겟모수가 업데이트된 시간 yyyy-MM-dd HH:mm:ss 형식 |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles/${ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1,
"adAccountId": 1234,
"name": "첫번째_고객파일",
"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"
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/customerFiles |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
광고그룹 생성 및 수정 시 사용할 정보를 파일 형태로 업로드할 수 있습니다. 이 API는 Multipart/form-data
방식만 지원합니다. 하나의 고객파일은 10개 이하의 CSV 파일(총합 200MB 이하)을 업로드하여 구성할 수 있으며, 계정당 최대 50개의 고객파일을 등록할 수 있습니다. 파일 등록 후 최대 6시간 이내로 모수가 추출됩니다. 고객파일 파일 내용 형식은 가이드 및 예제를 참고합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 POST
로 요청합니다. 고객파일 이름, 파일을 필수 파라미터로 전달해야 합니다. 성공 시 등록에 성공한 고객파일의 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
name | String |
고객파일 이름 한글, 영문, 특수문자, 공백을 허용하며 50자 이내 |
O |
files | MultipartFile |
고객파일MimeType 이 text/csv 인 csv 확장자를 가진 파일최대 10개의 파일 업로드 가능 총합 200MB까지 허용 |
O |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
고객파일 번호 |
adAccountId | Long |
광고계정 번호 |
name | String |
고객파일 이름 |
successCount | Integer |
성공 횟수 |
failedCount | Integer |
실패 횟수 |
successFileUrl | String |
성공 데이터 파일 URL |
failedFileUrl | String |
실패 데이터 파일 URL |
fileType | String |
파일 유형 ADID |
customerFileStatus | String |
상태WAITING (대기중) |
dataRegStatusTargeting | String |
모수 추출 타게팅 상태STANDBY (대기중) |
dataRegStatusPopulation | String |
모수 추출 상태STANDBY (대기중) |
createdDate | String |
생성일시yyyy-MM-dd'T'HH:mm:ss 형식 |
curl -X POST "https://apis.moment.kakao.com/openapi/v4/customerFiles" \
-H "Authorization: Bearer ${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=첫번째_고객파일"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1,
"adAccountId": 1234,
"name": "첫번째_고객파일",
"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"
}
메서드 | URL | 인증 방식 |
---|---|---|
PUT |
https://apis.moment.kakao.com/openapi/v4/customerFiles |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
광고그룹 생성 및 수정 시 사용할 정보를 파일 형태로 업로드할 수 있습니다. 이 API는 Multipart/form-data
방식만 지원합니다. 하나의 고객파일은 10개 이하의 CSV 파일(총합 200MB 이하)을 업로드하여 구성할 수 있으며, 계정당 최대 30개의 고객파일을 등록할 수 있습니다. 파일 등록 후 최대 12시간 이내로 모수가 추출됩니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 PUT
으로 요청합니다. 고객파일 이름, 파일을 필수 파라미터로 전달해야 합니다. 성공 시 등록에 성공한 고객파일의 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이 API는 고객파일마다 5초에 한 번씩 요청이 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | Long |
수정하고자 하는 고객파일 ID | O |
files | MultipartFile |
고객파일MimeType 이 text/csv 인 csv 확장자를 가진 파일최대 10개의 파일 업로드 가능 총합 200MB까지 허용 |
O |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
고객파일 번호 |
adAccountId | Long |
광고계정 번호 |
name | String |
고객파일 이름 |
successCount | Integer |
성공 횟수 |
failedCount | Integer |
실패 횟수 |
successFileUrl | String |
성공 데이터 파일 URL |
failedFileUrl | String |
실패 데이터 파일 URL |
fileType | String |
파일 유형 ADID |
customerFileStatus | String |
상태 WAITING (대기중) |
dataRegStatusTargeting | String |
모수 추출 타게팅 상태 STANDBY (대기중) |
dataRegStatusPopluation | String |
모수 추출 상태 STANDBY (대기중) |
createdDate | String |
생성일시 yyyy-MM-dd HH:mm:ss |
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerFiles" \
-H "Authorization: Bearer ${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": "첫번째_고객파일",
"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"
}
메서드 | URL | 인증 방식 |
---|---|---|
PUT |
https://apis.moment.kakao.com/openapi/v4/customerFiles/name |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
고객파일 이름을 수정합니다. 이미 등록된 파일의 수정은 불가능하며 이름만 수정 가능합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 PUT
으로 요청합니다. 이름을 수정할 고객파일 번호와 수정할 고객파일 이름을 필수 파라미터로 전달해야 합니다. 성공 시 수정된 고객파일 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | Long |
고객파일 번호 | O |
name | String |
수정할 고객파일 이름 한글, 영문, 특수문자, 공백을 허용하며 50자 이내 |
O |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
고객파일 번호 |
adAccountId | Long |
광고계정 번호 |
name | String |
고객파일 이름 |
adidListKey | String |
고객파일 등록 Key |
ready | Boolean |
준비완료 여부 |
customerFileStatus | String |
상태 WAITING (고객파일 모수추출 대기중), COMPLETE (모수추출 완료), ERROR (그 외 비정상적인 경우) 중 하나 |
createdDate | String |
생성일시yyyy-MM-dd HH:mm:ss 형식 |
lastModifiedDate | String |
마지막 수정일시yyyy-MM-dd HH:mm:ss 형식 |
originalCreatedDate | String |
타겟 생성일시 고객파일을 수정한 경우 최초 등록한 고객파일의 생성일시 yyyy-MM-dd HH:mm:ss 형식 |
populationUpdateDate | String |
타겟 업데이트 일시 타겟모수가 업데이트된 시간 yyyy-MM-dd HH:mm:ss 형식 |
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/customerFiles/name" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-d '{
"id": 123,
"name": "변경한_고객파일이름"
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1,
"adAccountId": 27429,
"name": "변경한_고객파일이름",
"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"
}
메서드 | URL | 인증 방식 |
---|---|---|
DELETE |
https://apis.moment.kakao.com/openapi/v4/customerFiles/${ID} |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
등록된 고객파일을 삭제합니다. 광고그룹에서 사용 중일 경우 삭제가 불가능합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 DELETE
로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ID | Long |
고객파일 번호 | O |
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/customerFiles/${ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
메서드 | URL | 인증 방식 |
---|---|---|
DELETE |
https://apis.moment.kakao.com/openapi/v4/customerFiles |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
복수의 고객파일을 한 번에 고객파일을 삭제합니다. 광고그룹에서 사용 중일 경우 삭제가 불가능합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 DELETE
로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
customerFileIds | String |
고객파일 번호 여러 개의 고객파일 번호를 쉼표(,)로 구분한 하나의 문자열로 전달 |
O |
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/customerFiles?customerFileIds=${CUSTOMER_FILE_ID},${CUSTOMER_FILE_ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
{
"successCount": 1,
"failCount": 1,
"errorMessages": [
"타겟을 사용 중인 오디언스가 있습니다."
]
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/customerFiles/usages/${ID} |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
지정한 고객파일을 사용 중인 광고그룹 및 캠페인 목록을 조회합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청하며, 고객파일 번호를 필수 파라미터로 전달해야 합니다. 성공 시 고객파일을 사용 중인 광고그룹 및 캠페인의 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ID | Long |
고객파일 번호 | O |
이름 | 타입 | 설명 |
---|---|---|
- | AdGroupAndCampaign[] |
고객파일을 사용 중인 광고그룹 및 캠페인 목록 |
이름 | 타입 | 설명 |
---|---|---|
adGroup | AdGroup |
광고그룹 |
campaign | Campaign |
캠페인 |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/customerFiles/usages/${ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
{
"adGroup": {
"id": 56,
"name": "첫번째_광고그룹",
"adGroupStatus": [
"LIVE"
],
"adGroupType": "DISPLAY"
},
"campaign": {
"id": 78,
"name": "첫번째_캠페인",
"campaignTypeGoal": {
"campaignType": "DISPLAY",
"goal": "VISITING"
}
}
}
]