# 批量写入黑名单

该接口用于将一批号码写入号码黑名单。命中黑名单的号码在外呼时将被拦截。

<span style="display:inline-block;background:#e6f8ea;color:#fca130;border-radius:6px;padding:2px 8px;font-weight:bold;font-family:monospace;margin-right:8px;">POST</span>
`https://dashboard.avavox.com/open/api/v1/phone-blacklists/batch-create`

## 请求头

<span style="font-family:monospace; color:#3451b2; ">Authorization </span> <code style="background:#f0f0f0; ">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

- 填写格式：`Authorization: Bearer <App Key>`
- `<App Key>` 为控制台「App Key 管理」页面生成的 Key。
- 获取方式详见：[《App Key 创建与管理》](https://avavox.com/docs/developer/app-key.html)。



## 请求体参数

<span style="font-family:monospace; color:#3451b2;">entries</span> <code style="background:#f0f0f0;">array</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

需要写入的黑名单列表，单次最大 2000 条。数组元素结构如下：

<details>
<summary>点击展开字段说明</summary>
<div style="margin: 16px 0; padding: 16px;  border-left: 1px solid #f0f0f0; border-radius: 6px;">

<span style="font-family:monospace; color:#3451b2;">phoneNumber</span> <code style="background:#f0f0f0;">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

号码。支持标准手机号，也支持固话。同一号码重复提交时，以最后一条为准。

---

<span style="font-family:monospace; color:#3451b2;">reason</span> <code style="background:#f0f0f0;">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

加入黑名单原因，枚举值：

- `user_opt_out`：     用户拒绝
- `complaint_risk`：   投诉风险
- `invalid_number`： 无效号码
- `internal_test`：内部测试
- `carrier_number_pool`：运营商号码池
- `other`： 其他

---

<span style="font-family:monospace; color:#3451b2;">remark</span> <code style="background:#f0f0f0;">string</code> <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

备注，最大长度 255。

</div>
</details>


## 响应数据

<span style="font-family:monospace; color:#3451b2;">code</span> <code style="background:#f0f0f0;">int</code>

状态码，200 为成功，其他状态均为失败。

---

<span style="font-family:monospace; color:#3451b2;">success</span> <code style="background:#f0f0f0;">boolean</code>

是否成功，`true` 表示成功，`false` 表示失败。

---

<span style="font-family:monospace; color:#3451b2;">message</span> <code style="background:#f0f0f0;">string</code>

描述信息。

---

<span style="font-family:monospace; color:#3451b2;">data</span> <code style="background:#f0f0f0;">object</code>

<details>
<summary>点击展开字段说明</summary>
<div style="margin: 16px 0; padding: 16px;  border-left: 1px solid #f0f0f0; border-radius: 6px;">

<span style="font-family:monospace; color:#3451b2;">total</span> <code style="background:#f0f0f0;">int</code>

本次请求去重后的处理总条数。

---

<span style="font-family:monospace; color:#3451b2;">successCount</span> <code style="background:#f0f0f0;">int</code>

写入成功条数。

---

<span style="font-family:monospace; color:#3451b2;">failCount</span> <code style="background:#f0f0f0;">int</code>

写入失败条数。

---

<span style="font-family:monospace; color:#3451b2;">failedItems</span> <code style="background:#f0f0f0;">array</code>

失败明细，元素结构：`phoneNumber`（失败号码）、`reason`（失败原因）。全部成功时为空数组。

</div>
</details>

## 请求示例

```shell
curl -X POST --location 'https://dashboard.avavox.com/open/api/v1/phone-blacklists/batch-create' \
--header 'Authorization: Bearer $Key' \
--header 'Content-Type: application/json' \
--data '{
  "entries": [
    {
      "phoneNumber": "13800000000",
      "reason": "carrier_number_pool",
      "remark": "2026-05 来自工单系统"
    },
    {
      "phoneNumber": "139000",
      "reason": "complaint_risk",
      "remark": ""
    }
  ]
}'
```

## 响应示例

```json
{
  "code": 200,
  "message": "操作成功",
  "success": true,
  "data": {
    "total": 2,
    "successCount": 1,
    "failCount": 1,
    "failedItems": [
      {
        "phoneNumber": "139000",
        "reason": "号码格式不支持"
      }
    ]
  }
}
```