Authentication

API Endpoint

https://public.pleasesign.eu/

Authentication headers

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.

Request Ids

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers against each logs on the request logs page. 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.

Email template example

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.

Email template example

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.

Email template example

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

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

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.
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.
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.eu/brand/:id

Example response


{
    "id": "35979549a18bddb87c84595c93168488",
    "name": "PleaseSign brand",
    "business": "PleaseSign Pty Ltd",
    "email": "example@pleasesign.eu",
    "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.eu/brands

Example response

[
    {
        "id": "35979549a18bddb87c84595c93168488",
        "name": "PleaseSign brand",
        "business": "PleaseSign Pty Ltd",
        "email": "example@pleasesign.eu",
        "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.eu/brand

Example request

{
    "name": "PleaseSign brand",
    "business": "PleaseSign Pty Ltd",
    "email": "example@pleasesign.eu",
    "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.eu",
    "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.eu/brand/:id

Example request

{
    "id": "35979549a18bddb87c84595c93168488",
    "name": "PleaseSign brand",
    "business": "PleaseSign Pty Ltd",
    "email": "example@pleasesign.eu",
    "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.eu",
    "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.eu/brand/:id

Example request

{
    "id": "35979549a18bddb87c84595c93168488",
    "logo": "encoded"
}

Example response

{
    "id": "35979549a18bddb87c84595c93168488",
    "name": "PleaseSign brand",
    "business": "PleaseSign Pty Ltd",
    "email": "example@pleasesign.eu",
    "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.eu/brand/:id

Example response

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.eu/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.eu",
    "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.eu",
        "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.eu/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.eu",
    "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.eu",
        "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.eu/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.eu",
      "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.eu",
        "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 (`total_count`) is over 20. Specify this parameter to show the documents for a next page. If you specify both next and prev, next will be used. 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.eu/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.eu/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.eu/document

Example request

{
  "title": "Example document",
  "message": "Lorem ipsum solar sit amet.",
  "file": "encoded",
  "recipients": [{
    "first_name": "John",
    "last_name": "Doe",
    "email": "example@pleasesign.eu",
    "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.eu",
  "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.

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.

routing integer

The order in which the recipient should receive the document.

nominee string

The email address of another recipient to act as the nominee.

silent boolean

Whether this recipient should be treated as silent.

redirect string

The URL the recipients web browser should be navigated to upon completing the document.

redirect_void string

The URL the recipients web browser should be navigated to after declining a document.

tabs* array

Array of tabs for the recipient.


kind* string	The tab type.
anchor** string	The anchor string for the tab, required when not using x and y coordinates.
x_offset int	The X axis offset value that will be applied to the found anchor position.
y_offset int	The Y axis offset value that will be applied to the found anchor position.
page** integer	The page number the tab should be positioned on. Required when not using an anchor string, page numbers start at index 1.
x** integer	The X coordinate of the tab, required when not using an anchor string.
y** integer	The Y coordinate of the tab, required when not using an anchor string.
height integer	The pixel height of the tab.
width integer	The pixel width of the tab.
text_height integer	The pixel font-size of the tab.
required boolean	Whether or not the tab is required.

Fields marked with an * are required.
Fields marked with an ** are conditionally required.

Void document

Endpoint

POST https://public.pleasesign.eu/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.eu/recipient/:id/signingurl

Example response

{
  "id": "52cc002fac06025cddad05de87f75b37",
  "url": "https://sign.pleasesign.eu?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.eu/recipient/:id/resend

Example request

{
  "id": "52cc002fac06025cddad05de87f75b37"
}

Example response

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.eu/recipient/:id/correct

Example request

{
  "id": "52cc002fac06025cddad05de87f75b37",
  "first_name": "John",
  "last_name": "Doe",
  "email": "example@pleasesign.eu",
  "mobile": "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.eu",
  "mobile": "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 it's 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.
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.

Template endpoint

List templates

Endpoint

GET https://public.pleasesign.eu/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 (`total_count`) is over 20. Specify this parameter to show the documents for a next page. If you specify both next and prev, next will be used. 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.eu/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.eu",
            "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.eu"
        }
    ]
}

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.eu/template/:id

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.eu",
            "sms_protect": "false",
            "mobile": "",
            "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": "Jane",
            "last_name": "Doe",
            "email": "example@pleasesign.eu",
            "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": "Mike",
            "last_name": "Doe",
            "email": "example@pleasesign.eu"
        }
    ]
}

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

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

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

recipients* array

Array of recipients that must sign the document before it is complete.

role** string

The configured role on the template. Not required for recipients outside of the template scope.

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. Required if sms_protect is set. If sms_protect is not set but mobile is, it will send an sms message with the link to sign the document.

sms_protect boolean

This will protect the document with an sms code that will be generated when the user agrees to the terms of the service.

routing integer

The order in which the recipient should receive the document.

nominee string

The email address of another recipient to act as the nominee.

silent boolean

Whether this recipient should be treated as silent.

redirect string

The URL the recipients web browser should be navigated to upon completing the document.

redirect_void string

The URL the recipients web browser should be navigated to after declining a document.

tabs* array

Array of tabs for the recipient.


kind* string	The tab type.
x_offset int	The X axis offset value that will be applied to the found anchor position.
y_offset int	The Y axis offset value that will be applied to the found anchor position.
page** integer	The page number the tab should be positioned on. Required when not using an anchor string, page numbers start at index 1.
x** integer	The X coordinate of the tab, required when not using an anchor string.
y** integer	The Y coordinate of the tab, required when not using an anchor string.
height integer	The pixel height of the tab.
width integer	The pixel width of the tab.
text_height integer	The pixel font-size of the tab.
required boolean	Whether or not the tab is required.

Fields marked with an * are required.
Fields marked with an ** are conditionally required.

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 gauranteed 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.eu",
  "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.eu",
  "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.eu",
  "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.eu",
  "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.