Do Not Reach List

GET accounts/:account_id/do_not_reach_lists¶

检索与当前账号关联的部分或所有 Do Not Reach List 的详细信息。

注意：一个 account_id 最多只能有一个 Do Not Reach List

资源 URL¶

https://ads-api.twitter.com/10/accounts/:account_id/do_not_reach_lists

参数¶

请求示例¶

GET https://ads-api.twitter.com/10/accounts/18ce54bgxky/do_not_reach_lists

响应示例¶

{
  "request": {
    "params": {
      "account_id": "18ce54bgxky"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "targetable": false,
      "name": "Do Not Reach List",
      "description": "test DNRL",
      "id": "4kzrq",
      "reasons_not_targetable": [
        "TOO_SMALL"
      ],
      "created_at": "2021-10-28T22:09:29Z",
      "list_size": null,
      "updated_at": "2021-11-04T03:33:06Z",
      "deleted": false
    }
  ]
}

POST accounts/:account_id/do_not_reach_lists¶

创建与当前账号关联的新 Do Not Reach List 标签。

注意：一个 account_id 最多只能有一个 Do Not Reach List

资源 URL¶

https://ads-api.twitter.com/10/accounts/:account_id/do_not_reach_lists

参数¶

请求示例¶

POST https://ads-api.twitter.com/10/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude

响应示例¶

{
  "request": {
    "params": {
      "description": "A list of users to exclude",
      "account_id": "18ce54bgxky"
    }
  },
  "data": {
    "targetable": false,
    "name": "Do Not Reach List",
    "description": "A list of users to exclude",
    "id": "4ofrq",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "created_at": "2022-02-08T23:02:48Z",
    "list_size": null,
    "updated_at": "2022-02-08T23:02:48Z",
    "deleted": false
  }
}

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users¶

此端点允许从给定的 do_not_reach_list_id 添加、更新和删除用户。此端点仅接受电子邮件作为有效的用户标识符类型。

emails 请求字段中提供的所有数据必须使用 SHA256 进行哈希运算和规范。

注意

• 一个 account_id 最多只能有一个 Do Not Reach List
• 添加到此列表的用户必须将 expires_at 时间戳设置为距当前时间戳不到 13 个月
• Do Not Reach List API 不接受 effective_at 时间戳，并默认为当前时间戳
• Do Not Reach List 不会从账号中的部分或所有自定义受众中删除用户，而是充当为账号投放的所有广告活动的排除目标

批量请求

• 此端点目前最大的批次大小为 2500。批次大小由每个请求的操作数量 (Update/Delete) 决定。例如，如果一个数组中的操作对象超过 2500 个 ({"operation_type": "Update/Delete", [..] }) ，则会导致错误。
• 此端点可以接受的最大请求 POST 正文大小为 5,000,000 字节。
• 对于每个 1 分钟窗口，此端点的速率限制为 1500
• 所有参数都在请求正文中发送，并且需要 application/json 的 Content-Type。
• 无论失败或成功，批量请求均作为一个整体，并且错误和成功的所有 API 响应都保留初始请求的项目顺序。

批量响应

广告 API 返回的响应包含两个字段：success_count 和 total_count。这些值必须始终相等，它们是请求中已由后端处理的记录计数。如果请求正文中发送的记录数不等于 success_count 和 total_count，则应视为错误，需要重试。

批量错误

• 请求级别的错误（例如，超过最大批量大小）会显示在 errors 对象下的响应中。
• 项目级别的错误（例如，缺少必需参数）会显示在 operation_errors 对象下的响应中。
• operation_errors 中错误的索引是指输入项目中的索引，内含相应的错误信息

资源 URL¶

https://ads-api.twitter.com/10/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

参数¶

请求示例¶

POST https://ads-api.twitter.com/10/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users

[
  {
    "operation_type": "Update",
    "params": {
      "effective_at": "2021-10-21T07:27:00Z",
      "expires_at": "2021-12-22T00:00:00Z",
      "emails": [
        "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC",
        "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
      ]
    }
  }
]

响应示例¶

{
  "data": [
    {
      "success_count": 2,
      "total_count": 2
    }
  ],
  "request": [
    {
      "params": {
        "do_not_reach_list_id": "4kzrq",
        "emails": [
          "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC",
          "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
        ],
        "account_id": "18ce54bgxky"
      },
      "operation_type": "Update"
    }
  ]
}

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id¶

删除属于当前账号的指定 Do Not Reach List。

资源 URL¶

https://ads-api.twitter.com/10/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

参数¶

无

请求示例¶

DELETE https://ads-api.twitter.com/10/accounts/18ce54bgxky/do_not_reach_lists/4ofrp

响应示例¶

{
  "request": {
    "params": {
      "do_not_reach_list_id": "4ofrp",
      "account_id": "18ce54bgxky"
    }
  },
  "data": {
    "targetable": false,
    "name": "Do Not Reach List",
    "description": null,
    "id": "4ofrp",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "created_at": "2022-02-08T23:02:07Z",
    "list_size": null,
    "updated_at": "2022-02-08T23:02:21Z",
    "deleted": true
  }
}