Customizing Notification Programmatically for Nintex AssureSign

One of the most powerful parts of Nintex AssureSign is the fact that you can manage the entire signing process programmatically through our API. In this post I wanted to showcase how you can customize notifications when sending envelopes using the Nintex AssureSign API.

For this example we are going to be using the `submit/prepare` API endpoint to customize the envelope and notification that we wish to send. As with any interaction with the AssureSign API, the first step will be getting your authentication token. You can do this by creating an API user from within Nintex AssureSign (video link), and then using the API username and key to get your authentication token:

Submit/Prepare with custom message for default email designs Authenticate Request POST https: //account.assuresign.net/api/v3.7/authentication/apiUser Content-Type: application/json Accept: application/json { "request": { "apiUsername": "ApiUserName", "key": "ProvidedUniqueKeyHere", "contextUsername": "user@example.com", "sessionLengthInMinutes": 5 } } Authentication Response { "result": { "token": "asdf1234..." } }

Next, we’ll use the emailDesignSets endpoint to look at how a standard email notification payload should be formatted. This will help us structure our customized notification that we want to add to our example request:

Default Notification Request GET https: //www.assuresign.net/api/documentnow/v3.7/emailDesignSets/defaultEmailNotifications/{culture} Content-Type: application/json Accept: application/json Authorization: bearer <<Token from Authenticate Response here>> Default Notification Response { "result": { "defaultEmailNotifications": [ { "body": "string", "name": "string", "recipients": [ "user@example.com" ], "stage": "Envelope_Start", "step": 0, "subject": "string" } ] } }

Now that we know what a standard notification payload typically looks like, let’s look at how we can customize it for our submit/prepare request:

Modifications to include Custom Message

Modify the result from DefaultNotificationResponse to add/update the CustomMessage property to include whatever custom message is desired.

{ "result": { "defaultEmailNotifications": [ { "body": "string", "name": "string", "recipients": [ "user@example.com" ], "stage": "Envelope_Start", "step": 0, "subject": "string", "customMessage": "Hello world! This is my first customized message!” } ] } }

Finally, let’s put this all together inside of our example submit/prepare request where we want to include a customized email notification:

Submit Prepare Request POST https: //www.assuresign.net/api/documentnow/v3.7/submit/prepare Content-Type: application/json Accept: application/json Authorization: bearer <<Token from Authenticate Response here>> { "request": { "content": { "documents": [ { "fields": [ { "fieldType": "signature", "inputType": "signatory", "instructions": "Please sign by entering your full name.", "name": "Signature JotBlock", "position": { "x": 0.27, "y": 0.32 }, "required": true, "signer": "First Signer", "size": { "height": 0.05, "width": 0.7 } } ], "file": { "fileToUpload": { "data": "[File data must be converted to Base64]", "fileName": "Example.pdf" }, "extension": "pdf" }, "name": "document 1" } ], "emailNotifications": [ { "body": "string", "name": "string", "recipients": [ "user@example.com" ], "stage": "Envelope_Start", "step": 0, "subject": "string", "customMessage": "Hello world! This is my first customized message!” } ] "envelope": { "cultureType": "en-US", "expirationDate": "2021-08-07", "name": "Example Envelope" }, "signers": [ { "email": "example@asd.com", "label": "First Signer", "name": "Signer one" } ] } } } Submit Prepare Response { "result": { "preparedEnvelopeID": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "setupUrl": "https://www.assuresign.net/ui/simpleSetup/3fa85f64-5717-4562-b3fc-2c963f66afa6" } }

Finally, to send our envelope out for signature we need to user our Prepared Envelope ID with our submit endpoint:

Submit Request with Prepared ID POST https://www.assuresign.net/api/documentnow/v3.7/submit/{preparedEnvelopeID} Content-Type: application/json Accept: application/json Authorization: bearer <<Token from Authenticate Response here>>

While not needed for every use case, the ability to customize email notifications is a core piece of functionality when integrating Nintex AssureSign within your custom application if you are not planning to use templates and/or notifications that are controlled from within AssureSign itself.

Happy coding!