Recipients

To add recipients to your envelopes use the recipients node. There are few required parameters you must provide for each recipient, such as name, email, and recipientId. When signature requests are sent to recipients via email the recipients are known as remote recipients. Alternatively, when you host signing directly through your app or website using embedding the recipients are known as embedded recipients.

Use the Envelopes: create API to create and send envelopes to recipients. For example, to create and send an envelope with one document to a single recipient send an http POST request to:

https://demo.docusign.net/restapi/v2/accounts/{accountId}/envelopes

With the following request body:

{
    "status": "sent",
    "emailSubject": "Example of one recipient, type signer",
    "documents": [{
        "documentId": "1",
        "name": "contract.pdf",
        "documentBase64": "base64 document bytes...",
    }],
    "recipients": {
        "signers": [{
            "email": "sally@email.com",
            "name": "Sally Doe",
            "recipientId": "1",
            "routingOrder": "1",
            "tabs": {
                "signHereTabs": [{
                    "xPosition": "150",
                    "yPosition": "200",
                    "documentId": "1",
                    "pageNumber": "1"
                }],
            }
        }]
    }
}

Adding Recipients to Draft Envelopes

You can also create an envelope then add recipients to it later using the EnvelopeRecipients: update API. To add a signer recipient to a draft envelope send an http PUT request to:

https://demo.docusign.net/restapi/v2/accounts/{accountId}/envelopes/{envelopeId}/recipients

With the following request body:

{
    "signers": [{
        "name": "Bart Simpson",
        "email": "bart@email.com",
        "recipientId": "1"
    }]
}

Recipient Authentication

Recipient authentication is determined by the envelope sender, who can configure single or multi-factor auth flows on a per recipient basis. For instance, an envelope might have two recipients where the first recipient uses email based authentication to access the envelope however the second recipient must pass a two-factor auth flow using email and SMS before they can sign.

Recipient Types

There are currently seven (7) different types of recipients you can use in your DocuSign transactions:

  1. Agents: This recipient can add name and email information for recipients that appear after them in routing order. For instance, if you have an Agent recipient in routing order 1, and two recipients in routing order = 2, the Agent will be able to edit the recipient information of those two subsequent recipients.
  2. Carbon Copies: Used when the recipient should get a copy of the envelope, but the recipient does not need to sign, initial, date or add any information to the documents. This type of recipient can be placed in any order in the recipient list. The recipient receives a copy of the envelope when the envelope reaches the recipient's routing order and when the envelope is completed. CC recipients are the only type that do not take any actions on the envelope.
  3. Certified Deliveries: Use this type if the recipient must receive the completed documents for the envelope to be completed, but the recipient does not need to sign, initial, date or add information to any of the documents. This is analogous to Certified mail delivery through the U.S. post office and is used to confirm that your recipients have received the envelope.
  4. Editors: This recipient has the same management and access rights for the envelope as the sender and can make changes to the envelope as if they were using the Advanced Correct feature. This recipient can add name and email information, add or change the routing order and set authentication options for the remaining recipients. Additionally, this recipient can edit signature/initial tabs and data fields for the remaining recipients. The recipient must have a DocuSign account to be an editor.
  5. In Person Signers: Use this when the signer is in the same physical location as the DocuSign user who is requesting a signature. During this process the sending user, known as the signing host, physically hands the device to the signer where they then can authenticate, review and sign the documents, then physically hand the device back to the signing host.
  6. Intermediaries: This recipient can, but is not required to, add name and email information for recipients at the same or subsequent level in the routing order (until subsequent Agents, Editors or Intermediaries recipient types are added).
  7. Signers: Use this recipient type if your recipient must sign, initial, date or add data to form fields on the documents in the envelope. Note that signers do not need a DocuSign account.

Recipient Statuses

