> ## Documentation Index
> Fetch the complete documentation index at: https://developer.effilink.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 联系组API

> 在 EffiLink 中添加、搜索与删除联系人名单。将联系人组织为静态或动态分组，并分页浏览你的所有名单。

## 认证

所有端点均接受 `ApiKey` 请求头或 `OAuth` 请求头。请参见 [OAuth 端点](/zh/api/oauth)页面了解令牌生成。

***

## 添加组

<api-endpoint method="POST" url="https://api.effilink.co/v5/lists/add" />

创建一个带可选描述的新联系人组。

### 请求体

<ParamField body="listName" type="string" required>
  新联系人组的唯一名称。
</ParamField>

<ParamField body="listDescription" type="string">
  对组用途或受众的简短描述。
</ParamField>

<ParamField body="sandboxMode" type="boolean">
  为 `true` 时,操作被模拟且不创建任何组。
</ParamField>

### 响应

<ResponseField name="code" type="int">
  成功时为 `200`。
</ResponseField>

<ResponseField name="message" type="string">
  成功时为空字符串;失败时为错误描述。
</ResponseField>

```bash theme={null}
curl --request POST \
  --url https://api.effilink.co/v5/lists/add \
  --header 'Content-Type: application/json' \
  --header 'ApiKey: YOUR_API_KEY' \
  --data '{
    "listName": "VIP Customers",
    "listDescription": "High-value customer segment"
  }'
```

```json Response theme={null}
{
  "code": 200,
  "message": ""
}
```

***

## 获取组

<api-endpoint method="POST" url="https://api.effilink.co/v5/lists/get" />

返回属于您账户的分页、可选过滤的联系人组集合。

### 请求体

<ParamField body="search" type="string">
  按名称过滤组。返回名称包含此字符串的所有组。
</ParamField>

<ParamField body="listType" type="string">
  按组类型过滤:

  * `"0"` — 动态组(基于规则的成员资格)。
  * `"1"` — 静态组(手动管理的成员资格)。
</ParamField>

<ParamField body="sort" type="string">
  结果的排序字段。可接受值:

  * `"CreateDate"` — 按创建日期排序。
  * `"ModifyDate"` — 按最后修改日期排序。
</ParamField>

<ParamField body="pageSize" type="int">
  每页返回的组数。默认为 `10`。
</ParamField>

<ParamField body="pageIndex" type="int">
  从 1 开始的页码。默认为 `1`。
</ParamField>

### 响应

<ResponseField name="code" type="int">
  成功时为 `200`。
</ResponseField>

<ResponseField name="message" type="string">
  成功时为空字符串;失败时为错误描述。
</ResponseField>

<ResponseField name="lists" type="array[object]">
  匹配查询的组记录数组。

  <Expandable title="list 对象">
    <ResponseField name="Id" type="string">
      组的唯一标识符。
    </ResponseField>

    <ResponseField name="TeamId" type="string">
      拥有组的团队标识符。
    </ResponseField>

    <ResponseField name="listName" type="string">
      组名称。
    </ResponseField>

    <ResponseField name="ListStatus" type="int">
      组的当前状态(例如 `1` = 活跃)。
    </ResponseField>

    <ResponseField name="ListType" type="int">
      `0` 表示动态组;`1` 表示静态组。
    </ResponseField>

    <ResponseField name="ListFilters" type="string">
      动态组的过滤条件。存在于动态组(`ListType: 0`);静态组为空或缺失。
    </ResponseField>

    <ResponseField name="CreateUserId" type="int">
      创建组的用户 ID。
    </ResponseField>

    <ResponseField name="CreateDate" type="string">
      组创建时间的 ISO 8601 时间戳。
    </ResponseField>

    <ResponseField name="ModifyDate" type="string">
      组最近一次更新的 ISO 8601 时间戳。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalRecords" type="int">
  跨所有页面匹配查询的组总数。
</ResponseField>

```bash theme={null}
curl --request POST \
  --url https://api.effilink.co/v5/lists/get \
  --header 'Content-Type: application/json' \
  --header 'ApiKey: YOUR_API_KEY' \
  --data '{
    "search": "VIP",
    "pageSize": 20,
    "pageIndex": 1
  }'
```

```json Response theme={null}
{
  "code": 200,
  "message": "",
  "lists": [
    {
      "Id": "abc123",
      "TeamId": "team001",
      "listName": "VIP Customers",
      "ListStatus": 1,
      "ListType": 1,
      "CreateUserId": 42,
      "CreateDate": "2024-01-15T08:00:00.000Z",
      "ModifyDate": "2025-03-10T14:30:00.000Z"
    }
  ],
  "totalRecords": 1
}
```

***

## 删除组

<api-endpoint method="POST" url="https://api.effilink.co/v5/lists/delete" />

按名称永久删除联系人组。组中的联系人**不会**被删除,仅移除组本身。

### 请求体

<ParamField body="listName" type="string" required>
  要删除的联系人组名称。
</ParamField>

<ParamField body="sandboxMode" type="boolean">
  为 `true` 时,操作被模拟且不删除任何组。
</ParamField>

### 响应

<ResponseField name="code" type="int">
  成功时为 `200`。
</ResponseField>

<ResponseField name="message" type="string">
  成功时为空字符串;失败时为错误描述。
</ResponseField>

```json Response theme={null}
{
  "code": 200,
  "message": ""
}
```