Authentication
API Endpoint
https://public.pleasesign.com.au/
Authentication headers (sample)
X-PLEASESIGN-KEY: PLSAPPd6117bb82a3329dc401c2605b20745ea
X-PLEASESIGN-SECRET: 88bc54853d5d429d17f71140e91c6412769e93a7
Authenticate your account by including your public and secret key in API requests. You can manage your API keys when logged in as the owner of an organisation on the developer settings page. Your API keys carry many privileges, including access to all documents you send with PleaseSign, so be sure to keep them secure! Do not share your secret key in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via HTTP Basic Auth. Provide your API keys as headers in each request to authenticate.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without the authentication headers will also fail.
Applications
Authentication sample; the application will work if it's approved and enabled.
GET https://private.pleasesign.com.au/oauth/authorize?client_id=eFFOytb1YXQ&code_challenge=xv38n6K5bfRftBcnJP5IFpIDzbrF0E2oTI1x2Ep575w&code_challenge_method=S256&redirect_uri=http%3A%2F%2Fmy.server%2Fauth%2Fcallback&response_type=code&scope=business&state=79560a1e48e74acc0049f94030628b40154e32cf98c77b4d
You can create an application to use your clients' PleaseSign resource on their behalf. It gives the application owner access to all resources specified in the endpoints below. Only authorised applications will be able to work with PleaseSign and access client resources.
This authentication scheme implements OAuth2. Please use the PKCE flow with an S256 code verifier method and state parameter to enhance security.
Scopes available:
- business: allows access to all endpoints.
After obtaining the token and the refresh token, you should use Bearer token authentication instead of the HTTP Basic Auth one.
The URL to obtain OAuth tokens for PleaseSign is: https://private.pleasesign.com.au/oauth/token.
Request Ids
Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.
Email templates
With the signing url endpoint and silent recipients, we provide you the tools necessary to control every aspect of how and when your recipients receive emails notifying them they have documents to sign.
For a more straight forward approach, you can customize the default email templates that PleaseSign provides through the business preferences dashboard. Refer to the image below on what fields are customisable and how they can be changed.
White labelling
Our branding feature allows you to personalise the logo and colour scheme of the signing interface. By default all organisations are set up with the PleaseSign brand, which will be used for all recipients when completing a document. To use your own brand you will need to supply a brand_id when sending a Create document request.
Colours
All colour fields require a valid hexidecimal colour code consisting of the hash symbol (#), followed by six characters. All colour fields are optional, so any fields that you do not choose to customise will be set to their default value.
The following table lists all of the customisable colour fields and their default values.
| Field | Default |
|---|---|
| bg_primary | #eeeeee |
| bg_secondary | #ffffff |
| bg_accent | #383838 |
| text_primary | #212121 |
| text_secondary | #ffffff |
| btn_bg_primary | #f49848 |
| btn_text_primary | #ffffff |
| btn_bg_secondary | #383838 |
| btn_text_secondary | #ffffff |
Signing interface
The following image can be used as a reference to understand which colour fields change which part of the signing interface. Buttons do not have a hover or a focus effect, and use a material waves effect on click.
Sender card
The sender card is an element shown on the default email template, and on the signing interface used to identify the sender of the document to the recipient. The fields shown in this card are inheritted automatically by the sender of the document, defaulting to the owner of the organisation when no sender is provided, or otherwise overriden by specifying a brand when sending a document.
Note: The avatar is currently not available as a field that can be customised at a brand level and instead is read from the sender of the document, defaulting to the owner of the organisation when no sender is provided. All users are created with the default PleaseSign avatar until otherwise set.
Resources
All date properties associated with a resource are returned in UTC unix time format.
Brand
A brand is a set of rules that determine how the signing interface should be styled, and which information should be made available to the recipients in the sender card.
Refer to the white labelling section for more information on brands.
| id string | Unique identifier for the brand. |
| name string | The name of the brand, intended as an identifier when viewing multiple brands. |
| business string | The business name, this will override the business name in the sender card. |
| email string | The email address, this will override the email address in the sender card. |
| logo string | The complete HTTPS url for the logo, this will be used in email templates and in the signing interface. |
| bg_primary string | Primary background colour. |
| bg_secondary string | Secondary background colour. |
| bg_accent string | Accent background colour. |
| text_primary string | Primary text colour, sits on the secondary background. |
| text_secondary string | Secondary text colour, sits on the accent background. |
| btn_bg_primary string | Primary button background colour, sits on the accent background. |
| btn_text_primary string | Primary button text colour, sits on the accent background. |
| btn_bg_secondary string | Secondary button background colour, sits on the accent background. |
| btn_text_secondary string | Secondary button text colour, sits on the accent background. |
Document
| id string | Unique identifier for the document, prepended with "PLSDOC". |
| title string | The title of the document, doubles as the subject of the email that is sent to te recipients. |
| message string | The message of the email that is sent to recipients. |
| status string | The current status of the document, possible values are building, sent, complete and void. |
| brand_id string | Unique identifier of the brand that was used when creating the document, if no brand was provided the organisation's default brand is used. |
| sender_id string | Unique identifier of the user that sent the document. If no sender_id is provided when creating the document, defaults to the owner of the organisation. |
| sender_name string | The full name of the user that sent the document, or the sender property that was provided when creating the document. |
| sender_email string | The email address of the user that sent the document, or the email address associated to the brand that was provided when creating the document. |
| sender_business string | Your organisation's business name, or the business name associated to the brand that was provided when creating the document. |
| created_date integer | Unix timestamp of when the document was created. |
| sent_date integer | Unix timestamp of when the document was sent. |
| complete_date integer | Unix timestamp of when the document was successfully signed and sealed. |
| void_date integer | Unix timestamp of when the document was declined by one of the recipients, or by action of the sender. |
| void_reason integer | The reason provided by one of the recipients or by the sender when opting to decline/void the document. |
| recipients array | Array of recipients. |
Lifecycle
The status property is intended for a quick reference on the state of a document at any given time. Each possible value is listed below, alongside an explanation on what each value represents and how it transitions to and from it's next and previous values.
| building | When a document is created the status is set to building. During the building phase the PDF file is normalised, encrypted and prepared for digital signing. When this operation is complete, an email will be dispatched to the appropriate recipients adhering to silent and routing properties and the document status will transition to sent. |
| sent | This status represents action pending by one or more recipients. From this status the document can transition to void by either being declined by one of the recipients, or by action of the sender. Once all recipients have signed the document the status will transition to complete. |
| complete | Represents a completed document that has been agreed to and signed by all recipients. |
| void | The document has been declined by one of the recipients of voided by the sender. Voided documents will generally be accompanied by a void_reason, though not enforced, users are encouraged to enter a reason when choosing to decline/void a document. |
Email reminders
Reminders can be configured for your recipients at an account level, you can specify a frequency in the number of days between email reminders and an attempt count which will be the maximum number of reminders sent before they stop.
For example: a document sent to a recipient with reminders configured with a frequency of 7 and an attempt count of 4 will have a reminder email sent 7 days after the initial email for a total of 4 weeks before stopping. Resulting in five total emails sent, including the first initial email that was not a reminder.
Reminder emails will not be sent to recipients that have signed the document.
Email reminders can be configured from your Business profile page.
Recipient
| id string | Unique identifier for the recipient. |
| first_name string | The first name of the recipient. |
| last_name string | The last name of the recipient. |
| email string | The email address of the recipient. |
| mobile string | The mobile number of the recipient. See Mobile numbers for more information. |
| sms_mfa string | The mobile number for multi-factor authentication. This recipient will be required a 6-digit code before signing. See Mobile numbers for more information. If both mobile and sms_mfa are specified, they need to match each other. |
| status string | The current status of the recipient, possible values are pending, sent, failed, complete and void. |
| silent boolean | Whether or not signing emails are automatically dispatched to the recipient when a document is created, or when routing order determines the recipient is next. |
| redirect string | A redirect url used to navigate the recipients web browser to after signing a document. |
| redirect_void string | A redirect url used to navigate the recipients web browser to after they choose to decline a document. |
| routing integer | Positive integer used to determine the order in which the recipient is to receive the document for signing. Will take into account silent property. |
| nominee_id string | The unique identifier for another recipient on the same document to be used as the nominee for in person signing. |
| created_date integer | Unix timestamp of when the recipient was created. |
| complete_date integer | Unix timestamp of when the recipient signed the document. |
| reminder_date integer | Unix timestamp of when the next email reminder is scheduled to be sent. See Email reminders for more information. |
| reminder_count integer | The number of reminders that the recipient has received. See Email reminders for more information. |
Ordered signing
To control the order in which recipients are to receive a document for digital signing, provide a routing property set as a positive integer. Recipients will only have emails dispatched when all recipients with a lesser routing value has signed the document and had their status set to complete.
In person signing
To use the in person signing feature, provide a nominee property set as the email address of another recipient. Once created, this property will be replaced with the id of the first matching recipient.
Silent recipients
To manage the distribution of signing urls from your own application, provide a silent property set to true for a recipient. Silent recipients will be ignored when signing emails would otherwise be scheduled for dispatch.
If you use this feature in conjunction with ordered signing, you will need to monitor webhooks to know when a signing url request can be made.
Redirect URLs
By providing a redirect property for a recipient, you have control over where the recipient's web browser is navigated to after they have signed a document. The same functionality can be applied with the redirect_void property, this will be used if the recipient chooses to decline a document.
Mobile numbers
We support the dispatch of sms messages to recipients in addition to signing emails as an alternative method for recipients to receive a document for digital signing.
At this time only mobile numbers within the Australian network are supported and therefore must begin with "61" and be exactly 11 digits in length.
SMS MFA (multi factor authentication) affects your SMS quota each time a user requests a 6-digit code.
Tab
Tabs identify positions on a document where recipient input is generally required. Tabs can be customised by accompanying attributes, such as the dimensions of the tab and whether or not input is required before the document can be completed.
| kind string | The tab type. |
| anchor string | The anchor string, see anchors for more information. |
| x integer | The X coordinate of the tab, assuming the origin 0,0 as the bottom left of the pdf at 72DPI. |
| y integer | The Y coordinate of the tab, assuming the origin 0,0 as the bottom left of the pdf at 72DPI. |
| page integer | The page number the tab should be positioned on, page numbers start at index 1. |
| height integer | The pixel height of the tab, only applicable when the tab kind is signature, input or check. If this is not provided the following defaults are given: signature: 30, input: 23, check: 8. |
| width integer | The pixel width of the tab, only applicable when the tab kind is input. If this is not provided the following default value is used: 100. Check tabs have their width set to the given height property due to a forced 1:1 aspect ratio and signatures automatically set due to a forced 1:2.5 aspect ratio. |
| text_height integer | The pixel font-size of the tab, only applicable when the tab kind is first_name, last_name, full_name, sign_date, sign_short_date or input. If this is not provided the default value is set to 11. |
| options array[option] | A set of options when declaring a dropdown tab. Its format: [{ "option": "First option" }, { "option": "Second option" }] |
| required boolean | Whether or not the recipient is required to enter a value into the input box before the document can be completed, only applicable when the tab kind is input. |
| locked boolean | Whether or not the recipient can change this tab value. Only applicable when the tab kind is input. |
Tab types
The following table lists the tab types that are available, and how recipients must action each tab in order to complete a document.
| Signature signature | Allows the recipient to sign the document by drawing their signature. |
| Initials initial | Allows the recipient to initial the document by drawing their initials. |
| Witness witness | Allows the signature of the recipient to be witnessed by another individual. |
| Signature datetime sign_date | Displays the date and time the recipient signed the document in format DD/MM/YYYY hh:mma. |
| Signature date sign_short_date | Displays the date the recipient signed the document in format DD/MM/YYYY. |
| Input box input | Allows the recipient to enter any type of text, can be enforced by the required property. |
| Checkbox check | Allows the recipient to tick a box if applicable, checkbox's are optional and not required to be ticked in order to complete a document. |
| Dropdowndropdown | Allows the recipient to choose text from a predefined set of options. |
| First name first_name | Displays the recipient's first name based on what was entered in the recipient information. |
| Last namelast_name | Displays the recipient's last name based on what was entered in the recipient information. |
| Full namefull_name | Displays the recipient's full name, joining the first name and last name with a space as entered in the recipient information. |
Coordinate system
The coordinate system used is a standard pixel-based reference to any given location on a pdf file at 72DPI. All coordinate values should assume the origin 0,0 as the bottom left of the document and should always specify the XY position of the bottom left corner of the tab.
When specifying the coordinates for an input type tab, specify the XY position of the tab as the top left, rather than the bottom left. This is because the top left corner will always remain static, even when the tab grows from user input.
Anchors
Tab anchors can be used as an alternative method to the coordinate system as a way to intelligently position tabs on a page. Commonly used for documents with dynamic content that may shift the position of tabs, anchors provides a simple way for you to offset the logic of positioning tabs to PleaseSign.
When using anchors, the x, y, and page properties do not need to be provided in the request as they will be determined for you.
When given an anchor, all pages of the document will be scanned and any text elements matching the anchor exactly will have a tab created at it's found location. If more than one match is found on the document, each match will have a tab created at it's location.
Anchors are case-insensitive, meaning anchor foobar will match a FooBar text element found on the document. Text elements found are not partially-matched to anchors meaning anchor {foobar} will not match a {{foobar}} text element.
Anchors that are found too close to the edge of a document, that would otherwise cause the tab to overflow, fail silently and do not get created. Anchors that cannot be found on the document fail silently and do not get created.
All tabs except input are positioned at the bottom left origin of the matched text element of the anchor, input tabs are positioned at the top-left origin of the matched text element.
User
Users within your organisation can be created to change the sender of a document to personalise emails that are sent to recipients by PleaseSign. Senders will also receive notification emails when a document has either been completed, or declined by one of the recipients. Documents voided by the sender will not trigger a notification email.
Each user created will need to verify their email address before their id can be used as the sender of a document.
| id string | Unique identifier for the user. |
| first_name string | The first name of the user. |
| last_name string | The last name of the user. |
| email string | The email address of the user. |
| active boolean | Whether or not the user is active. |
Brand endpoint
Get brand
Endpoint
GET https://public.pleasesign.com.au/brand/:id
Example response
{
"id": "35979549a18bddb87c84595c93168488",
"name": "PleaseSign brand",
"business": "PleaseSign Pty Ltd",
"email": "example@pleasesign.com.au",
"logo": "https://ps-branding.s3.amazonaws.com/127b6227-e1c0-434c-8fc8-bf6f5cd4d514.png",
"bg_primary": "#eeeeee",
"bg_secondary": "#ffffff",
"bg_accent": "#383838",
"text_primary": "#212121",
"text_secondary": "#ffffff",
"btn_bg_primary": "#f49848",
"btn_text_primary": "#ffffff",
"btn_bg_secondary": "#383838",
"btn_text_secondary": "#ffffff"
}
This endpoint retrieves the information for a single brand. You need to supply the unique brand identifier that was returned upon creating a brand.
List brands
Endpoint
GET https://public.pleasesign.com.au/brands
Example response
[
{
"id": "35979549a18bddb87c84595c93168488",
"name": "PleaseSign brand",
"business": "PleaseSign Pty Ltd",
"email": "example@pleasesign.com.au",
"logo": "https://ps-branding.s3.amazonaws.com/127b6227-e1c0-434c-8fc8-bf6f5cd4d514.png",
"bg_primary": "#eeeeee",
"bg_secondary": "#ffffff",
"bg_accent": "#383838",
"text_primary": "#212121",
"text_secondary": "#ffffff",
"btn_bg_primary": "#f49848",
"btn_text_primary": "#ffffff",
"btn_bg_secondary": "#383838",
"btn_text_secondary": "#ffffff"
}
]
This endpoint retrieves the information for all brands created in your organisation, the default PleaseSign brand will not be included in thie response.
Create brand
Endpoint
POST https://public.pleasesign.com.au/brand
Example request
{
"name": "PleaseSign brand",
"business": "PleaseSign Pty Ltd",
"email": "example@pleasesign.com.au",
"logo": "encoded",
"bg_primary": "#eeeeee",
"bg_secondary": "#ffffff",
"bg_accent": "#383838",
"text_primary": "#212121",
"text_secondary": "#ffffff",
"btn_bg_primary": "#f49848",
"btn_text_primary": "#ffffff",
"btn_bg_secondary": "#383838",
"btn_text_secondary": "#ffffff"
}
Example response
{
"id": "35979549a18bddb87c84595c93168488",
"name": "PleaseSign brand",
"business": "PleaseSign Pty Ltd",
"email": "example@pleasesign.com.au",
"logo": "encoded",
"bg_primary": "#eeeeee",
"bg_secondary": "#ffffff",
"bg_accent": "#383838",
"text_primary": "#212121",
"text_secondary": "#ffffff",
"btn_bg_primary": "#f49848",
"btn_text_primary": "#ffffff",
"btn_bg_secondary": "#383838",
"btn_text_secondary": "#ffffff"
}
This endpoint creates a brand for your organisation. Colour fields must be provided as a valid hexidecimal colour code consisting of the hash symbol (#), following by six characters.
All colour fields are optional, so any fields that you do not provide in the request will be set to their default value. See White labelling for a list of the default values.
Request body
| name* string | The name of the brand, intended as an identifier when viewing multiple brands, this field is not exposed to recipients. |
| business* string | The business name, this will override the business name in the sender card. |
| email* string | The email address, this will override the email address in the sender card. |
| logo* string | The base64 encoded string of bytes containing the logo to be used. |
| bg_primary string | Primary background colour. |
| bg_secondary string | Secondary background colour. |
| bg_accent string | Accent background colour. |
| text_primary string | Primary text colour, sits on the secondary background. |
| text_secondary string | Secondary text colour, sits on the accent background. |
| btn_bg_primary string | Primary button background colour, sits on the accent background. |
| btn_text_primary string | Primary button text colour, sits on the accent background. |
| btn_bg_secondary string | Secondary button background colour, sits on the accent background. |
| btn_text_secondary string | Secondary button text colour, sits on the accent background. |
Update brand colours
Endpoint
PUT https://public.pleasesign.com.au/brand/:id
Example request
{
"id": "35979549a18bddb87c84595c93168488",
"name": "PleaseSign brand",
"business": "PleaseSign Pty Ltd",
"email": "example@pleasesign.com.au",
"bg_primary": "#eeeeee",
"bg_secondary": "#ffffff",
"bg_accent": "#383838",
"text_primary": "#212121",
"text_secondary": "#ffffff",
"btn_bg_primary": "#f49848",
"btn_text_primary": "#ffffff",
"btn_bg_secondary": "#383838",
"btn_text_secondary": "#ffffff"
}
Example response
{
"id": "35979549a18bddb87c84595c93168488",
"name": "PleaseSign brand",
"business": "PleaseSign Pty Ltd",
"email": "example@pleasesign.com.au",
"logo": "encoded",
"bg_primary": "#eeeeee",
"bg_secondary": "#ffffff",
"bg_accent": "#383838",
"text_primary": "#212121",
"text_secondary": "#ffffff",
"btn_bg_primary": "#f49848",
"btn_text_primary": "#ffffff",
"btn_bg_secondary": "#383838",
"btn_text_secondary": "#ffffff"
}
This endpoint updates the business information and colours for an existing brand. Colour fields must be provided as a valid hexidecimal colour code consisting of the hash symbol (#), following by six characters.
When updating a brand's colours, you must provide all colour fields that you wish to stay modified on the brand. Any colour fields that you do not provide in the request body will revert back to their default value.
Request body
| id* string | Unique identifier for the brand. |
| name* string | The name of the brand, intended as an identifier when viewing multiple brands, this field is not exposed to recipients. |
| business* string | The business name, this will override the business name in the sender card. |
| email* string | The email address, this will override the email address in the sender card. |
| bg_primary string | Primary background colour. |
| bg_secondary string | Secondary background colour. |
| bg_accent string | Accent background colour. |
| text_primary string | Primary text colour, sits on the secondary background. |
| text_secondary string | Secondary text colour, sits on the accent background. |
| btn_bg_primary string | Primary button background colour, sits on the accent background. |
| btn_text_primary string | Primary button text colour, sits on the accent background. |
| btn_bg_secondary string | Secondary button background colour, sits on the accent background. |
| btn_text_secondary string | Secondary button text colour, sits on the accent background. |
Update brand logo
Endpoint
PUT https://public.pleasesign.com.au/brand/:id
Example request
{
"id": "35979549a18bddb87c84595c93168488",
"logo": "encoded"
}
Example response
{
"id": "35979549a18bddb87c84595c93168488",
"name": "PleaseSign brand",
"business": "PleaseSign Pty Ltd",
"email": "example@pleasesign.com.au",
"logo": "https://ps-branding.s3.amazonaws.com/127b6227-e1c0-434c-8fc8-bf6f5cd4d514.png",
"bg_primary": "#eeeeee",
"bg_secondary": "#ffffff",
"bg_accent": "#383838",
"text_primary": "#212121",
"text_secondary": "#ffffff",
"btn_bg_primary": "#f49848",
"btn_text_primary": "#ffffff",
"btn_bg_secondary": "#383838",
"btn_text_secondary": "#ffffff"
}
This endpoint updates the business logo for an existing brand. The logo must be provided as a base64 encoded string of bytes containing the logo to be used.
Logos must not be larger than 2mb in size, and must be of mimetype image/*.
Request body
| id* string | Unique identifier for the brand. |
| logo* string | The base64 encoded string of bytes containing the logo to be used. |
Delete brand
Endpoint
DELETE https://public.pleasesign.com.au/brand/:id
Example response
200
Deletes a brand and immediately removes all existing associations to it.
Any users that have the brand set as their default through the PleaseSign portal will be set back to the default PleaseSign brand.
Any completed documents, as well as documents that are still in progress, will have their brand set back to the default PleaseSign brand.
Document endpoint
Get document
Endpoint
GET https://public.pleasesign.com.au/document/:id
Example response
{
"id": "PLSDOC19704278f8c51564ff0c707817",
"title": "Example document",
"message": "Lorem ipsum dolor sit amet.",
"status": "complete",
"brand_id": "60b4eb348cb410fbd2dbc410790fd99c",
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "example@pleasesign.com.au",
"sender_business": "PleaseSign Developers",
"created_date": 1531228693,
"sent_date": 1531228693,
"complete_date": 1531228693,
"void_date": 1531228693,
"void_reason": "Lorem ipsum dolor sit amet.",
"recipients": [{
"id": "52cc002fac06025cddad05de87f75b37",
"first_name": "Jane",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mobile": null,
"status": "complete",
"silent": false,
"redirect": "https://www.google.com.au/",
"redirect_void": "https://www.google.com.au/",
"routing": 1,
"nominee_id": null,
"created_date": 1531228693,
"complete_date": 1531228693,
"reminder_date": null,
"reminder_count": 0
}]
}
This endpoint retrieves the information for a document and all recipients. You need to supply the unique document identifier that was returned upon creating a document.
List documents
Endpoint
GET https://public.pleasesign.com.au/documents?ids=
Example response
[{
"id": "PLSDOC19704278f8c51564ff0c707817",
"title": "Example document",
"message": "Lorem ipsum dolor sit amet.",
"status": "complete",
"brand_id": "60b4eb348cb410fbd2dbc410790fd99c",
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "example@pleasesign.com.au",
"sender_business": "PleaseSign Developers",
"created_date": 1531228693,
"sent_date": 1531228693,
"complete_date": 1531228693,
"void_date": 1531228693,
"void_reason": "Lorem ipsum dolor sit amet.",
"recipients": [{
"id": "52cc002fac06025cddad05de87f75b37",
"first_name": "Jane",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mobile": null,
"status": "complete",
"silent": false,
"redirect": "https://www.google.com.au/",
"redirect_void": "https://www.google.com.au/",
"routing": 1,
"nominee": null,
"created_date": 1531228693,
"complete_date": 1531228693,
"reminder_date": null,
"reminder_count": 0
}]
}]
This endpoint retrieves the information for a list of documents and all recipients. You will need to supply the unique document identifiers returned upon creating a document as a comma-delimited list as a querystring parameter.
List documents (v2)
Endpoint
GET https://public.pleasesign.com.au/documents
Additional headers
Please send the special header below to use this endpoint:
Accept-Version: v2
Example response
{
"data": [
{
"id": "PLSDOC19704278f8c51564ff0c707817",
"title": "Example document",
"message": "Lorem ipsum dolor sit amet.",
"status": "complete",
"brand_id": "60b4eb348cb410fbd2dbc410790fd99c",
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "example@pleasesign.com.au",
"sender_business": "PleaseSign Developers",
"created_date": 1531228693,
"sent_date": 1531228693,
"complete_date": 1531228693,
"void_date": 1531228693,
"void_reason": "Lorem ipsum dolor sit amet.",
"recipients": [{
"id": "52cc002fac06025cddad05de87f75b37",
"first_name": "Jane",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mobile": null,
"status": "complete",
"silent": false,
"redirect": "https://www.google.com.au/",
"redirect_void": "https://www.google.com.au/",
"routing": 1,
"nominee": null,
"created_date": 1531228693,
"complete_date": 1531228693,
"reminder_date": null,
"reminder_count": 0
}]
}
],
"total_count": 154,
"next": "cb87hb3d91==",
"prev": null
}
This endpoint retrieves the information for a list of documents and all recipients. You can select documents by a specific status and order them by a specific date.
Parameters
| next string |
This pointer will be returned within the response body when the total of documents this query returns ( If you specify one of these pointers, other pagination or criteria parameters will be disregarded: status, order, order_direction. |
| prev string | This pointer will be returned within the response body after the second page. Specify this to get the previous page (before the current page you requested). |
| order string | Specify the ordering by which documents will be returned. See Document order. |
| order_direction string |
Specify the direction of the ordering. These can be: desc: The newest documents meeting the criteria will be returned first. This is the default order direction.asc: The oldest documents meeting the criteria will be returned first. |
| status string | Filter the returned documents by a specific status. See Document statuses. |
Document statuses
When the document list endpoint is queried, results can be filtered by these statuses:
| complete | Completed documents. We will order these documents by date of completion (when all recipients signed and the document was finalised); |
| sent | Documents that were sent but not completed. |
| pending | Draft documents (documents that still were not sent). |
| void | Voided documents (documents that either the business voided or a recipient declined). |
Document order
When the document list endpoint is queried, results can be sorted by these fields:
| created | Order the documents by the date the documents were created. This is the default if you don't specify an order with which to sort the documents. |
| sent | Order the documents by the date the documents were sent (when the first document processing is done and the first recipient may sign it); |
| complete | Order the documents by the date the documents were finished (when all recipients signed and the document is finalised); |
| void | Order the documents by the date they were voided (when you voided a document or a recipient declined the document). |
Get original
Endpoint
GET https://public.pleasesign.com.au/document/:id/original
Example response
{
"id": "PLSDOC19704278f8c51564ff0c707817",
"url": "https://ps-master.s3.ap-southeast-2.amazonaws.com/1afbd2c2181d32ddcf4324f07509290f.pdf"
}
This endpoint returns a temporary link that can be used to download the original PDF file for a document before it was signed by any recipients. This link will be accessible for 24 hours, after which it will return a 403 status code.
The original copy of the document will not be security stamped with the unique document identifier.
Get master
Endpoint
GET https://public.pleasesign.com.au/document/:id/master
Example response
{
"id": "PLSDOC19704278f8c51564ff0c707817",
"url": "https://ps-master.s3.ap-southeast-2.amazonaws.com/1afbd2c2181d32ddcf4324f07509290f.pdf"
}
This endpoint returns a temporary link that can be used to download the master PDF file for a document. The link will be accessible for 24 hours, after which it will return a 403 status code.
The master document is the most up-to-date version for a document that may or may not contain any signatures or a sealed digital certificate.
You can determine the current state of the master copy by checking the status of the recipients and the document itself. The master copy will only be sealed with a digital certificate once the document status is complete.
Create document
Endpoint
POST https://public.pleasesign.com.au/document
Example request
{
"title": "Example document",
"message": "Lorem ipsum solar sit amet.",
"file": "encoded",
"recipients": [{
"first_name": "John",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"tabs": [{
"kind": "signature",
"page": 1,
"x": 100,
"y": 800
}]
}]
}
Example response
{
"id": "PLSDOC19704278f8c51564ff0c707817",
"title": "Example document",
"message": "Lorem ipsum solar sit amet.",
"status": "building",
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "example@pleasesign.com.au",
"sender_business": "PleaseSign Developers",
"created_date": 1531228693,
"sent_date": 1531228693,
"complete_date": null,
"void_date": null,
"void_reason": null,
}
This endpoint creates a document for digital signing. You will need to provide the base64 encoded bytes of a pdf file, at least one recipient and at least one tab for each recipient.
Request body
Before reading the request body for this endpoint, we encourage you to have a good understanding of the Recipient and Tab resources to better understand some of the properties and how they may affect the workflow of a document.
| title* string | The title of your document, this is used as the subject line of emails sent to recipients. | ||||||||||||||||||||||||||||||||||||||||||||||||
| message string | A short paragraph intended as the introductory message to recipients when opening a document for digital signing. | ||||||||||||||||||||||||||||||||||||||||||||||||
| file* string | The base64 encoded string of bytes containing the PDF file to be used. | ||||||||||||||||||||||||||||||||||||||||||||||||
| brand_id string | Unique identifier of the brand to be used for the signing interface when recipients complete the document. | ||||||||||||||||||||||||||||||||||||||||||||||||
| sender_id string | Unique identifier of the user that is sending the document. If this is not provided defaults to the owner of the organisation. | ||||||||||||||||||||||||||||||||||||||||||||||||
| sender string | Name override of the user that is sending the document. If this field is provided, the name of the user associated to the sender_id will be masked. This is useful when your senders do not require accounts. | ||||||||||||||||||||||||||||||||||||||||||||||||
| folder_id string | Unique identifier of the folder that the document should created in. This will allow the document to be accessible to other users within the same access group that the folder belongs to. | ||||||||||||||||||||||||||||||||||||||||||||||||
| brand_id string | Unique identifier of the brand that should be used to style the signing application for all recipients associated with the document. The logo of the brand will also be used in the email sent to recipients. | ||||||||||||||||||||||||||||||||||||||||||||||||
| recipients* array | Array of recipients that must sign the document before it is complete.
|
Fields marked with an * are required.
Fields marked with an ** are conditionally required.
Void document
Endpoint
POST https://public.pleasesign.com.au/document/:id/void
Example request
{
"id": "PLSDOC19704278f8c51564ff0c707817",
"void_reason": "Lorem ipsum solar sit amet."
}
Voids a document rendering it incompletable by any recipients. This action can only be done when a documents status is sent. When a recipient opens a document that has been voided, a user friendly error message will appear notifying them that the document can no longer be viewed or completed.
When a document is voided by this endpoint, a notification email will not be dispatched to the sender as it is implied that the sender is the one who called the action.
Request body
| id string | Unique identifier for the document. |
| void_reason string | The reason for voiding the document. |
Recipient endpoint
Get signing url
Endpoint
GET https://public.pleasesign.com.au/recipient/:id/signingurl
Example response
{
"id": "52cc002fac06025cddad05de87f75b37",
"url": "https://sign.pleasesign.com.au?e=84364f3c73e8&p=c71ea459c014"
}
This endpoint can be used to generate a signing url for a recipient, it is with this url that a session can be created in the context of the recipient which will then allow the completion of a document. A signing url can only be generated when the status of the document is sent, and when the status of the recipient is either pending or sent.
Note: If you use this endpoint when the status of the recipient is pending (meaning a signing order has been applied to the document and it is not yet time for this recipient to sign) you will be required to delay the distribution of this url until the status has been changed to sent, in order to avoid an error message from being shown to the recipient when attempting to open the document.
It is imperative that with the use of this endpoint, you record an auditable log of how and when the returned signing url is distributed to the recipient by any verifiable means.
Resend email
Endpoint
POST https://public.pleasesign.com.au/recipient/:id/resend
Example request
{
"id": "52cc002fac06025cddad05de87f75b37"
}
Example response
200
Resends a signing email to the recipient, this endpoint can only be used when the status of the document is sent and the status of the recipient is either sent or failed. If the recipient has been created as silent, en error will be raised.
To prevent spamming, this endpoint can only be used once every 30 minutes per recipient. If a request is made within 30 minutes of a previous one, an error will be raised.
Signing urls that are automatically generated and embedded in signing emails do not expire, which means if more than one email is sent to a recipient any one of them can be used to open and complete the document.
Request body
| id string | Unique identifier for the recipient. |
Correct recipient
Endpoint
POST https://public.pleasesign.com.au/recipient/:id/correct
Example request
{
"id": "52cc002fac06025cddad05de87f75b37",
"first_name": "John",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mobile": "61437111222",
"sms_mfa": "61437111222",
"redirect": "https://www.google.com.au/",
"redirect_void": "https://www.google.com.au/"
}
Example response
{
"id": "52cc002fac06025cddad05de87f75b37",
"first_name": "Jane",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mobile": "61437111222",
"sms_mfa": "61437111222",
"status": "sent",
"silent": false,
"redirect": "https://www.google.com.au/",
"redirect_void": "https://www.google.com.au/",
"routing": 1,
"nominee": null,
"created_date": 1531228693,
"complete_date": null,
"reminder_date": null,
"reminder_count": 0
}
This endpoint is intended to be used when the information for a recipient that has not yet signed the document needs to be updated. A recipient's information can only be changed when the status is either pending, sent or failed.
When a recipient is corrected, a new recipient with the information provided is created in its place. The old recipient is immediately removed from the document and will no longer be able to access the document through any of the emails or SMS messages previously dispatched.
The new recipient created will automatically inherit the tabs that were initially created against the old recipient.
Request body
Before reading the request body for this endpoint, we encourage you to have a good understanding of the Recipient resource to better understand some of the properties and how they may affect the workflow of a document.
| id string | Unique identifier for the recipient being corrected. |
| first_name* string | The corrected first name of the recipient. |
| last_name*string | The corrected last name of the recipient. |
| email* string | The corrected email address of the recipient. |
| mobile string | The corrected mobile number of the recipient. |
| sms_mfa string | The mobile number for multi-factor authentication. This recipient will be required a 6-digit code before signing. See Mobile numbers for more information. If both mobile and sms_mfa are specified, they need to match each other. |
| redirect string | The URL the recipients web browser should ne navigated to upon completing the document. |
| redirect_void string | The URL the recipients web browser should ne navigated to after declining a document. |
Mobile number for signing and multi factor authentication
If you use both mobile number for signing and multi factor authentication, please specify the same mobile number for both fields.
Template endpoint
List templates
Endpoint
GET https://public.pleasesign.com.au/templates
Example response
{
"total_count": 21,
"data": [
{
"id": "0506ee8f5b53fa76f0c4e89591e66a85",
"title": "Example template document",
"name": "Template Document",
"created_date": 1622111456
}
],
"next": "cb87hb3d91==",
"prev": null
}
This endpoint retrieves the information for a list of templates. You can select templates by brand or folder and order them by a specific date or name.
Parameters
| next string |
This pointer will be returned within the response body when the total of templates this query returns ( If you specify one of these pointers, other pagination or criteria parameters will be disregarded: status, order, order_direction. |
| prev string | This pointer will be returned within the response body after the second page. Specify this to get the previous page (before the current page you requested). |
| order string | Specify the ordering by which templates will be returned. See Template order. |
| order_direction string |
Specify the direction of the ordering. These can be: desc: The newest documents meeting the criteria will be returned first. This is the default order direction.asc: The oldest documents meeting the criteria will be returned first. |
| folder_id string | The id of the folder that will be used to filter the template list |
| brand_id string | The id of the brand that will be used to filter the template list |
Template order
When the template list endpoint is queried, results can be sorted by these fields:
| created | Order the templates by the date the templates were created. This is the default if you don't specify an order with which to sort the documents. |
| name | Order the templates by the name the template. |
Get Template
Endpoint
GET https://public.pleasesign.com.au/template/:id
Example response
{
"title": "An example template",
"name": "A document from a template",
"message": "Please sign the attached document(s).",
"active": true,
"template_folder_id": "330aea8eadf88ee1e9ab509367faefa1",
"template_folder_name": "Template Folder 1",
"brand_id": null,
"brand_name": null,
"pages": [
{
"page": 1,
"width": "594.0",
"height": "841.0"
},
{
"page": 2,
"width": "445.0",
"height": "630.0"
}
],
"recipients": [
{
"role": "Developer",
"order": null,
"first_name": "John",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"tabs": [
{
"page": 1,
"kind": "signature",
"x": 83,
"y": 692,
"width": "74.0",
"height": "30.0"
},
{
"page": 2,
"kind": "witness",
"x": 200,
"y": 223,
"width": "56.0",
"height": "22.0"
}
]
},
{
"role": "Tester",
"order": null,
"first_name": null,
"last_name": null,
"email": null,
"tabs": [
{
"page": 1,
"kind": "signature",
"x": 108,
"y": 646,
"width": "74.0",
"height": "30.0"
},
{
"page": 1,
"kind": "witness",
"x": 213,
"y": 645,
"width": "74.0",
"height": "30.0"
}
]
}
],
"carbons": [
{
"role": "Debugger",
"first_name": "Jane",
"last_name": "Doe",
"email": "janedoe@pleasesign.com.au"
}
]
}
This endpoint retrieves the information for a template and its configuration. You need to supply the unique template identifier that was returned from the template listing.
Create Document from Template
Endpoint
POST https://public.pleasesign.com.au/template/:id/document
Example request
{
"title": "An example template",
"name": "A document from a template",
"message": "Please sign the attached document(s).",
"active": true,
"folder_id": "3c2576b347680931c04c8478bd9a2a4b",
"brand_id": null,
"sender_id": "1aef1e121c60f8189424f4c4661d41df",
"recipients": [
{
"role": "Developer",
"order": null,
"first_name": "John",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mfa": {
"mobile": "61499999999"
},
"mobile": "61499999999",
"tabs": [
{
"page": 1,
"kind": "signature",
"x": 83,
"y": 692,
"width": 74,
"height": 30
},
{
"page": 2,
"kind": "witness",
"x": 200,
"y": 223,
"width": 56,
"height": 22
}
]
},
{
"role": "Tester",
"order": null,
"first_name": "Jane",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"tabs": [
{
"page": 1,
"kind": "signature",
"x": 108,
"y": 646,
"width": 74,
"height": 30
},
{
"page": 1,
"kind": "witness",
"x": 213,
"y": 645,
"width": 74,
"height": 30
}
]
}
],
"carbons": [
{
"role": "Debugger",
"first_name": "Mike",
"last_name": "Doe",
"email": "example@pleasesign.com.au"
}
]
}
Example response
{
"id": "PLSDOC19704278f8c51564ff0c707817",
"created_date": 1531228693
}
This endpoint creates a new document based on an existing template. Template configured tabs and carbons are mandatory.
Request body
Before reading the request body for this endpoint, we encourage you to have a good understanding of the Recipient and Tab resources to better understand some of the properties and how they may affect the workflow of a document.
| title* string | The title of your document, this is used as the subject line of emails sent to recipients. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| message string | A short paragraph intended as the introductory message to recipients when opening a document for digital signing. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| brand_id string | Unique identifier of the brand to be used for the signing interface when recipients complete the document. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| sender_id string | Unique identifier of the user that is sending the document. If this is not provided defaults to the owner of the organisation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| sender string | Name override of the user that is sending the document. If this field is provided, the name of the user associated to the sender_id will be masked. This is useful when your senders do not require accounts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| folder_id string | Unique identifier of the folder that the document should created in. This will allow the document to be accessible to other users within the same access group that the folder belongs to. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| brand_id string | Unique identifier of the brand that should be used to style the signing application for all recipients associated with the document. The logo of the brand will also be used in the email sent to recipients. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| recipients* array | Array of recipients that must sign the document before it is complete.
|
Fields marked with an * are required.
Fields marked with an ** are conditionally required.
Folders endpoint
List folders
Endpoint
GET https://public.pleasesign.com.au/folders
Example response
{
"total_count": 1,
"data": [
{
"id": "28cc7e8cd4e7010079aa73580182db53",
"name": "Folder A",
"created_date": 1613096267
}
],
"next": null,
"prev": null
}
This endpoint retrieves the list of folders.
Parameters
| next string |
This pointer will be returned within the response body when the total of templates this query returns ( If you specify one of these pointers, other pagination or criteria parameters will be disregarded: status, order, order_direction. |
| prev string | This pointer will be returned within the response body after the second page. Specify this to get the previous page (before the current page you requested). |
| order string | Specify the ordering by which templates will be returned. See Folder order. |
| order_direction string |
Specify the direction of the ordering. These can be: desc: The newest documents meeting the criteria will be returned first. This is the default order direction.asc: The oldest documents meeting the criteria will be returned first. |
Folder order
When the folder list endpoint is queried, results can be sorted by these fields:
| created | Order the folders by date of creation. |
| name | Order the folders by name. This is the default if you don't specify an order with which to sort the documents. |
Enterprise endpoint
Update settings
Endpoint
PUT https://public.pleasesign.com.au/enterprise
Example request
{
"endpoint": "https://my.endpoint.com",
"webhook_token": "f81c4145079ac036c675f27988b18311"
}
Example response
204 OK
Example request (error code: 400 Bad Request)
{
"endpoint": "http://my.endpoint.com"
}
Example response
{
"message": "Invalid endpoint address."
}
This endpoint sets system options for a PleaseSign business.
Parameters
| endpoint string |
This sets the URL to which our system will connect to when sending you webhooks. We can only accept HTTPS addresses. To remove the URL, please send an empty string. |
| webhook_token string |
If you configure a webhook verification key (token), each webhook will have an X-PLEASESIGN-SIGNATURE header containing a digest calculated using the HMAC-SHA256 algorithm. The input for this calculation is the entire payload (body). To remove the token, please send an empty string. |
Users endpoint
List users
Endpoint
GET https://public.pleasesign.com.au/users
Example response
{
"total_count": 2,
"data": [
{
"id": "79f7075c7f11b33c799b90374a6f143a",
"first_name": "Test",
"last_name": "User",
"email": "test@example.net",
"active": true
},
{
"id": "411aefd1445e581d4cdbd58b54cf9b85",
"first_name": "Test",
"last_name": "User 2",
"email": "test2@example.net",
"active": false
}
],
"next": null,
"prev": null
}
Example request (filter by e-mail)
GET https://public.pleasesign.com.au/users?email=test@example.net
Example response
{
"total_count": 1,
"data": [
{
"id": "79f7075c7f11b33c799b90374a6f143a",
"first_name": "Test",
"last_name": "User",
"email": "test@example.net",
"active": true
}
],
"next": null,
"prev": null
}
This endpoint lists the business users.
Parameters
| email string |
If specified, the server will retrieve a user whose entry matches this e-mail address. |
| active boolean |
If specified, the parameter tells the server to filter the results and only return the active (true) or inactive (false) users. |
| next string |
This pointer will be returned within the response body when the total of documents this query returns ( |
| prev string | This pointer will be returned within the response body after the second page. Specify this to get the previous page (before the current page you requested). |
Connector
Use webhooks to be notified about events that happen on documents you send for digital signing.
PleaseSign can send webhook events that notify your application any time an event happens on a document. This is especially useful for events that are not triggered by a direct API request, such as when an email fails to send to a recipient or when a document has been completed.
As most of the internal operational procedures of PleaseSign are executed asynchronously, webhooks are the most viable way for your application to be notified of important events.
Here are some examples you might use webhooks for:
- Prepare to send your own signing emails once a document has been created.
- Correct a recipient's email address when a signing email fails to send.
- Start a new workflow when a recipient declines a document.
- Make a request to download the completed document once it has been signed by all parties.
All registered webhook URLs must use HTTPS, PleaseSign will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.
You can register webhook URLs that we will notify any time an event happens on a document you send on the Webhooks settings page.
Testing webhooks
Before deploying your application, test that your webhooks are configured properly. You can do so by sending dummy test events from the Webhooks settings page. To do this, first click the test webhooks button to reveal a modal, then add the endpoint to which test events should be sent. Next, click send webhook next to each event to test the different types that are made available. Understand that because these are dummy, test events, the data included with each request will not map to real documents or recipients.
Because webhooks are processed asynchronously, you will need to monitor the request logs advisably in another window by reloading the results until they appear.
If your webhook endpoint performs complex logic, or makes network calls, it's possible that the request may time out before PleaseSign sees its complete execution. For that reason, you might want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its logic asynchronously.
Validating webhooks
Set a verification key in the Webhooks settings page if you want to validate webhooks. After setting a key, our server will send webhooks including an X-PLEASESIGN-SIGNATURE header with the digest calculated against the entire webhook JSON payload body. You can verify the payload manually using OpenSSL.
The digest is calculated using the HMAC-SHA256 algorithm. If you need to validate the implementation, our dummy webhooks send the verification key together. Please note that we do not include newlines at the end of the payload.
$ echo -n '{"id":"a366b74dc750a2c58d8179aaf3170f42","event":"document.created","document_id":"PLSDOC6b776e1a931ef27ca87e56b6fb","created_date":1609974510}' | openssl dgst -sha256 -hmac verification_key
(stdin)= 2859aa9815835fd023acef531d0cad4156bdc95ddc2208e7ed67db9ac976779c
In this example, you should have received a webhook containing an X-PLEASESIGN-SIGNATURE header field with 2859aa9815835fd023acef531d0cad4156bdc95ddc2208e7ed67db9ac976779c value.
Duplicate webhooks
Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicate events by making your event processing idempotent. One way of doing this is by logging the id of each event that you process, and then not processing already-logged events.
Responding to a webhook
To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to PleaseSign that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure. PleaseSign will ignore any other information returned in the request headers or request body.
Webhook failures
If your endpoint does not successfully receive a webhook for any reason, we will continue trying to send the webhook every hour for up to three days. Webhooks cannot be manually retried after this time, though you can view a log of the failed webhooks from the Webhooks settings page and send the request yourself using a HTTP client such as Postman.
Webhook failures on test events you manually send will not be retried, response codes will be logged in your request logs so you can monitor how each request is performing.
Referencing dates
It is important when processing webhook events that you refer to the date properties included in the request body with each event, rather than the current timestamp of when you receive the event. As webhooks are processed asynchronously there may be a delay between the time the webhook event was created and when it was sent to your endpoint.
Connector events
document.created
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "document.created",
"document_id": "PLSDOC19704278f8c51564ff0c707817",
"processed_date": 1531228693
}
This webhook event is registered when a document has been completely processed after being created and has had its status transitioned to sent. If you are using silent recipients and sending your own signing emails, this is when you will be able to request a signing url for each recipient.
When you are not using silent recipients, this webhook event will generally be accompanied by a recipient.sent event for each recipient that has been sent a signing email. It is not guaranteed that this webhook event will be received before any of the recipient.sent events.
Request body
| id string | Unique event identifier. |
| event string | "document.created". |
| document_id string | The unique identifier for the document that was created. |
| processed_date integer | Unix timestamp of when the document was processed and had its status transition to sent. |
document.void
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "document.void",
"document_id": "PLSDOC19704278f8c51564ff0c707817",
"recipient_id": "52cc002fac06025cddad05de87f75b37",
"void_date": 1531228693,
"void_reason": "Lorem ipum solar sit amet."
}
This webhook event is registered when a recipient declines a document. The status of the document and the recipient will have already transitioned to void before this webhook is sent.
Recipients are not required to enter a reason when declining a document and therefore you will need to expect that the void_reason field may be null.
This webhook is not registered when a document is voided via direct API request, as the process of voiding a document is synchronous, it is expected you can execute the same workflow upon successful return of a void request.
Request body
| id string | Unique event identifier. |
| event string | "document.void". |
| document_id string | The unique identifier for the document that was voided. |
| recipient_id string | The unique identifier for the recipient that declined the document. |
| void_date integer | Unix timestamp of when the recipient declined the document. |
| void_reason string | The reason provided by the recipient when declining the document. This field is not required when declining a document and may be null. |
document.complete
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "document.complete",
"document_id": "PLSDOC19704278f8c51564ff0c707817",
"complete_date": 1531228693,
"original": "https://ps-master.s3.ap-southeast-2.amazonaws.com/1afbd2c2181d32ddcf4324f07509290f.pdf",
"signed": "https://ps-master.s3.ap-southeast-2.amazonaws.com/1afbd2c2181d32ddcf4324f07509290f.pdf",
"certificate": "https://ps-master.s3.ap-southeast-2.amazonaws.com/1afbd2c2181d32ddcf4324f07509290f.pdf"
}
This webhook event is registered when PleaseSign has successfully verified all aspects of the document and placed an encrypted digital certificate, sealing the final copy. The status of the document will have already transitioned to complete before this webhook is sent.
It is important to remember that the complete_date included in the request body may not match the complete_date of the last recipient that signed the document. A document is not considered complete until is has been certified and sealed with an encrypted digital certificate. Generally this process takes up to 5 seconds from the last recipient completing.
Included in the request body are links that can be used to download the original document, signed document and certificate of authenticity. These links are active for 72 hours after which they will return a 403. 72 hours is used as this is the maximum amount of time a webhook event can be retried until stopping.
It is important to remember when manually resending an expired webhook event for this event type, that the links will not be regenerated and will return a 403.
Request body
| id string | Unique event identifier. |
| event string | "document.complete". |
| document_id string | The unique identifier for the document that was completed. |
| complete_date string | The true unix timestamp of when the document was completed. |
| original string | A 72 hour link that can be used to download the original copy of the document before it was signed by any recipients. |
| signed string | A 72 hour link that can be used to download the signed and sealed copy of the document. |
| certificate string | A 72 hour link that can be used to download the certificate of authenticity. |
recipient.sent
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "recipient.sent",
"document_id": "PLSDOC19704278f8c51564ff0c707817",
"recipient_id": "52cc002fac06025cddad05de87f75b37",
"first_name": "John",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mobile": "61437111222",
"method": "email",
"sent_date": 1531228693
}
This webhook event is registered after a successful request has been made to dispatch either an email or sms message to a recipient. The status of the recipient will have already transitioned to sent, before this webhook is sent.
This webhook event does not necessarily mean that the email or sms message was successfully delivered to the recipient, only that the request to attempt the send operation was successful. If the send operation is later determined to have failed, a recipient.failed webhook event will soon follow.
The mailing service used by PleaseSign delivers webhooks notifying us on the status of each request made in batches, once an hour. It is because of this that we have determined the potential 59 minute delay on when an email was sent, to when we are notified that the operation was successful, to then notify you, is an unacceptable amount of time. Thus all webhook events are sent with the assumption that the operation will be successful.
Request body
| id string | Unique event identifier. |
| event string | "recipient.sent". |
| document_id string | The unique identifier for the document the recipient belongs to. |
| recipient_id string | The unique identifier for the recipient that had either an email or sms message sent to. |
| first_name string | The first name of the recipient. |
| last_name string | The last name of the recipient. |
| email string | The email address of the recipient. |
| mobile string | The mobile number of the recipient. |
| method string | The method that was used to send the document to the recipient, can be "email" or "sms". |
| sent_date integer | Unix timestamp of when the recipient had either an email or sms message sent to. |
recipient.failed
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "recipient.failed",
"document_id": "PLSDOC19704278f8c51564ff0c707817",
"recipient_id": "52cc002fac06025cddad05de87f75b37",
"first_name": "John",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mobile": "61437111222",
"diag": "smtp;550 5.1.1 RESOLVER.ADR.RecipNotFound; not found",
"message": "bad_mailbox",
"failed_date": 1531228693
}
This webhook event is registered when PleaseSign is notified of a failure when sending a signing email to a recipient. This webhook event can potentially be delayed by up to 59 minutes of when the send operation failed.
The diag and message included in the request body are taken directly from the receiving SMTP mail server and may not be easily deciphered by end users. It is important to remember that some SMTP mail servers may not respond with any reason for failure and thus these fields may be null.
The failed_date included in the request body is the true date that the email was sent when the receiving SMTP mail server responded with a failure.
Request body
| id string | Unique event identifier. |
| event string | "recipient.sent". |
| document_id string | The unique identifier for the document the recipient belongs to. |
| recipient_id string | The unique identifier for the recipient that had an email fail to send to. |
| first_name string | The first name of the recipient. |
| last_name string | The last name of the recipient. |
| email string | The email address of the recipient. |
| mobile string | The mobile number of the recipient. |
| diag string | The specific SMTP response code and bounce description, if any, received from the remote server. |
| message string | A short description of the bounce reason, such as bad_mailbox or invalid_domain. |
| failed_date integer | Unix timestamp of when the recipients email failed to send. |
recipient.opened
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "recipient.opened",
"document_id": "PLSDOC19704278f8c51564ff0c707817",
"recipient_id": "52cc002fac06025cddad05de87f75b37",
"first_name": "John",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mobile": "61437111222",
"method": "email",
"opened_date": 1531228693
}
This webhook event is registered when a recipient opens a document, either by method of "email", "sms", "user" or "api". The method property refers to how the recipient authenticated to the document, definition for each method are as follows:
- email - the recipient opened the document by means of an email that was sent by PleaseSign.
- sms - the recipient opened the document by means of an sms message that was sent by PleaseSign.
- user - the recipient opened the document while logged in to their verified PleaseSign account.
- api - the recipient opened the document using a signing url that was generated by api request. It is important to remember that for the this method of authenticating, your means of distributing the signing url are irrelevant when recording how the recipient received the document.
When a recipient is created, PleaseSign scans through the list of verified accounts to create an alternative entrypoint to the document by means of logging in to that account and accessing it via the dashboard. Until this method is used to access the document, you will have no way to know whether or not this method is available to a recipient. This is intentional by design to prevent mining.
Request body
| id string | Unique event identifier. |
| event string | "recipient.sent". |
| document_id string | The unique identifier for the document the recipient belongs to. |
| recipient_id string | The unique identifier for the recipient that opened the document. |
| first_name string | The first name of the recipient. |
| last_name string | The last name of the recipient. |
| email string | The email address of the recipient. |
| mobile string | The mobile number of the recipient. |
| method string | The method the recipient used to open the document, possible values are "email", "sms", "user" and "api". |
| opened_date integer | Unix timestamp of when the recipient opened the document. |
recipient.complete
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "recipient.complete",
"document_id": "PLSDOC19704278f8c51564ff0c707817",
"recipient_id": "52cc002fac06025cddad05de87f75b37",
"first_name": "John",
"last_name": "Doe",
"email": "example@pleasesign.com.au",
"mobile": "61437111222",
"method": "email",
"complete_date": 1531228693
}
This webhook event is registered when a recipient completes a document. The method property refers to how the recipient authenticated to the document in the session they used to complete the document.
It is important to remember that although you may have recieved a recipient.complete webhook event for every recipient on a document, the document is not considered complete until the document.complete webhook event is registered.
Request body
| id string | Unique event identifier. |
| event string | "recipient.sent". |
| document_id string | The unique identifier for the document the recipient belongs to. |
| recipient_id string | The unique identifier for the recipient that completed the document. |
| first_name string | The first name of the recipient. |
| last_name string | The last name of the recipient. |
| email string | The email address of the recipient. |
| mobile string | The mobile number of the recipient. |
| method string | The method the recipient used to open the document, before completing. |
| complete_date integer | Unix timestamp of when the recipient completed the document. |