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. |
Identity resources
The identity verification feature allows your organisation to programmatically request that a person verify their identity against a government-issued document. An identity request captures who you want to verify, what document type to accept, and who is sending the request. Once sent, PleaseSign coordinates the end-to-end verification session with the recipient and notifies you of the outcome via webhooks.
Each identity request has exactly one associated identity session. The session is created when the request is sent and tracks the full lifecycle of the verification attempt — from the notification being dispatched to the recipient through to their outcome. The session is reused on resend: its status, URL, and expiry are updated in place rather than replaced.
All date properties in the public API are returned as UTC unix timestamps (integers).
Identity request
| id string | Unique identifier for the identity request, prepended with "PLSIDREQ". |
| status string | The current status of the identity request. See Identity request lifecycle. |
| doc_type string | The type of document accepted for verification. Possible values are document (any government-issued photo ID) and id_number (a national identification number). |
| first_name string | The first name of the person being verified. |
| last_name string | The last name of the person being verified. |
| email string | The email address of the person being verified. |
| mobile string | The mobile number of the person being verified, in E.164 format. Used to dispatch verification notifications via SMS. See Mobile numbers for identity. |
| country_code string | The ISO 3166-1 alpha-2 country code for the recipient. Determines which document types are accepted and validates the mobile number dial code prefix. |
| message string | An optional custom message included in the notification sent to the recipient. If not provided, defaults to: "As part of our compliance and security standards, we require a quick identity verification to confirm your identity. Please complete your verification using the secure link below." |
| active boolean | Whether the identity request is active. This is always true for requests created through the API. |
| brand_id string | Unique identifier of the brand applied to this request, if any. |
| sender_id string | Unique identifier of the user associated as the sender. Defaults to the owner of the organisation. |
| sender_name string | The display name shown to the recipient as the sender. Sourced from the sender field provided at creation time, or falls back to the linked user's name if no sender was provided. |
| sender_email string | The email address of the sender. When a brand is applied, this is sourced from the brand's email. |
| sender_business string | The business name of the sender's organisation. When a brand is applied, this is sourced from the brand's business name. |
| created_date integer | UTC unix timestamp of when the identity request was created. |
| sent_date integer | UTC unix timestamp of when the notification was first dispatched to the recipient. Set when the dispatch job processes, not at the time of the API call. |
| verified_date integer | UTC unix timestamp of when the recipient's identity was successfully verified. |
| canceled_date integer | UTC unix timestamp of when the identity request was canceled. |
| cancel_reason string | The reason provided when the identity request was canceled. May be null. |
| identity_sessions array | Array containing the single identity session for this request. |
Lifecycle
The status property reflects the current state of an identity request. Each value is described below along with which transitions lead to and from it.
| draft | The request has been saved but no notification has been sent to the recipient. From this state the request can be sent using the send endpoint, updated using the update endpoint, or permanently deleted using the delete endpoint. |
| sent | The request has been dispatched. The notification was sent to the recipient and the verification session is active. From this state the request can be canceled using the cancel endpoint, or the recipient can be re-notified using the resend endpoint. |
| failed | The recipient's verification attempt failed, for example due to an unsupported document, an expired document, or because they declined the disclosure agreement. The request can be canceled or the recipient re-notified from this state. |
| verified | The recipient has been successfully verified. This is a terminal status. |
| canceled | The request was canceled. All associated verification sessions are also canceled at the upstream provider. This is a terminal status. |
Note: The internal statuses sending and processing are both normalised to sent in public API responses. You will never observe these values from the public API.
Identity session
An identity session is created when an identity request is sent. It tracks the lifecycle of the verification attempt for the request and holds the identity report once verification is complete. Each identity request has exactly one session. When a resend is performed, the existing session is updated in place — its verification URL, expiry, and status are refreshed — rather than replaced.
| id string | Unique identifier for the identity session, prepended with "PLSIDS". |
| status string | The current status of the session. See Identity session lifecycle. |
| created_date integer | UTC unix timestamp of when the session was created. |
| sent_date integer | UTC unix timestamp of when the notification was most recently dispatched for this session. |
| opened_date integer | UTC unix timestamp of when the recipient agreed to the disclosure and opened the verification interface. |
| submitted_date integer | UTC unix timestamp of when the recipient submitted their documents for review. |
| verified_date integer | UTC unix timestamp of when the verification was confirmed as successful. |
| canceled_date integer | UTC unix timestamp of when this session was canceled. |
| redacted_date integer | UTC unix timestamp of when this session's data was redacted. |
| failure_code string | A machine-readable code describing why the session failed, when applicable. Common values include document_expired, document_type_not_supported, document_unverified_other, id_number_unverified_other, and under_supported_age. |
| failure_reason string | A human-readable description of the failure, sourced directly from the verification provider. May be null when no detail is available. |
| report object | The identity report containing verified data extracted from the recipient's document. Only present when status is verified. See Identity report. |
Lifecycle
| requires_input | The session has been created and the notification dispatched. The recipient has not yet opened the verification interface. |
| processing | The recipient has submitted their documents and the verification is being evaluated by the provider. |
| verified | The recipient has been successfully verified. The report field will be populated. |
| failed | The verification attempt failed. The failure_code and failure_reason fields provide details. This also occurs when the recipient declines the disclosure agreement. |
| expired | The session expired before the recipient completed verification. Use the resend endpoint to refresh the session and re-notify the recipient. |
| canceled | The session was canceled because the parent identity request was canceled. |
| redaction_processing | A redaction request has been submitted to the verification provider and is being processed. The actual removal of identity data is confirmed asynchronously. |
| redacted | The identity data for this session has been permanently removed. |
Identity report
The identity report is returned as the report property on a verified identity session. It contains the data extracted from the recipient's government-issued document during the verification process.
| id string | Unique identifier for the report. |
| status string | The report status, typically verified. |
| report_type string | The type of report generated, reflecting the doc_type of the parent request. |
| first_name string | The first name as it appears on the verified document. |
| last_name string | The last name as it appears on the verified document. |
| date_of_birth string | The date of birth from the verified document, in YYYY-MM-DD format. |
| document_type string | The specific document type used, for example driving_license or passport. |
| issuing_country string | The ISO 3166-1 alpha-2 country code of the country that issued the document. |
| issued_date string | The date the document was issued, in YYYY-MM-DD format. May be null. |
| expiration_date string | The expiry date of the document, in YYYY-MM-DD format. May be null. |
| verified_date integer | UTC unix timestamp of when the report was generated. |
Mobile numbers for identity
Identity requests require a mobile number to send verification notifications via SMS. Mobile numbers must be in E.164 format: a + sign followed by the country dial code and the subscriber number, with no spaces or dashes, totalling between 8 and 15 digits. The + prefix is optional — if omitted, the API will prepend it automatically. However, the number after the + must be a valid dial code and subscriber number.
The mobile number must also match the country_code provided with the request. For example, if country_code is AU, the mobile must begin with +61. If country_code is GB, the mobile must begin with +44.
Examples of valid mobile numbers:
| Country | country_code | Example |
|---|---|---|
| Australia | AU | +61491570006 |
| United States | US | +12025551234 |
| United Kingdom | GB | +447911123456 |
| Germany | DE | +4915123456789 |
| New Zealand | NZ | +6421234567 |
| France | FR | +33612345678 |
| Canada | CA | +16135550100 |
If the mobile number is not in valid E.164 format after normalisation, a 400 will be returned: mobile must be in E.164 format (e.g. +61491570006, +12025551234, +447911123456).
If the mobile number does not start with the expected dial code for the given country, a 400 will be returned: mobile does not match country_code 'AU'. Expected a number starting with +61.
Common errors
The following errors can be returned by multiple identity endpoints and are not repeated in the individual error tables below.
| 400 | Identity request {id} does not exist. |
| 400 | Identity session {id} does not exist. |
| 400 | No identity request quota remaining. |
| 400 | Brand {id} does not exist. |
| 401 | "Missing authorisation headers." — API key or secret header is absent. |
| 401 | "Unauthorised." — API key not found or secret is incorrect. |
| 401 | "Key {key_id} has been deactivated" — API key exists but has been deactivated. |
| 403 | "Forbidden." — The requested resource does not belong to your organisation. |
Identity request endpoint
Get identity request
Endpoint
GET https://public.pleasesign.com.au/identity-requests/:id
Example response
{
"id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "sent",
"doc_type": "document",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "Please verify your identity.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": 1531228750,
"verified_date": null,
"canceled_date": null,
"cancel_reason": null,
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "requires_input",
"created_date": 1531228750,
"sent_date": 1531228752,
"opened_date": null,
"submitted_date": null,
"verified_date": null,
"canceled_date": null,
"redacted_date": null,
"failure_code": null,
"failure_reason": null,
"report": null
}
]
}
This endpoint retrieves a single identity request, including its associated session and identity report (if verified). The request must belong to your organisation.
Error responses
See common errors for authentication and authorisation error responses.
List identity requests
Endpoint
GET https://public.pleasesign.com.au/identity-requests
Example response
{
"total_count": 42,
"data": [
{
"id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "sent",
"doc_type": "document",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "Please verify your identity.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": 1531228750,
"verified_date": null,
"canceled_date": null,
"cancel_reason": null,
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "requires_input",
"created_date": 1531228750,
"sent_date": 1531228752,
"opened_date": null,
"submitted_date": null,
"verified_date": null,
"canceled_date": null,
"redacted_date": null,
"failure_code": null,
"failure_reason": null,
"report": null
}
]
}
],
"next": "cb87hb3d91==",
"prev": null
}
Example request (filter by status)
GET https://public.pleasesign.com.au/identity-requests?status=verified
This endpoint retrieves a paginated list of identity requests belonging to your organisation. Results default to descending creation date order. You can filter by status and navigate pages using cursor-based next and prev pointers.
Parameters
| next string |
A cursor returned in the response body when the total number of results exceeds When a cursor is specified, status, order, and order_direction are disregarded. |
| prev string | A cursor returned after the second page. Specify this to retrieve the previous page. |
| status string | Filter results to a specific status. See Identity request statuses. |
| order string | Field to sort results by. See Identity request order. |
| order_direction string |
Direction of the sort: desc: Most recent first. This is the default.asc: Oldest first. |
| per_page integer | Number of results per page. Defaults to 20, maximum 100. Must be at least 1. |
Identity request statuses
| draft | Returns only requests saved as drafts and not yet sent. |
| sent | Returns requests that have been dispatched and are awaiting a verification outcome. This includes requests in the internal sending and processing states. |
| verified | Returns requests where the recipient was successfully verified. |
| failed | Returns requests where the verification attempt failed. |
| canceled | Returns requests that were canceled. |
Identity request order
| created_at | Order by the date the request was created. This is the default. |
| sent | Order by the date the request was dispatched to the recipient. |
| verified | Order by the date the recipient's identity was verified. |
| canceled | Order by the date the request was canceled. |
Create identity request
Endpoint
POST https://public.pleasesign.com.au/identity-requests
Example request (create and send immediately)
{
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"doc_type": "document",
"message": "As part of our compliance and security standards, we require a quick identity verification to confirm your identity. Please complete your verification using the secure link below."
}
Example request (save as draft)
{
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"doc_type": "document",
"draft": true
}
Example response (201 Created)
{
"id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "sent",
"doc_type": "document",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "As part of our compliance and security standards, we require a quick identity verification to confirm your identity. Please complete your verification using the secure link below.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": 1531228750,
"verified_date": null,
"canceled_date": null,
"cancel_reason": null,
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "requires_input",
"created_date": 1531228750,
"sent_date": 1531228752,
"opened_date": null,
"submitted_date": null,
"verified_date": null,
"canceled_date": null,
"redacted_date": null,
"failure_code": null,
"failure_reason": null,
"report": null
}
]
}
This endpoint creates a new identity request. By default, the request is sent immediately: an email and SMS notification are dispatched to the recipient and a verification session is provisioned. Provide draft: true to save the request without sending it — a draft can later be dispatched using the send endpoint.
When creating and sending immediately, the entire operation is atomic. If the verification session cannot be provisioned — for example because the mobile number is not accepted by the provider — the request is rolled back completely and a 400 is returned. No record is persisted in this case.
The sender parameter sets the display name the recipient will see as the sender. When not provided, the name of the user identified by sender_id (or the organisation owner) is used. See the sender_name field on the Identity request resource.
Request body
| first_name* string | The first name of the person to be verified. Maximum 100 characters. |
| last_name* string | The last name of the person to be verified. Maximum 100 characters. |
| email* string | The email address of the person to be verified. Must be a valid email address. |
| mobile* string | The mobile number of the person to be verified. Must match the provided country_code prefix. The + sign is optional and will be prepended automatically if omitted. See Mobile numbers for identity. |
| country_code* string | The ISO 3166-1 alpha-2 country code of the recipient. Case-insensitive; normalised to uppercase. Determines which document types are accepted and validates the mobile number prefix. See Mobile numbers for identity. |
| doc_type* string |
The type of document to accept for verification:
document: Any government-issued photo ID such as a passport or driving licence. id_number: A national identification number. Only supported for country_code US.
|
| message string | An optional message included in the notification to the recipient. Maximum 1000 characters. HTML is stripped. When not provided, defaults to: "As part of our compliance and security standards, we require a quick identity verification to confirm your identity. Please complete your verification using the secure link below." |
| sender_id string | The unique identifier of a user in your organisation to associate as the sender. Defaults to the organisation owner. The user must belong to your organisation. |
| sender string | A custom display name for the sender shown to the recipient. When provided, this is stored and used as sender_name in place of the linked user's name. Maximum 100 characters. HTML is stripped. |
| brand_id string | The unique identifier of a brand to apply. The brand must belong to your organisation. |
| draft boolean | When true, saves the request as a draft without sending. Defaults to false. |
Fields marked with an * are required.
Error responses
| 400 | Validation error — a required field is missing, email format is invalid, doc_type is unsupported, id_number is used with a non-US country code, or the mobile number fails format or country code validation. |
See common errors for authentication and authorisation error responses.
Update identity request
Endpoint
PUT https://public.pleasesign.com.au/identity-requests/:id
Example request
{
"first_name": "Janet",
"last_name": "Jones",
"message": "Updated message for the recipient."
}
Example response (200 OK)
{
"id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "draft",
"doc_type": "document",
"first_name": "Janet",
"last_name": "Jones",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "Updated message for the recipient.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": null,
"verified_date": null,
"canceled_date": null,
"cancel_reason": null,
"identity_sessions": []
}
This endpoint updates the fields of a draft identity request. Only requests with a status of draft can be updated. All fields are optional and only the fields provided will be updated.
If mobile or country_code is provided, mobile number validation is applied against the effective values after the update. See Mobile numbers for identity.
Request body
| first_name string | Updated first name. Maximum 100 characters. |
| last_name string | Updated last name. Maximum 100 characters. |
| email string | Updated email address. Must be a valid email address. |
| mobile string | Updated mobile number. Must match the effective country_code. The + sign is optional. See Mobile numbers for identity. |
| country_code string | Updated country code. ISO 3166-1 alpha-2. Case-insensitive; normalised to uppercase. |
| doc_type string | Updated document type. Accepted values are document and id_number. id_number is only supported for country_code US. |
| message string | Updated recipient message. Maximum 1000 characters. HTML is stripped. |
| sender_id string | Updated sender user ID. Must belong to your organisation. |
| sender string | Updated custom display name for the sender. Maximum 100 characters. HTML is stripped. |
| brand_id string | Updated brand ID. Must belong to your organisation. |
Error responses
| 400 | Identity request {id} is not a draft and cannot be updated. |
| 400 | Validation error — email format, doc_type, country_code, field length, or mobile validation failed. |
| 400 | User {id} does not exist. |
See common errors for authentication and authorisation error responses.
Delete identity request
Endpoint
DELETE https://public.pleasesign.com.au/identity-requests/:id
Example response
204
This endpoint permanently deletes a draft identity request. Only requests with a status of draft can be deleted — once sent, a request must be canceled instead. A successful deletion returns 204 No Content with an empty body.
Error responses
| 400 | Identity request {id} is not a draft and cannot be deleted. |
See common errors for authentication and authorisation error responses.
Send identity request
Endpoint
POST https://public.pleasesign.com.au/identity-requests/:id/send
Example request
{}
Example response (200 OK)
{
"id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "sent",
"doc_type": "document",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "Please verify your identity.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": 1531228750,
"verified_date": null,
"canceled_date": null,
"cancel_reason": null,
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "requires_input",
"created_date": 1531228750,
"sent_date": 1531228752,
"opened_date": null,
"submitted_date": null,
"verified_date": null,
"canceled_date": null,
"redacted_date": null,
"failure_code": null,
"failure_reason": null,
"report": null
}
]
}
This endpoint sends a previously saved draft identity request to the recipient. The status update and verification session provisioning are wrapped in a transaction — if the session cannot be provisioned (for example because the mobile number is rejected by the provider) the transaction rolls back completely and the request status remains draft. The notification is dispatched asynchronously after the transaction completes.
An optional message field updates the stored message on the request before sending, permanently replacing the existing value. The updated message is used in the notification sent to the recipient.
This endpoint can only be used when the request status is draft.
Request body
| message string | Optional. Updates and permanently replaces the message stored on the request before sending. |
Error responses
| 400 | Identity request has already been sent. |
| 400 | Stripe error — the mobile number or other provided details were rejected by the verification provider. |
See common errors for authentication and authorisation error responses.
Cancel identity request
Endpoint
POST https://public.pleasesign.com.au/identity-requests/:id/cancel
Example request
{
"reason": "Recipient requested cancellation."
}
Example response (200 OK)
{
"id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "canceled",
"doc_type": "document",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "Please verify your identity.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": 1531228750,
"verified_date": null,
"canceled_date": 1531229000,
"cancel_reason": "Recipient requested cancellation.",
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "requires_input",
"created_date": 1531228750,
"sent_date": 1531228752,
"opened_date": null,
"submitted_date": null,
"verified_date": null,
"canceled_date": null,
"redacted_date": null,
"failure_code": null,
"failure_reason": null,
"report": null
}
]
}
This endpoint cancels an identity request. The request status transitions to canceled immediately, and the cancellation is propagated to the upstream verification provider to cancel any active sessions. The session status in the immediate response may still show requires_input — the provider confirms the session cancellation asynchronously, so the session's own canceled_date will be set shortly after via an inbound webhook from Stripe.
A request can be canceled when its status is sent, processing, or failed. Draft requests should be deleted instead.
Request body
| reason string | Optional reason for the cancellation. Stored on the request as cancel_reason. |
Error responses
| 400 | Identity request cannot be canceled at this time. |
| 400 | Unable to cancel identity verification. Please try again later. |
See common errors for authentication and authorisation error responses.
Identity session endpoint
Resend identity notification
Endpoint
POST https://public.pleasesign.com.au/identity-sessions/:id/resend
Example request
{}
Example response (200 OK)
{
"id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "sent",
"doc_type": "document",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "Please verify your identity.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": 1531228750,
"verified_date": null,
"canceled_date": null,
"cancel_reason": null,
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "requires_input",
"created_date": 1531228750,
"sent_date": 1531228800,
"opened_date": null,
"submitted_date": null,
"verified_date": null,
"canceled_date": null,
"redacted_date": null,
"failure_code": null,
"failure_reason": null,
"report": null
}
]
}
This endpoint re-notifies the recipient for a given identity session. It is intended for cases where the initial notification was not received, the session has expired, or the previous attempt failed and you want to give the recipient another chance to verify.
A resend does not create a new session. Instead, the existing session is updated in place: its verification URL and expiry are refreshed from the provider, any previous failure information is cleared, and the status is reset to requires_input. The response returns the full identity request.
This endpoint can only be used when the session status is requires_input, failed, or expired, and when the parent identity request is active.
To prevent spamming, resend is rate-limited to once per 30 minutes per session. If called within 30 minutes of the previous resend, a 400 is returned.
Request body
Error responses
| 400 | Identity session cannot be resent at this time. |
| 400 | Identity request is inactive. |
| 400 | A reminder has already been sent recently. Please wait before sending another. |
| 400 | No verification session found to resend. |
See common errors for authentication and authorisation error responses.
Correct identity session
Endpoint
POST https://public.pleasesign.com.au/identity-sessions/:id/correct
Example request
{
"first_name": "Janet",
"last_name": "Smith",
"email": "janet@example.com",
"mobile": "+61491570007",
"country_code": "AU"
}
Example response (200 OK)
{
"id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "sent",
"doc_type": "document",
"first_name": "Janet",
"last_name": "Smith",
"email": "janet@example.com",
"mobile": "+61491570007",
"country_code": "AU",
"message": "Please verify your identity.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": 1531228750,
"verified_date": null,
"canceled_date": null,
"cancel_reason": null,
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "requires_input",
"created_date": 1531228750,
"sent_date": 1531228752,
"opened_date": null,
"submitted_date": null,
"verified_date": null,
"canceled_date": null,
"redacted_date": null,
"failure_code": null,
"failure_reason": null,
"report": null
}
]
}
This endpoint corrects the recipient details on an identity session and its parent identity request. It can only be used when the session status is requires_input.
The behaviour of this endpoint depends on what is corrected:
- If
emailormobileis changed, the verification session at the provider is updated with the new details and a new notification is automatically dispatched to the recipient. There is no need to call resend separately in this case. - If only
first_nameorlast_nameis updated (without changingemailormobile), the records are updated locally but no new notification is sent.
If country_code is provided, mobile must also be provided. The mobile number must match the new country code prefix. See Mobile numbers for identity.
All fields are optional; only the fields provided will be updated. The response returns the full identity request with the updated values.
Request body
| first_name string | Updated first name. Maximum 100 characters. |
| last_name string | Updated last name. Maximum 100 characters. |
| email string | Updated email address. Must be a valid email address. If changed, triggers a new notification to the updated address. |
| mobile string | Updated mobile number. Must match the effective country_code. If changed, triggers a new notification to the updated number. See Mobile numbers for identity. |
| country_code string | Updated country code. ISO 3166-1 alpha-2. Case-insensitive. Must be provided alongside mobile. |
Error responses
| 400 | Identity session can only be corrected when its status is requires_input. |
| 400 | Validation error — email format, country code, or mobile number validation failed. |
| 400 | country_code cannot be updated without providing mobile. |
| 400 | No Stripe verification session found to update. |
| 400 | Unable to update Stripe verification session. Please try again. |
See common errors for authentication and authorisation error responses.
Redact identity session
Endpoint
POST https://public.pleasesign.com.au/identity-sessions/:id/redact
Example request
{
"redact_in_ps": true
}
Example response (200 OK)
{
"id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "verified",
"doc_type": "document",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "Please verify your identity.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": 1531228750,
"verified_date": 1531228900,
"canceled_date": null,
"cancel_reason": null,
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "redaction_processing",
"created_date": 1531228750,
"sent_date": 1531228752,
"opened_date": 1531228800,
"submitted_date": 1531228850,
"verified_date": 1531228900,
"canceled_date": null,
"redacted_date": null,
"failure_code": null,
"failure_reason": null,
"report": null
}
]
}
This endpoint initiates redaction of the identity data for a verification session. A redaction request is submitted to the verification provider immediately, and the session status transitions to redaction_processing. The actual removal of data is confirmed asynchronously by the provider — the status will transition to redacted once confirmed, at which point redacted_date will be populated. The response returns the full identity request.
Redaction permanently removes sensitive personal information — including the identity report and any document images held by the provider — and cannot be undone.
The redact_in_ps flag controls whether PleaseSign's own stored copy of the identity report is also deleted. When true, the report is removed from PleaseSign as well. When false, only the upstream provider data is redacted.
Redaction is permitted when the session status is verified or requires_input. A session already in redaction_processing, already redacted, canceled, or failed cannot be redacted.
Request body
| redact_in_ps* boolean | Whether to also delete the identity report from PleaseSign's records. |
Fields marked with an * are required.
Error responses
| 400 | Redaction is only allowed when verification status is verified or requires_input. |
| 400 | Redaction is already in progress for this verification session. |
| 400 | This verification session has already been redacted. |
| 400 | No Stripe verification session found to redact. |
| 400 | Stripe redaction request failed. Please try again later. |
See common errors for authentication and authorisation error responses.
Identity connector events
PleaseSign fires identity webhook events whenever significant state changes occur on an identity request or its session. These events follow the same delivery, validation, deduplication, and retry behaviour as document connector events — please review the Connector section for full details on testing, validating signatures, handling duplicates, and responding to webhooks.
Identity webhooks are configured separately from document webhooks. You can register your endpoint and test identity events from the Webhooks settings page by selecting the Identity tab.
Here are some examples of how you might use identity webhooks:
- Trigger your own onboarding flow once a recipient has been successfully verified.
- Correct a recipient's mobile number and resend when a session fails.
- Update your records when an identity request is canceled.
- Retrieve the full identity report once verification is confirmed.
identity_request.created
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "identity_request.created",
"identity_request_id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "draft",
"doc_type": "document",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "As part of our compliance and security standards, we require a quick identity verification to confirm your identity. Please complete your verification using the secure link below.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"sent_date": null,
"verified_date": null,
"canceled_date": null,
"cancel_reason": null
}
This webhook event fires immediately when an identity request is created, whether created as a draft or sent immediately. The full state of the request at the moment of creation is included.
Request body
| id string | Unique event identifier. |
| event string | "identity_request.created". |
| identity_request_id string | The unique identifier of the identity request that was created. |
| status string | The status of the request at creation time. |
| doc_type string | The document type accepted for verification. |
| first_name string | The first name of the person to be verified. |
| last_name string | The last name of the person to be verified. |
| email string | The email address of the person to be verified. |
| mobile string | The mobile number of the person to be verified. |
| country_code string | The ISO country code of the recipient. |
| message string | The custom message, if any. |
| active boolean | Whether the request is active. |
| brand_id string | The brand applied, if any. |
| sender_id string | The unique identifier of the sender user. |
| sender_name string | The display name of the sender. |
| sender_email string | The email address of the sender. |
| sender_business string | The business name of the sender's organisation. |
| created_date integer | UTC unix timestamp of when the request was created. |
| sent_date integer | Always null at creation time. |
| verified_date integer | Always null at creation time. |
| canceled_date integer | Always null at creation time. |
| cancel_reason string | Always null at creation time. |
identity_request.updated
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "identity_request.updated",
"identity_request_id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "draft",
"doc_type": "document",
"first_name": "Janet",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"message": "As part of our compliance and security standards, we require a quick identity verification to confirm your identity. Please complete your verification using the secure link below.",
"active": true,
"brand_id": null,
"sender_id": "a6564df8db9e9624",
"sender_name": "John Doe",
"sender_email": "john@example.com",
"sender_business": "Acme Corp",
"created_date": 1531228693,
"updated_date": 1531228750,
"sent_date": null,
"verified_date": null,
"canceled_date": null,
"cancel_reason": null
}
This webhook event fires when an identity request's fields are updated — either via the update endpoint on a draft, or via the correct endpoint on an active session. The full updated state is included.
Request body
| id string | Unique event identifier. |
| event string | "identity_request.updated". |
| identity_request_id string | The unique identifier of the identity request that was updated. |
| status string | The current status of the request. |
| doc_type string | The document type accepted for verification. |
| first_name string | The updated first name. |
| last_name string | The updated last name. |
| email string | The updated email address. |
| mobile string | The updated mobile number. |
| country_code string | The updated country code. |
| message string | The updated message. |
| active boolean | Whether the request is active. |
| brand_id string | The brand applied, if any. |
| sender_id string | The unique identifier of the sender user. |
| sender_name string | The display name of the sender. |
| sender_email string | The email address of the sender. |
| sender_business string | The business name of the sender. |
| created_date integer | UTC unix timestamp of when the request was created. |
| updated_date integer | UTC unix timestamp of when the request was last updated. |
| sent_date integer | UTC unix timestamp of when the request was sent. May be null for draft requests. |
| verified_date integer | UTC unix timestamp of when the request was verified. May be null. |
| canceled_date integer | UTC unix timestamp of when the request was canceled. May be null. |
| cancel_reason string | The cancellation reason, if any. |
identity_request.verified
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "identity_request.verified",
"identity_request_id": "PLSIDREQ19704278f8c51564ff0c707817",
"status": "verified",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"country_code": "AU",
"doc_type": "document",
"verified_date": 1531229100,
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "verified",
"verified_date": 1531229100
}
]
}
This webhook event fires when the recipient has successfully completed identity verification and the request transitions to verified. The nested identity_sessions array identifies the session that was verified. To retrieve the full identity report, call the get identity request endpoint after receiving this event.
Request body
| id string | Unique event identifier. |
| event string | "identity_request.verified". |
| identity_request_id string | The unique identifier of the identity request. |
| status string | "verified". |
| first_name string | The first name of the person who was verified. |
| last_name string | The last name of the person who was verified. |
| email string | The email address of the person who was verified. |
| mobile string | The mobile number of the person who was verified. |
| country_code string | The country code of the request. |
| doc_type string | The document type that was used for verification. |
| verified_date integer | UTC unix timestamp of when the request was verified. |
| identity_sessions array | Array containing the single session that was verified. |
| identity_sessions[].id string | The unique identifier of the verified session. |
| identity_sessions[].status string | "verified". |
| identity_sessions[].verified_date integer | UTC unix timestamp of when the session was verified. |
identity_request.canceled
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "identity_request.canceled",
"identity_request_id": "PLSIDREQ19704278f8c51564ff0c707817",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"canceled_date": 1531229000,
"cancel_reason": "Recipient requested cancellation."
}
This webhook event fires when an identity request is canceled, either via the cancel endpoint or from within the PleaseSign application. The cancel_reason field will be null if no reason was provided.
Request body
| id string | Unique event identifier. |
| event string | "identity_request.canceled". |
| identity_request_id string | The unique identifier of the identity request that was canceled. |
| first_name string | The first name of the person whose request was canceled. |
| last_name string | The last name of the person whose request was canceled. |
| email string | The email address of the person whose request was canceled. |
| canceled_date integer | UTC unix timestamp of when the request was canceled. |
| cancel_reason string | The reason for cancellation, if provided. May be null. |
identity_session.sent
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "identity_session.sent",
"identity_request_id": "PLSIDREQ19704278f8c51564ff0c707817",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"method": "email",
"sent_date": 1531228752,
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "requires_input",
"expires_at": 1531401552,
"created_date": 1531228750
}
]
}
This webhook event fires after a notification has been dispatched to the recipient. This includes both the initial send and any resends. The method indicates whether the notification was sent via email or SMS.
The expires_at timestamp shows when the verification session will expire. After this time the recipient's verification link will no longer work. Use the resend endpoint to refresh the session if needed.
This event does not guarantee that the notification was delivered to the recipient — only that the dispatch was queued successfully.
Request body
| id string | Unique event identifier. |
| event string | "identity_session.sent". |
| identity_request_id string | The unique identifier of the parent identity request. |
| 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 channel used to deliver the notification. Can be "email" or "sms". |
| sent_date integer | UTC unix timestamp of when the notification was dispatched. |
| identity_sessions array | Array containing the single session for this request. |
| identity_sessions[].id string | The unique identifier of the session. |
| identity_sessions[].status string | The session status at the time of sending — typically "requires_input". |
| identity_sessions[].expires_at integer | UTC unix timestamp of when the verification session expires. |
| identity_sessions[].created_date integer | UTC unix timestamp of when the session was created. |
identity_session.opened
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "identity_session.opened",
"identity_request_id": "PLSIDREQ19704278f8c51564ff0c707817",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"method": "email",
"opened_date": 1531228800
}
This webhook event fires when a recipient agrees to the disclosure and opens the identity verification interface. If the recipient clicks the same notification link more than once, this event fires only once per dispatch. The method indicates the channel the recipient used to access the interface.
Request body
| id string | Unique event identifier. |
| event string | "identity_session.opened". |
| identity_request_id string | The unique identifier of the parent identity request. |
| 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 channel the recipient used to access the interface. Can be "email" or "sms". |
| opened_date integer | UTC unix timestamp of when the recipient agreed to the disclosure. |
identity_session.failed
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "identity_session.failed",
"identity_request_id": "PLSIDREQ19704278f8c51564ff0c707817",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "+61491570006",
"doc_type": "document",
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "failed",
"expires_at": 1531401552,
"created_date": 1531228750,
"failure_code": "document_expired",
"failure_reason": "The document provided has expired."
}
]
}
This webhook event fires when a verification session fails. Failures can occur for a number of reasons:
- The document provided by the recipient has expired.
- The document type is not supported for the given country.
- The verification provider could not verify the document.
- The recipient declined the disclosure agreement before beginning verification.
The failure_code and failure_reason provide details. The failure_reason is sourced from the provider and may be null in some cases. After a failure, you can use the resend endpoint to give the recipient another attempt.
Request body
| id string | Unique event identifier. |
| event string | "identity_session.failed". |
| identity_request_id string | The unique identifier of the parent identity request. |
| 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. |
| doc_type string | The document type that was requested. |
| identity_sessions array | Array containing the single session that failed. |
| identity_sessions[].id string | The unique identifier of the failed session. |
| identity_sessions[].status string | "failed". |
| identity_sessions[].expires_at integer | UTC unix timestamp of when the session was due to expire. |
| identity_sessions[].created_date integer | UTC unix timestamp of when the session was created. |
| identity_sessions[].failure_code string | A machine-readable failure code. |
| identity_sessions[].failure_reason string | A human-readable failure description. May be null. |
identity_session.redacted
Example request
{
"id": "fe6de8a8ebfa5fc13edea83ab35c298c",
"event": "identity_session.redacted",
"identity_request_id": "PLSIDREQ19704278f8c51564ff0c707817",
"doc_type": "document",
"identity_sessions": [
{
"id": "PLSIDS311150de0b08d1a7c4d8b83d",
"status": "redacted",
"redacted_date": 1531229100,
"redact_in_ps": true
}
]
}
This webhook event fires once the verification provider has confirmed that the identity data for a session has been permanently removed. This follows the redaction_processing status set by the redact endpoint. The redact_in_ps field indicates whether PleaseSign's own copy of the report was also deleted.
Request body
| id string | Unique event identifier. |
| event string | "identity_session.redacted". |
| identity_request_id string | The unique identifier of the parent identity request. |
| doc_type string | The document type of the verification that was redacted. |
| identity_sessions array | Array containing the single session that was redacted. |
| identity_sessions[].id string | The unique identifier of the redacted session. |
| identity_sessions[].status string | "redacted". |
| identity_sessions[].redacted_date integer | UTC unix timestamp of when the redaction was confirmed. |
| identity_sessions[].redact_in_ps boolean | Whether PleaseSign's own copy of the identity report was also deleted. |