Recipients

 

There are 7 different types of recipients you can assign to your envelopes: Agents, Carbon Copies, Certified Deliveries, Editors, In Person Signers, Intermediaries, and Signers. Note that when you add tabs to your document(s) each tab is specific to a given recipient (as opposed to the document itself) and they are assigned using the recipientId property.

This means you cannot have a generic signature tab that everyone who receives the envelope is supposed to sign – instead you have a signature tab for Bob, a signature tab for Sally, a tab for Joe, etc. Or if using Templates you might have a signature tab for Role A, a signature tab for Role B, etc. Note that at least one recipient in a given envelope needs to be of type signer or inPersonSigner, and the carbonCopy recipient is the only type that does not take any actions on the envelope (they simply receive a copy) and therefore are not allowed to have any tabs defined for them.

Recipient Types

When adding recipients to envelopes through your API calls you need to specify the type of recipient along with any potential parameters. The exact parameters associated with a recipient depend on the recipient type. For instance, if we wanted to add 3 different types of recipients to a given envelope, one Signer, one In Person Signer, and one Certified Delivery, our (partial) request body might look like:

"recipients": {
        "signers": [
            { ... }
        ],
        "inPersonSigners": [
            { ... }
        ],
        "certifiedDeliveries": [
            { ... }
        ],
        ...
}

Here is more information on the seven different recipient types currently available:

  1. Agents: This recipient can add name and email information for recipients that appear after the recipient in routing order. For instance, if you have an Agent recipient in routing order 1, and two recipients in routing order = 2, then the Agent will be able to edit the recipient information of those two subsequent recipients.
  2. Carbon Copies: Use this action if the recipient should get a copy of the envelope, but the recipient does not need to sign, initial, date or add information to any of 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 order in the process flow and when the envelope is completed. CC recipients are special in that they do not take any actions on the envelope but instead just receive a copy of it.
  3. Certified Deliveries: Use this action 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 action if the signer is in the same physical location as a DocuSign user who will act as a Signing Host for the transaction. The recipient added is the Signing Host and new separate Signer Name field appears after Sign in person is selected.
  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 action if your recipient must sign, initial, date or add data to form fields on the documents in the envelope.

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 here.

Sample JSON Body

Below is a sample JSON request body that includes multiple recipient types as well as tabs for some of those recipients. When supplied in a signature request API call it configures two signing recipients and two Carbon Copy (CC) recipients. One signature tab is added for the first signer (i.e. test_1@email.com), while a signature tab and an initial tab is added for the second signer (test_2@email.com).

Since the first recipient has a routingOrder of 1, and the second recipient has a routing order of 2, the second recipient does not receive the request until the first signer has finished signing. Another thing to note is that both CC recipients have a routingOrder of 3, which means they simultaneously receive a copy of the completed envelope once the second recipient has completed their actions.

Carbon copy recipients can only view envelopes and cannot take any actions on them, which is why no tabs section is defined for those two. One last notable is the placement of the tabs - since they all have xPosition and yPosition properties set they all use absolute positioning (default unit of measurement is pixels). If we wanted to we could also use relative positioning (aka anchor tagging), please see the Tab Positioning section on the Stick-eTabs page for more info.

{
    "emailBlurb": "Sample Email Body",
    "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.