DocuSign

Connect to DocuSign for electronic signatures, envelope management, and document automation.

Overview

DocuSign is an industry-leading e-signature platform. The integration supports:

Envelopes - Create, send, and track signature requests
Templates - Use pre-built document templates
Recipients - Manage signers and routing
Documents - Upload, download, and manage documents
Embedded Signing - Generate signing URLs for in-app experiences
Audit - Track envelope events and history

Prerequisites

DocuSign account (Developer, Standard, or Enterprise)
DocuSign Developer account for sandbox testing
Connected App configured for OAuth
Account ID from DocuSign admin

Authentication

DocuSign uses OAuth 2.0 for authentication via Nango.

# Sandbox
curl "http://localhost:3000/api/v1/connections/docusign-sandbox/auth-url" \
  -H "x-api-key: YOUR_API_KEY"
 
# Production
curl "http://localhost:3000/api/v1/connections/docusign/auth-url" \
  -H "x-api-key: YOUR_API_KEY"

Getting Account ID

Call getUserInfo first to retrieve your account ID:

{
  "action": "docusign.getUserInfo",
  "config": {}
}

Available Actions

Account Actions

getUserInfo

Get user info and available accounts.

{
  "action": "docusign.getUserInfo",
  "config": {
    "providerConfigKey": "docusign-sandbox"
  }
}

Template Actions

listTemplates

List available templates.

{
  "action": "docusign.listTemplates",
  "config": {
    "accountId": "{{input.accountId}}",
    "searchText": "NDA",
    "count": 50,
    "startPosition": 0,
    "order": "desc",
    "orderBy": "modified"
  }
}

getTemplate

Get template details.

{
  "action": "docusign.getTemplate",
  "config": {
    "accountId": "{{input.accountId}}",
    "templateId": "{{input.templateId}}"
  }
}

Envelope Actions

createEnvelope

Create a new envelope (full configuration).

{
  "id": "create-envelope",
  "type": "action",
  "action": "docusign.createEnvelope",
  "config": {
    "accountId": "{{input.accountId}}",
    "templateId": "{{input.templateId}}",
    "emailSubject": "Please sign: {{input.documentName}}",
    "emailBlurb": "Please review and sign this document.",
    "status": "sent",
    "templateRoles": [
      {
        "email": "{{input.signerEmail}}",
        "name": "{{input.signerName}}",
        "roleName": "Signer",
        "routingOrder": "1"
      },
      {
        "email": "{{input.ccEmail}}",
        "name": "{{input.ccName}}",
        "roleName": "CC"
      }
    ],
    "customFields": {
      "textCustomFields": [
        {
          "name": "ContractValue",
          "value": "{{input.contractValue}}"
        }
      ]
    },
    "notification": {
      "useAccountDefaults": false,
      "reminders": {
        "reminderEnabled": true,
        "reminderDelay": 2,
        "reminderFrequency": 2
      },
      "expirations": {
        "expireEnabled": true,
        "expireAfter": 30,
        "expireWarn": 5
      }
    }
  }
}

Parameters:

Field	Type	Required	Description
`accountId`	string	Yes	DocuSign account ID
`templateId`	string	No	Template to use
`documents`	array	No	Documents (if not using template)
`recipients`	object	No	Recipients object
`templateRoles`	array	No	Template role assignments
`emailSubject`	string	No	Email subject line
`emailBlurb`	string	No	Email body message
`status`	string	No	`created` (draft) or `sent`
`customFields`	object	No	Custom metadata fields
`notification`	object	No	Reminder/expiration settings
`brandId`	string	No	Branding theme ID

createEnvelopeFromTemplate

Simplified envelope creation from template.

{
  "action": "docusign.createEnvelopeFromTemplate",
  "config": {
    "accountId": "{{input.accountId}}",
    "templateId": "{{input.templateId}}",
    "recipients": [
      {
        "email": "{{input.email}}",
        "name": "{{input.name}}",
        "roleName": "Signer"
      }
    ],
    "emailSubject": "Contract for {{input.companyName}}",
    "status": "sent"
  }
}

getEnvelope

Get envelope details.

{
  "action": "docusign.getEnvelope",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "include": "recipients,documents"
  }
}

getEnvelopeStatus

Get envelope status.

{
  "action": "docusign.getEnvelopeStatus",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{steps.create.output.envelopeId}}"
  }
}

Envelope Statuses:

Status	Description
`created`	Draft, not yet sent
`sent`	Sent for signature
`delivered`	Viewed by recipients
`signed`	Signed by all recipients
`completed`	Finished and closed
`declined`	Declined by recipient
`voided`	Voided by sender

listEnvelopes

List envelopes with filters.

{
  "action": "docusign.listEnvelopes",
  "config": {
    "accountId": "{{input.accountId}}",
    "fromDate": "2024-01-01",
    "toDate": "2024-12-31",
    "status": "completed",
    "searchText": "Contract",
    "count": 50,
    "order": "desc",
    "orderBy": "last_modified"
  }
}

updateEnvelope

Update envelope properties.

{
  "action": "docusign.updateEnvelope",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "emailSubject": "Updated: {{input.newSubject}}",
    "resend": true
  }
}

sendEnvelope

Send a draft envelope.

{
  "action": "docusign.sendEnvelope",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}"
  }
}

voidEnvelope

Void an envelope.

{
  "action": "docusign.voidEnvelope",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "voidedReason": "Contract terms changed"
  }
}

sendReminder

Send reminder to recipients.

{
  "action": "docusign.sendReminder",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}"
  }
}

Document Actions

listDocuments

List documents in an envelope.

{
  "action": "docusign.listDocuments",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}"
  }
}

downloadDocument

Download a specific document.

{
  "action": "docusign.downloadDocument",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "documentId": "1",
    "certificate": false,
    "watermark": false
  }
}

