# 잠재 고객 API 개요

> 탭조이 오퍼월 잠재고객 API를 사용하여 이미 앱이 설치된 디바이스 목록을 관리하고 해당 사용자가 중복 오퍼를 받지 않도록 방지합니다.

탭조이 잠재 고객 API는 특정 디바이스 목록에서 앱 노출을 제한하는 데 활용할 수 있는 잠재 고객 정보를 생성하고 조회하기 위한 REST API입니다.

## 앱 서프레션##app-suppression

앱 서프레션은 제공된 디바이스에 해당 앱 ID가 이미 설치된 것으로 표시해야 함을 의미합니다. 이 정보는 디바이스에 대한 Unity의 일반 네트워크/SDK 데이터 외부에서 제공됩니다. 예를 들어, 광고주가 이미 앱이 설치된 것으로 확인된 디바이스 목록을 업로드하는 경우입니다. 탭조이는 해당 앱의 오퍼를 '차단'하여 사용자에게 이 앱의 오퍼를 표시하지 않도록 합니다.

## 요청 생성##making-requests

API 요청을 수행하려면 먼저 Unity의 OAuth API를 통해 액세스 토큰을 요청해야 합니다. 이 방법에 대한 자세한 내용은 [여기](./api-authentication.md)입니다.

### 필수 파라미터 및 예상 값##required-parameters-and-expected-values

| 필수 파라미터       | 예상 값                             | 참고                                                            |
| ------------- | -------------------------------- | ------------------------------------------------------------- |
| `account_id`  | 시스템에서 광고주를 인증하기 위한 광고주 계정 ID입니다. |                                                               |
| `name`        | 잠재 고객의 이름입니다.                    |                                                               |
| `description` | 잠재 고객에 대한 설명입니다.                 |                                                               |
| `devices`     | 헤더가 없는 디바이스 ID의 CSV 파일입니다.       | IDFA 및 GAID는 대소문자를 가리지 않으며 하이픈을 포함할 수 있습니다. 이들은 백엔드에서 정규화됩니다. |
| `offer_id`    | 탭조이 `offer_id`(또는 AdSet ID)입니다.  |                                                               |
| `app_id`      | 광고주가 중단하려는 앱의 탭조이 `app_id`입니다.   |                                                               |
| `list_type`   | 앱 서프레션을 요청하는 목록 유형입니다.           | 허용된 값: `['app_suppression']`. 예상 값은 사용 가능한 옵션 중 하나여야 합니다.     |

> **Note:**
>
> 나열된 파라미터(총 7개)는 API 요청에 필수적이지만, API로부터 성공적인 응답을 반환하기 위해 각 파라미터에 대해 모든 값을 기재할 필요는 없습니다.
> 또한 각 요청은 동일한 API 엔드포인트에 대해 이루어집니다.

### 엔드포인트##endpoint

모든 요청은 다음 엔드포인트에 대해 이루어집니다.

```text
https://api.tapjoy.com/v4/audiences
```

### 요청 예시##example-requests

다음 예제는 인증된 API 요청에 필요한 헤더를 보여줍니다.

```curlrc
POST /v4/audiences 
Host: api.tapjoy.com 
Authorization: Bearer <token_string> 
Accept: application/json
```

#### 앱 서프레션##app-suppression

다음 예제는 앱 제거 요청의 파라미터 값을 보여줍니다.

```curlrc
account_id: '497670f6-a152-4bdd-a717-dbe7f7635dc7' 
name: ' ' 
description: ' ' 
devices: device_list_3.csv 
offer_id: ' ' (blank for suppression lists)
app_id: '6881899b-9c55-4d83-9afc-552f880289d4' 
list_type: 'app_suppression'
```

다음 예제는 기기 리스트 파일 업로드 및 쿼리 파라미터를 비롯한 전체 curl 커맨드 동일한 요청을 보여줍니다.

```curlrc
curl --header "Authorization: Bearer YOUR-TOKEN" --request POST --form devices=@/path/to/device_list.csv "https://api.tapjoy.com/v4/audiences?account_id=497670f6-a152-4bdd-a717-dbe7f7635dc7&app_id=6881899b-9c55-4d83-9afc-552f880289d4&description=LIST-DESCRIPTION&list_type=app_suppression&name=LIST-NAME&offer_id="
```

## FAQ##faq

**How often can a client upload an audience for app suppression?:**원할 때마다(예: 1시간) 업로드 가능합니다.**What is the max list of devices I can upload?:**100만대의 디바이스가 소프트 상한입니다. 더 많은 디바이스를 처리하려면 엔지니어링 팀에 문의하십시오.**If I upload two files (for example:, list\\\_one.csv, list\\\_two.csv) are they being replaced or merged?:**앱 서프레션 - CSV에 포함된 모든 디바이스에 지정된 앱이 설치된 것으로 표시됩니다. 두 개의 목록을 보내면 병합됩니다.**Can I delete a list?:**앱 서프레션 - 아니요, 디바이스에 앱이 설치된 것으로 표시된 경우 사용자가 앱을 제거했음을 탭조이에 알릴 방법이 없습니다. 파트너가 디바이스를 제거할 수 있도록 하려면 차단 목록을 사용해야 합니다.**Which MMPs are integrated with the audience API automatically?:**[Appsflyer](../mmp-integrations/appsflyer)