如何通过DocuSign API确定远程签署收件人的操作行为

Great question! Tracking exactly what actions a recipient takes on your DocuSign envelope—like signing, declining, or viewing—is totally manageable with a couple of key API features. Let me walk you through the main methods:

1. Use DocuSign Connect (Webhooks) for Real-Time Notifications #

This is the most efficient way to get instant updates when a recipient takes an action. Here's how it works:

• Set up a DocuSign Connect webhook in your account, pointing to a publicly accessible endpoint on your server.
• Configure the webhook to listen for specific recipient events: check boxes for Recipient Completed, Recipient Declined, Recipient Viewed, and any other actions you care about.
• When an event triggers, DocuSign will send a POST payload to your endpoint with detailed data, including:
  • recipientEventStatus: The exact action taken (e.g., completed, declined, viewed)
  • recipientId, name, and email of the user who acted
  • Timestamps for when the action occurred
  • Additional context like IP address (for signing/viewing events) or decline reason (for rejection events)

2. Poll the Envelope Status API for On-Demand Checks #

If real-time updates aren't critical, you can periodically fetch the envelope's status to check recipient actions:

• Call the GET /v2.1/accounts/{accountId}/envelopes/{envelopeId} endpoint.
• In the response, look at the recipients array—each entry corresponds to a recipient and includes:
  • status: The core state (e.g., Completed, Declined, Viewed)
  • statusChangedDateTime: When the recipient's last action happened
  • recipientActionDetails: A list of specific actions the recipient took (e.g., Sign with a timestamp)
  • declinedReason: If applicable, the text the recipient entered when rejecting the envelope

3. Fetch Individual Recipient Status for Granular Details #

If you only need info about a single recipient, use this targeted endpoint:

• Call GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}
• This returns a full history of that recipient's interactions with the envelope, including every time they viewed the document, attempted to sign, or took other actions.

Common Status Values & Their Corresponding Actions #

Here's a quick cheat sheet for what statuses mean:

• Completed: Recipient successfully finished all required actions (most commonly signing)
• Declined: Recipient rejected the envelope
• Viewed: Recipient opened and viewed the document
• Delivered: Envelope was sent to the recipient's inbox but no action was taken yet
• Sent: Envelope was queued to be sent to the recipient

Example API Response Snippet #

Here’s a sample of what you’ll see in an envelope status response for a completed signer:

{
  "envelopeId": "d123456-7890-abcd-efgh-ijklmnopqrst",
  "status": "Completed",
  "recipients": {
    "signers": [
      {
        "recipientId": "1",
        "name": "Jane Smith",
        "email": "jane.smith@example.com",
        "status": "Completed",
        "completedDateTime": "2024-05-21T10:30:00Z",
        "recipientActionDetails": [
          {
            "action": "Sign",
            "actionDateTime": "2024-05-21T10:29:45Z",
            "ipAddress": "203.0.113.45"
          }
        ]
      }
    ]
  }
}

Pro Tip #

DocuSign Connect is usually the best choice for production systems—it avoids unnecessary polling and ensures you get updates the second an action happens. Just make sure your endpoint is secure and can handle the incoming POST requests reliably.

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