downloadCombinedDocument

Download all documents as one PDF.

{
  "action": "docusign.downloadCombinedDocument",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "certificate": true
  }
}

Recipient Actions

getRecipients

Get envelope recipients.

{
  "action": "docusign.getRecipients",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "includeTabs": true,
    "includeExtended": true
  }
}

updateRecipients

Update envelope recipients.

{
  "action": "docusign.updateRecipients",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "recipients": {
      "signers": [
        {
          "recipientId": "1",
          "email": "{{input.newEmail}}",
          "name": "{{input.newName}}"
        }
      ]
    },
    "resendEnvelope": true
  }
}

deleteRecipients

Remove recipients from envelope.

{
  "action": "docusign.deleteRecipients",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "recipients": {
      "signers": [
        { "recipientId": "2" }
      ]
    }
  }
}

Embedded Signing Actions

createRecipientView

Create embedded signing URL.

{
  "id": "get-signing-url",
  "type": "action",
  "action": "docusign.createRecipientView",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{steps.create-envelope.output.envelopeId}}",
    "email": "{{input.signerEmail}}",
    "userName": "{{input.signerName}}",
    "clientUserId": "{{input.userId}}",
    "authenticationMethod": "none",
    "returnUrl": "https://yourapp.com/signing-complete",
    "pingUrl": "https://yourapp.com/webhook/docusign-status",
    "pingFrequency": 60
  }
}

Response:

{
  "url": "https://demo.docusign.net/Signing/...",
  "expires_at": "2024-01-15T12:00:00Z"
}

createSenderView

Create embedded sending URL.

{
  "action": "docusign.createSenderView",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "returnUrl": "https://yourapp.com/sending-complete"
  }
}

createEditView

Create embedded edit URL.

{
  "action": "docusign.createEditView",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "returnUrl": "https://yourapp.com/edit-complete"
  }
}

createCorrectView

Create embedded correction URL.

{
  "action": "docusign.createCorrectView",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}",
    "returnUrl": "https://yourapp.com/correct-complete",
    "suppressNavigation": false
  }
}

Audit Actions

getAuditEvents

Get envelope audit trail.

{
  "action": "docusign.getAuditEvents",
  "config": {
    "accountId": "{{input.accountId}}",
    "envelopeId": "{{input.envelopeId}}"
  }
}

Webhook Triggers

DocuSign Connect webhooks trigger workflows on envelope events.

{
  "trigger": {
    "type": "webhook",
    "provider": "docusign",
    "events": ["envelope-completed", "envelope-declined"]
  }
}

Event Types:

Event	Description
`envelope-sent`	Envelope sent
`envelope-delivered`	Envelope viewed
`envelope-completed`	All signatures collected
`envelope-declined`	Recipient declined
`envelope-voided`	Envelope voided
`recipient-completed`	Individual recipient signed

Example Workflow

Contract signing workflow:

{
  "name": "Send Contract on Deal Close",
  "trigger": {
    "type": "webhook",
    "provider": "hubspot",
    "events": ["deal.propertyChange"]
  },
  "steps": [
    {
      "id": "check-stage",
      "type": "condition",
      "config": {
        "conditions": {
          "and": [
            { "left": "{{input[0].propertyName}}", "operator": "eq", "right": "dealstage" },
            { "left": "{{input[0].propertyValue}}", "operator": "eq", "right": "closedwon" }
          ]
        },
        "then": ["get-deal"],
        "else": []
      }
    },
    {
      "id": "get-deal",
      "type": "action",
      "action": "hubspot.getDeal",
      "config": {
        "dealId": "{{input[0].objectId}}",
        "properties": ["dealname", "amount", "closedate"]
      }
    },
    {
      "id": "get-contact",
      "type": "action",
      "action": "hubspot.getAssociations",
      "config": {
        "objectType": "deals",
        "objectId": "{{input[0].objectId}}",
        "toObjectType": "contacts"
      }
    },
    {
      "id": "create-contract",
      "type": "action",
      "action": "docusign.createEnvelopeFromTemplate",
      "config": {
        "accountId": "{{env.DOCUSIGN_ACCOUNT_ID}}",
        "templateId": "{{env.CONTRACT_TEMPLATE_ID}}",
        "recipients": [
          {
            "email": "{{steps.get-contact.output.results[0].email}}",
            "name": "{{steps.get-contact.output.results[0].firstname}} {{steps.get-contact.output.results[0].lastname}}",
            "roleName": "Signer"
          }
        ],
        "emailSubject": "Service Agreement - {{steps.get-deal.output.properties.dealname}}",
        "status": "sent"
      }
    },
    {
      "id": "notify-sales",
      "type": "action",
      "action": "slack.sendMessage",
      "config": {
        "channel": "#sales",
        "text": "Contract sent for {{steps.get-deal.output.properties.dealname}} (${{steps.get-deal.output.properties.amount}})"
      }
    }
  ]
}

Rate Limits

Limit	Value
API calls	1,000/hour (standard)
Envelopes/day	Based on plan
Embedded signing URLs	5 per recipient per envelope

Troubleshooting

Common Errors

Error	Cause	Solution
`accountId is required`	Missing account ID	Call getUserInfo first
`templateId is required`	No template specified	Provide templateId or documents
`AUTHENTICATION_FAILED`	Invalid credentials	Check OAuth connection
`ENVELOPE_NOT_IN_CORRECT_STATE`	Wrong envelope status	Check status before operation
`RECIPIENT_NOT_FOUND`	Invalid recipient ID	Verify recipient exists

Sandbox vs Production

Use different provider config keys:

Sandbox: docusign-sandbox
Production: docusign

Configure both in your Nango setup for proper testing.

DocuSign

On this page