DocuSign REST API：原收件人配置2FA时的重新指派功能问询

我来分享下对这个场景的理解和可行的解决方案，之前处理过类似的DocuSign API需求：

先明确两种2FA场景的默认行为 #

访问码验证场景 #

DocuSign的访问码是**绑定到收件人任务（而非特定用户）**的，所以默认情况下，重新指派后新收件人需要输入原访问码。这是因为访问码属于信封层级的收件人验证配置，系统会把这个验证要求和签署任务一起传递，而不是限定给原收件人——这就是你测试时看到原访问码被一并指派的原因。

短信验证场景 #

短信验证的逻辑和访问码不同，它是直接绑定原收件人的手机号码的。当你完成原收件人的短信验证后重新指派，系统并没有更新验证关联的手机号，导致新收件人点击链接时，系统仍尝试向原号码发送验证码，但新收件人无法获取，最终抛出无明确提示的错误——这是DocuSign的默认行为，也是你遇到问题的核心原因。

如何修改行为，让新收件人无需使用原2FA #

要解决这个问题，核心是在重新指派时通过API主动覆盖原收件人的验证设置，具体有几种方式：

1. 重新指派时直接关闭验证要求 #

调用DocuSign的收件人更新API（PUT /envelopes/{envelopeId}/recipients）时，在请求体中为新收件人设置requireIdLookup: false，同时清除原有的验证参数。示例请求体如下：

{
  "recipients": {
    "signers": [
      {
        "email": "new_signer@example.com",
        "name": "New Signer Name",
        "recipientId": "1", // 对应原收件人的recipientId
        "requireIdLookup": "false",
        "accessCode": "", // 清空原访问码
        "smsAuthentication": null // 清空原短信验证配置
      }
    ]
  },
  "resendEnvelope": true // 可选：自动给新收件人发送签署邮件
}

2. 为新收件人设置新的验证规则 #

如果仍需要新收件人验证，但不想用原2FA，可以在重新指派时为其配置新的访问码或短信验证：

{
  "recipients": {
    "signers": [
      {
        "email": "new_signer@example.com",
        "name": "New Signer Name",
        "recipientId": "1",
        "requireIdLookup": "true",
        "accessCode": "new_secure_code_456" // 设置新访问码
        // 或者设置新短信验证：
        // "smsAuthentication": {
        //   "senderProvidedNumbers": ["+1234567890"]
        // }
      }
    ]
  },
  "resendEnvelope": true
}

3. 调整账户或模板的默认配置 #

• 如果是模板创建的信封，可以在模板中不预先设置强制2FA，而是在发送信封时动态添加验证规则，这样重新指派时更灵活。
• 部分账户级别的设置可能影响重新指派时的验证继承行为，若API调整无法满足需求，可以联系DocuSign支持检查账户配置，看是否有开关可以修改默认逻辑。

是否有人成功实现该场景？ #

当然有很多开发者遇到过相同的需求，通过上述API覆盖验证设置的方法就能成功实现。只要在重新指派的请求中明确修改新收件人的验证参数，就能绕过原收件人的2FA要求，让新收件人正常签署。

内容的提问来源于stack exchange，提问作者marcusstarnes