Introduction

The signing order feature helps you set up your document distribution list so that your document gets sent to one person at a time. The document will only be sent to the next person on the list once the previous signature (or any other field) is completed.

This recipe assumes:

You have authenticated via OAuth (see Authentication process) or have an API key (see API key authentication process)
You have created a template (see Save time with templates)

Set a signing order in the document creation request (templates & PDFs)

You can set or override a signing order in the document creation request, you need to add a signing_order parameter with a predefined number to each recipient.

1. Structure your Document details

Use the create document endpoint description to decide what metadata and details you need to pass to your document. The simplest possible document schema consists of a name, template ID, or PDF, and at least two recipients.

...
"recipients": [  
  {  
    "email": "[email protected]",
    "first_name": "Josh",
    "last_name": "Ron",
    "role": "user",
    "signing_order": 2
  },
  {  
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Snow",
    "role": "Signer",
    "signing_order": 1
  }
]
...

2. Create the Document

Using your authentication token or API key, and the content-type application/json
POST https://api.pandadoc.com/public/v1/documents
The response will contain the document ID as the element “id”

{
  "id":"XHjv8z3SfDuTseFSnhprML",
  "name":"My minimal document",
  "Status":"document.uploaded",
  "date_created":"2021-07-05T15:05:27.787341Z",
  "date_modified":"2021-07-05T15:05:27.787341Z",
  "Expiration_date":null,
  "Version":null,
  "uuid":"XHjv8z3SfDuTseFSnhprML"
}

In this case, a signing order of recipients will be defined based on data in the document creation request.

...
"roles": [
        {
            "id": "UByHvrFwEgjC8CgDLja9wZ",
            "name": "user",
            "signing_order": "1",
            "preassigned_person": null
        },
        {
            "id": "Z2NQj6BcWvu99YZLrPYxVC",
            "name": "Signer",
            "signing_order": "2",
            "preassigned_person": null
        }
]
...

...
"recipients": [
        {
            "id": "dHHZoALntuGmybk4R7QJvk",
            "first_name": "Josh",
            "last_name": "Ron",
            "email": "[email protected]",
            "recipient_type": "CC",
            "has_completed": false,
            "role": "",
            "signing_order": 2
        },
        {
            "id": "8dYMZoCYbnRPyNoYLGaqWo",
            "first_name": "John",
            "last_name": "Snow",
            "email": "[email protected]",
            "recipient_type": "CC",
            "has_completed": false,
            "role": "",
            "signing_order": 1
        }
]
...

3. Wait for the Document to enter a draft status

See Listening for changes in document status. If you are actively polling your document ID is “id” from the previous step.

4. Send the Document

Once you’ve determined that the document has entered “document.draft” status you can send it with a
POST https://api.pandadoc.com/public/v1/documents/{id}/send
Where {id} is the document ID from above. If you want you can include the optional parameters in your POST to set a subject line and body text

{
  "message": "Hello! This document was sent from the PandaDoc API.",
  "subject": "Please check this test API document from PandaDoc"
}

Do not set the “silent” parameter to “true” unless you don’t want an email to go out with the document link. For more information about why you might want to send silently see “Create a document and share it in real time”

Set a signing order in the template

The best practice is to set up a signing order on your template (both editable and uploaded) so that all subsequent documents inherit this setting.

2850 — Set a signing order in the template