There are various statuses that Recipients can have as their envelopes progress through to completion. These are not to be confused with Envelope Statuses – which are similar but mean something different! A typical recipient status flow, for instance, might go from created->sent ->delivered->signed. Here are the possible recipient statuses along with their descriptions.

created – The recipient is in a draft state. This is only associated with draft envelopes (envelopes with a Created status).

sent – The recipient has been sent an email notification that it is their turn to sign an envelope.

delivered - The recipient has viewed the document(s) in an envelope through the DocuSign signing web site. This is not an email delivery of the documents in an envelope.

signed - The recipient has completed (signed) all required tags in an envelope. This is a temporary state during processing, after which the recipient is automatically moved to Completed.

declined - The recipient declined to sign the document(s) in the envelope.

completed - The recipient has completed their actions (signing or other required actions if not a signer) for an envelope.

faxpending - The recipient has finished signing and the system is waiting a fax attachment by the recipient before completing their signing step.

autoresponded - The recipient's email system auto-responded (bounced-back) to the email from DocuSign. This status is used in the web console to inform senders about the bounced-back email. This is only used if "Send-on-behalf-of" is turned off for the account.

Note that recipient statuses are different than envelope statuses. For instance, if you have an envelope that has two signer recipients and currently one of the recipients have signed but the other has not, then the envelope status would be Processing, the first recipient status would be Completed, and the other recipient might be Sent. Possible envelope status values are: Voided, Created, Deleted, Sent, Delivered, Signed, Completed, Declined, TimedOut and Processing.

For more information on recipient and envelope statuses please refer to the REST API Guide.

Corrections

DocuSign gives you the ability to correct/modify recipient information for envelopes that are in the draft state as well as for in-process envelopes. The REST API guide has several pages that discuss this functionality, and the SOAP API guide has some additional pages if you are using that protocol. Here are some useful pages from the REST guide regarding recipient corrections, modifications, and deletions:

Or feel free to search the REST API Guide.

Sample Request with Multiple Recipients

Below is a sample request body that includes two signing recipients and two carbon copy (CC) recipients. One signature tab is added for the first signer and a signature tab and initial tab is configured for the second signer.

Since the first recipient has a routingOrder of 1, and the second recipient has a routing order of 2, the second recipient will not receive the request until the first signer has finished signing. Both CC recipients have a routingOrder of 3, which means they simultaneously receive a copy of the completed envelope once the second signer completes their actions. Carbon copy recipients can only view envelopes and cannot take any actions on them, hence no tabs section defined for them.

{
    "emailSubject": "Email Subject",
    "status": "sent",
    "documents": [
        {
            "documentId": "1",
            "name": "test.pdf"
        }
    ],
    "recipients": {
        "signers": [
            {
                "email": "test_1@email.com",
                "name": "Name 1",
                "recipientId": "1",
                "routingOrder": "1",
                "tabs": {
                    "signHereTabs": [
                        {
                            "xPosition": "100",
                            "yPosition": "100",
                            "documentId": "1",
                            "pageNumber": "1"
                        }
                    ]
                }
            },
            {
                "email": "test_2@email.com",
                "name": "Name 2",
                "recipientId": "2",
                "routingOrder": "2",
                "tabs": {
                    "initialHereTabs": [
                        {
                            "xPosition": "100",
                            "yPosition": "200",
                            "documentId": "1",
                            "pageNumber": "1"
                        }
                    ],
                    "signHereTabs": [
                        {
                            "xPosition": "200",
                            "yPosition": "200",
                            "documentId": "1",
                            "pageNumber": "1"
                        }
                    ]
                }
            }
        ],
        "carbonCopies": [
            {
                "email": "test_3@email.com",
                "name": "Name 3",
                "recipientId": "3",
                "routingOrder": "3"
            },
            {
                "email": "test_4@email.com",
                "name": "Name 4",
                "recipientId": "4",
                "routingOrder": "3"
            }
        ]
    }
}

As always you can find more information in the online REST API Guide.