Overview
This tutorial will guide you through the complete process of creating an eSignature envelope using the Nitro Sign Public API, a common task that most systems integrating with Nitro will require. It will cover:- Envelope creation
- Adding Documents
- Adding Participants
- Adding Fields
- Sending the Envelope
- Monitoring Status
Prerequisites
Authentication
You will need a access token to authenticate your requests to the Nitro API. Check the Getting Started guide first to get the client_id and client_secret to be able to generate an access token.Documents to be signed.
To create an envelope successfully, you will upload documents to be signed. You can use the example PDF below for testing purposes:
1. Envelope Creation
An envelope is the container for a series of digital resources that make up what a user experiences as the eSignature document signing process. These resources are document files, participants, fields, and configurations that you can set up via this API, and they are all part of an envelope.Currently, only the Sign API supports envelopes with multiple documents. The Nitro Sign UI supports only single documents for signature, so you will not see the envelopes you create in the UI. Envelopes will be launched in the Nitro Sign UI soon.
1.1 Create the Envelope
Creating an envelope, your container, is the first step to creating an eSignature flow. We do this with a POST request to the/sign/envelopes
route in the API. You need to specify the following body parameters by replacing them in the curl below and include your access token:
name
: A string that specifies the name of the envelope to be created.notification
: An object that defines the notification email sent to participants.subject
: The subject line of the notification email.body
: The body content of the notification email.
mode
: Defines the signing order. Accepted values are:sequential
: Participants receive notifications one at a time, in the order they were added. Each new notification is triggered once the previous participant has completed their signing.parallel
: All participants are notified at the same time and can sign the document independently, without waiting for others.
1.1.2 Notification variables
You can personalize notification emails that go tosigner
participants by referencing dynamic variables in the subject or body. Keep in mind that cc
participants will get the default system notification.
Available variables:
envelope_name
: The name of the envelope being signed.
sender_name_or_email
: The sender’s name, or their email address if the name is not available.
Syntax:
To reference the variables. wrap them with $()
in your message. Example: $(envelope_name)
You can insert breaks using \n
Request:
ID
: The unique id of your envelope in the Nitro system.createdAt
: A UTC timestamp of when the envelope was created.lastModifiedAt
: A UTC timestamp of when the envelope was last modified.name
: The name you provided.status
: The status of your envelope. On creation it will be in “drafted” status. The status will change when you publish the envelope and it’s signed by participants.mode
: The mode to describe the signing order.notification
: The notification that participants will receive.
1.2 Save the Envelope ID
To keep interacting with the envelope you just created, you will need to reference the unique id for that envelope in following requests. Store the returned envelope ID (for example2fb5e56c-887d-4474-a370-5822f87eb822
) for the next operations.
2. Adding Documents
After creating an envelope, you need to upload documents for the end users to eventually sign. The Nitro Sign API supports PDF files only.When uploading a document, the following limits apply:
- Maximum documents per envelope: 15
- Maximum size per envelope: 300 Mb
- Maximum pages per document: 250
- Maximum size per document: 20Mb
2.1 Upload Document
Upload the file by doing a POST request to the/sign/envelopes/<envelopeID>/documents
route, where envelopeID
is the reference to the ID obtained on envelope creation above. You have to specify the following body parameters:
metadata
: A JSON object with the metadata fields for the file.name
: Your document’s name. The internal filename will be automatically generated by Nitro.
payload
: The binary of your document file.nitroDocumentID
: As an alternative to uploading a file in the request payload, you can reference an existing Nitro Document by its nitroDocumentID. For clarity, this tutorial only shows the example of uploading a document directly in the payload.
ID
: A unique identifier for the document.name
: Name of the file provided by the user.createdAt
: UTC timestamp indicating when the document was created.status
: Current status of the document. Defaults topending
and it’ will change touploaded
when the system ingested the document.
2.2 Add Additional Documents (Optional)
An envelope can contain multiple documents. Repeat the upload process for each document needed in the envelope.3. Adding Participants
Envelopes can be signed by multiple participants who review and sign the uploaded documents.When creating participants, the following limits apply:
- Maximum participants per envelope: 200
3.1 Add Primary Signer
To create a participant for your envelope, you will make a POST request to the/sign/envelopes/<envelopeID>/participants
endpoint, where envelopeID
is the reference to the ID obtained on the envelope creation above. You have to specify the following parameters:
email
: The participant’s email. Here is where the notifications will be sent when the envelope is published.role
: Enum that defines the participant’s role in the envelope. Accepted values:signer
: The participant must review and sign the documents in the envelope.cc
: The participant only receives notifications about the envelope but is not required to sign.
authentication
: (Optional) Enum that defines the authentication method that participants will be required upon signing the envelope. Accepted values:accessCode
: A shared secret between the participant and the sender of the envelope.sms
: The phone number of the participant.
ID
: The unique id for that participant in the nitro system.email
: The emailauthentication
: The authentication method
3.2 Add Additional Participants
Envelopes can have multiple participants. Repeat the process above to add participants. If the envelope mode is set tosequential
, the signing order will follow the order in which participants are added.
4. Adding Fields
Fields are the different pieces of information a participant fills in a document.4.1 Add Signature Field
To add fields to a document, send a POST request to theenvelopes/{envelopeID}/documents/{documentID}/fields
endpoint.
In the request path, include:
envelopeID
: Identifies the envelope containing the documentdocumentID
: Identifies the document where the field will be created.
The document in the envelope that you’re referring to must have the status “uploaded” before the field is added.
participantID
: The participant to which this field will be associated to.type
: Enum that specifies which type of information an eSignature participant is expected to fill in. Available options:signature
,name
,checkbox
,date
,initials
,company
,title
,custom
.label
: A descriptive label for custom type fields.page
: The page index that determines where in the document the field will appear. Page numbering starts at index 1, which corresponds to Page 1.boundingBox
: An array that specifies the position and size of the field on the page. It is defined by the coordinates of the top-left corner (x, y) and the rectangle’s dimensions: width (w) and height (h). All values are expressed in PDF points, in the format [x, y, w, h].required
: A boolean that indicates whether the participant must complete the field.format
: Default format for date fields.
ID
: A unique id for the field, associated to the document and participant.documentID
: The unique identifier of the Field’s parent Document.envelopeID
: The unique identifier of the Document’s parent Envelope.participantID
(optional): The participant to which this field will be associated to.type
: An enum that specifies which type of information an eSignature participant is expected to fill in: signature, name, initials, date, title, company, checkbox, custom.label
: A descriptive label for custom type fields.page
: The page of the document in which the field displays.boundingBox
: An array that specifies the position and size of the field on the page. It is defined by the coordinates of the top-left corner (x, y) and the rectangle’s dimensions: width (w) and height (h). All values are expressed in PDF points, in the format [x, y, w, h].required
: A boolean that indicates whether the participant must complete the field.
4.1.2 How to find the bounding box coordinates for a field in your document?
See the bounding box guide guide for details on positioning fields in a document.4.2 Add extra fields (Optional)
Add the extra fields you want the different participants to fill in.5. Sending the Envelope
Once you configure the envelope, you can send it to the participants for them to sign the documents in it.In the Sign API, participants can sign and access envelopes through their email notifications. At this time, envelopes are not visible in the Nitro Sign UI.
5.1 Send Envelope
To send an envelope, make a POST request to the/sign/envelopes/<envelopeID>:send-for-signing
endpoint. Provide the envelopeID as a path parameter. This request does not require a request body.
Sample Request:
ID
: The unique id of your envelope in the Nitro system.createdAt
: A UTC timestamp of when the envelope was created.lastModifiedAt
: A UTC timestamp of when the envelope was last modified.name
: The name you provided.status
: The status of the publishing process: “sent” if already published, “publishing” if still in process, or “scheduled” if it’s scheduled for publishing.mode
: The mode you provided for signing.notification
: The notification that participants will receive.
6. Monitoring Status
An eSignature process is asynchronous and can have different statuses depending on user behavior. You can request the envelope data to keep track of its status.6.1 Check Envelope Status
To get data and status for an envelope, make a GET request to the/sign/envelopes/<envelopeID>
route.
Request example: