NAV Navbar
  • Authentication
  • Request Ids
  • Email templates
  • White labelling
  • Resources
  • Brand endpoint
  • Document endpoint
  • Recipient endpoint
  • Connector
  • Connector events
  • Authentication

    API Endpoint

    https://public.pleasesign.com.au/
    

    Authentication headers

    X-PLEASESIGN-KEY: PLSAPPd6117bb82a3329dc401c2605b20745ea
    X-PLEASESIGN-SECRET: 88bc54853d5d429d17f71140e91c6412769e93a7
    

    Authenticate your account by including your public and secret key in API requests. You can manage your API keys when logged in as the owner of an organisation on the developer settings page. Your API keys carry many privileges, including access to all documents you send with PleaseSign, so be sure to keep them secure! Do not share your secret key in publicly accessible areas such as GitHub, client-side code, and so forth.

    Authentication to the API is performed via HTTP Basic Auth. Provide your API keys as headers in each request to authenticate.

    All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without the authentication headers will also fail.

    Request Ids

    Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers against each logs on the request logs page. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

    Email templates

    With the signing url endpoint and silent recipients, we provide you the tools necessary to control every aspect of how and when your recipients receive emails notifying them they have documents to sign.

    For a more straight forward approach, you can customize the default email templates that PleaseSign provides through the business preferences dashboard. Refer to the image below on what fields are customisable and how they can be changed.

    Email template example

    White labelling

    Our branding feature allows you to personalise the logo and colour scheme of the signing interface. By default all organisations are set up with the PleaseSign brand, which will be used for all recipients when completing a document. To use your own brand you will need to supply a brand_id when sending a Create document request.

    Colours

    All colour fields require a valid hexidecimal colour code consisting of the hash symbol (#), followed by six characters. All colour fields are optional, so any fields that you do not choose to customise will be set to their default value.

    The following table lists all of the customisable colour fields and their default values.

    Field Default
    bg_primary
    #eeeeee
    bg_secondary
    #ffffff
    bg_accent
    #383838
    text_primary
    #212121
    text_secondary
    #ffffff
    btn_bg_primary
    #f49848
    btn_text_primary
    #ffffff
    btn_bg_secondary
    #383838
    btn_text_secondary
    #ffffff

    Signing interface

    The following image can be used as a reference to understand which colour fields change which part of the signing interface. Buttons do not have a hover or a focus effect, and use a material waves effect on click.

    Email template example

    Sender card

    The sender card is an element shown on the default email template, and on the signing interface used to identify the sender of the document to the recipient. The fields shown in this card are inheritted automatically by the sender of the document, defaulting to the owner of the organisation when no sender is provided, or otherwise overriden by specifying a brand when sending a document.

    Note: The avatar is currently not available as a field that can be customised at a brand level and instead is read from the sender of the document, defaulting to the owner of the organisation when no sender is provided. All users are created with the default PleaseSign avatar until otherwise set.

    Email template example

    Resources

    All date properties associated with a resource are returned in UTC unix time format.

    Brand

    A brand is a set of rules that determine how the signing interface should be styled, and which information should be made available to the recipients in the sender card.

    Refer to the white labelling section for more information on brands.

    id string Unique identifier for the brand.
    name string The name of the brand, intended as an identifier when viewing multiple brands.
    business string The business name, this will override the business name in the sender card.
    email string The email address, this will override the email address in the sender card.
    logo string The complete HTTPS url for the logo, this will be used in email templates and in the signing interface.
    bg_primary string Primary background colour.
    bg_secondary string Secondary background colour.
    bg_accent string Accent background colour.
    text_primary string Primary text colour, sits on the secondary background.
    text_secondary string Secondary text colour, sits on the accent background.
    btn_bg_primary string Primary button background colour, sits on the accent background.
    btn_text_primary string Primary button text colour, sits on the accent background.
    btn_bg_secondary string Secondary button background colour, sits on the accent background.
    btn_text_secondary string Secondary button text colour, sits on the accent background.

    Document

    id string Unique identifier for the document, prepended with "PLSDOC".
    title string The title of the document, doubles as the subject of the email that is sent to te recipients.
    message string The message of the email that is sent to recipients.
    status string The current status of the document, possible values are building, sent, complete and void.
    brand_id string Unique identifier of the brand that was used when creating the document, if no brand was provided the organisation's default brand is used.
    sender_id string Unique identifier of the user that sent the document. If no sender_id is provided when creating the document, defaults to the owner of the organisation.
    sender_name string The full name of the user that sent the document, or the sender property that was provided when creating the document.
    sender_email string The email address of the user that sent the document, or the email address associated to the brand that was provided when creating the document.
    sender_business string Your organisation's business name, or the business name associated to the brand that was provided when creating the document.
    created_date integer Unix timestamp of when the document was created.
    sent_date integer Unix timestamp of when the document was sent.
    complete_date integer Unix timestamp of when the document was successfully signed and sealed.
    void_date integer Unix timestamp of when the document was declined by one of the recipients, or by action of the sender.
    void_reason integer The reason provided by one of the recipients or by the sender when opting to decline/void the document.
    recipients array Array of recipients.

    Lifecycle

    The status property is intended for a quick reference on the state of a document at any given time. Each possible value is listed below, alongside an explanation on what each value represents and how it transitions to and from it's next and previous values.

    building When a document is created the status is set to building. During the building phase the PDF file is normalised, encrypted and prepared for digital signing. When this operation is complete, an email will be dispatched to the appropriate recipients adhering to silent and routing properties and the document status will transition to sent.
    sent This status represents action pending by one or more recipients. From this status the document can transition to void by either being declined by one of the recipients, or by action of the sender. Once all recipients have signed the document the status will transition to complete.
    complete Represents a completed document that has been agreed to and signed by all recipients.
    void The document has been declined by one of the recipients of voided by the sender. Voided documents will generally be accompanied by a void_reason, though not enforced, users are encouraged to enter a reason when choosing to decline/void a document.

    Email reminders

    Reminders can be configured for your recipients at an account level, you can specify a frequency in the number of days between email reminders and an attempt count which will be the maximum number of reminders sent before they stop.

    For example: a document sent to a recipient with reminders configured with a frequency of 7 and an attempt count of 4 will have a reminder email sent 7 days after the initial email for a total of 4 weeks before stopping. Resulting in five total emails sent, including the first initial email that was not a reminder.

    Reminder emails will not be sent to recipients that have signed the document.

    Email reminders can be configured from your Business profile page.

    Recipient

    id string Unique identifier for the recipient.
    first_name string The first name of the recipient.
    last_name string The last name of the recipient.
    email string The email address of the recipient.
    mobile string The mobile number of the recipient. See Mobile numbers for more information.
    status string The current status of the recipient, possible values are pending, sent, failed, complete and void.
    silent boolean Whether or not signing emails are automatically dispatched to the recipient when a document is created, or when routing order determines the recipient is next.
    redirect string A redirect url used to navigate the recipients web browser to after signing a document.
    redirect_void string A redirect url used to navigate the recipients web browser to after they choose to decline a document.
    routing integer Positive integer used to determine the order in which the recipient is to receive the document for signing. Will take into account silent property.
    nominee_id string The unique identifier for another recipient on the same document to be used as the nominee for in person signing.
    created_date integer Unix timestamp of when the recipient was created.
    complete_date integer Unix timestamp of when the recipient signed the document.
    reminder_date integer Unix timestamp of when the next email reminder is scheduled to be sent. See Email reminders for more information.
    reminder_count integer The number of reminders that the recipient has received. See Email reminders for more information.

    Ordered signing

    To control the order in which recipients are to receive a document for digital signing, provide a routing property set as a positive integer. Recipients will only have emails dispatched when all recipients with a lesser routing value has signed the document and had their status set to complete.

    In person signing

    To use the in person signing feature, provide a nominee property set as the email address of another recipient. Once created, this property will be replaced with the id of the first matching recipient.

    Silent recipients

    To manage the distribution of signing urls from your own application, provide a silent property set to false 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.

    Tab

    Tabs identify positions on a document where recipient input is generally required. Tabs can be customised by accompanying attributes, such as the dimensions of the tab and whether or not input is required before the document can be completed.

    kind string The tab type.
    anchor string The anchor string, see anchors for more information.
    x integer The X coordinate of the tab, assuming the origin 0,0 as the bottom left of the pdf at 72DPI.
    y integer The Y coordinate of the tab, assuming the origin 0,0 as the bottom left of the pdf at 72DPI.
    page integer The page number the tab should be positioned on, page numbers start at index 1.
    height integer The pixel height of the tab, only applicable when the tab kind is signature, input or check. If this is not provided the following defaults are given: signature: 30, input: 23, check: 8.
    width integer The pixel width of the tab, only applicable when the tab kind is input. If this is not provided the following default value is used: 100. Check tabs have their width set to the given height property due to a forced 1:1 aspect ratio and signatures automatically set due to a forced 1:2.5 aspect ratio.
    text_height integer The pixel font-size of the tab, only applicable when the tab kind is first_name, last_name, full_name, sign_date, sign_short_date or input. If this is not provided the default value is set to 11.
    required boolean Whether or not the recipient is required to enter a value into the input box before the document can be completed, only applicable when the tab kind is input.

    Tab types

    The following table lists the tab types that are available, and how recipients must action each tab in order to complete a document.

    Signature signature Allows the recipient to sign the document by drawing their signature.
    Witness witness Allows the signature of the recipient to be witnessed by another individual.
    Signature datetime sign_date Displays the date and time the recipient signed the document in format DD/MM/YYYY hh:mma.
    Signature date sign_short_date Displays the date the recipient signed the document in format DD/MM/YYYY.
    Input box input Allows the recipient to enter any type of text, can be enforced by the required property.
    Checkbox check Allows the recipient to tick a box if applicable, checkbox's are optional and not required to be ticked in order to complete a document.
    First name first_name Displays the recipient's first name based on what was entered in the recipient information.
    Last namelast_name Displays the recipient's last name based on what was entered in the recipient information.
    Full namefull_name Displays the recipient's full name, joining the first name and last name with a space as entered in the recipient information.

    Coordinate system

    The coordinate system used is a standard pixel-based reference to any given location on a pdf file at 72DPI. All coordinate values should assume the origin 0,0 as the bottom left of the document and should always specify the XY position of the bottom left corner of the tab.

    When specifying the coordinates for an input type tab, specify the XY position of the tab as the top left, rather than the bottom left. This is because the top left corner will always remain static, even when the tab grows from user input.

    Anchors

    Tab anchors can be used as an alternative method to the coordinate system as a way to intelligently position tabs on a page. Commonly used for documents with dynamic content that may shift the position of tabs, anchors provides a simple way for you to offset the logic of positioning tabs to PleaseSign.

    When using anchors, the x, y, and page properties do not need to be provided in the request as they will be determined for you.

    When given an anchor, all pages of the document will be scanned and any text elements matching the anchor exactly will have a tab created at it's found location. If more than one match is found on the document, each match will have a tab created at it's location.

    Anchors are case-insensitive, meaning anchor foobar will match a FooBar text element found on the document. Text elements found are not partially-matched to anchors meaning anchor {foobar} will not match a {{foobar}} text element.

    Anchors that are found too close to the edge of a document, that would otherwise cause the tab to overflow, fail silently and do not get created. Anchors that cannot be found on the document fail silently and do not get created.

    All tabs except input are positioned at the bottom left origin of the matched text element of the anchor, input tabs are positioned at the top-left origin of the matched text element.

    User

    Users within your organisation can be created to change the sender of a document to personalise emails that are sent to recipients by PleaseSign. Senders will also receive notification emails when a document has either been completed, or declined by one of the recipients. Documents voided by the sender will not trigger a notification email.

    Each user created will need to verify their email address before their id can be used as the sender of a document.

    id string Unique identifier for the user.
    first_name string The first name of the user.
    last_name string The last name of the user.
    email string The email address of the user.
    active boolean Whether or not the user is active.

    Brand endpoint

    Get brand

    Endpoint

    GET https://public.pleasesign.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.

    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.

    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.
    first_name* string The first name of the recipient.
    last_name* string The last name of the recipient.
    email* string The email address of the recipient.
    mobile string The mobile number of the recipient.
    routing integer The order in which the recipient should receive the document.
    nominee string The email address of another recipient to act as the nominee.
    silent boolean Whether this recipient should be treated as silent.
    redirect string The URL the recipients web browser should be navigated to upon completing the document.
    redirect_void string The URL the recipients web browser should be navigated to after declining a document.
    tabs* array Array of tabs for the recipient.
    kind* string The tab type.
    anchor** string The anchor string for the tab, required when not using x and y coordinates.
    x_offset int The X axis offset value that will be applied to the found anchor position.
    y_offset int The Y axis offset value that will be applied to the found anchor position.
    page** integer The page number the tab should be positioned on. Required when not using an anchor string, page numbers start at index 1.
    x** integer The X coordinate of the tab, required when not using an anchor string.
    y** integer The Y coordinate of the tab, required when not using an anchor string.
    height integer The pixel height of the tab.
    width integer The pixel width of the tab.
    text_height integer The pixel font-size of the tab.
    required boolean Whether or not the tab is required.

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

    Void document

    Endpoint

    POST https://public.pleasesign.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",
      "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",
      "status": "sent",
      "silent": false,
      "redirect": "https://www.google.com.au/",
      "redirect_void": "https://www.google.com.au/",
      "routing": 1,
      "nominee": null,
      "created_date": 1531228693,
      "complete_date": null,
      "reminder_date": null,
      "reminder_count": 0
    }
    

    This endpoint is intended to be used when the information for a recipient that has not yet signed the document needs to be updated. A recipient's information can only be changed when the status is either pending, sent or failed.

    When a recipient is corrected, a new recipient with the information provided is created in it's place. The old recipient is immediately removed from the document and will no longer be able to access the document through any of the emails or sms messages previously dispatched.

    The new recipient created will automatically inherit the tabs that were initially created against the old recipient.

    Request body

    Before reading the request body for this endpoint, we encourage you to have a good understanding of the Recipient resource to better understand some of the properties and how they may affect the workflow of a document.

    id string Unique identifier for the recipient being corrected.
    first_name* string The corrected first name of the recipient.
    last_name*string The corrected last name of the recipient.
    email* string The corrected email address of the recipient.
    mobile string The corrected mobile number of the recipient.
    redirect string The URL the recipients web browser should ne navigated to upon completing the document.
    redirect_void string The URL the recipients web browser should ne navigated to after declining a document.

    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:

    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.

    Duplicate webhooks

    Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicate events by making your event processing idempotent. One way of doing this is by logging the id of each event that you process, and then not processing already-logged events.

    Responding to a webhook

    To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to PleaseSign that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure. PleaseSign will ignore any other information returned in the request headers or request body.

    Webhook failures

    If your endpoint does not successfully receive a webhook for any reason, we will continue trying to send the webhook every hour for up to three days. Webhooks cannot be manually retried after this time, though you can view a log of the failed webhooks from the Webhooks settings page and send the request yourself using a HTTP client such as Postman.

    Webhook failures on test events you manually send will not be retried, response codes will be logged in your request logs so you can monitor how each request is performing.

    Referencing dates

    It is important when processing webhook events that you refer to the date properties included in the request body with each event, rather than the current timestamp of when you receive the event. As webhooks are processed asynchronously there may be a delay between the time the webhook event was created and when it was sent to your endpoint.

    Connector events

    document.created

    Example request

    {
      "id": "fe6de8a8ebfa5fc13edea83ab35c298c",
      "event": "document.created",
      "document_id": "PLSDOC19704278f8c51564ff0c707817",
      "processed_date": 1531228693
    }
    

    This webhook event is registered when a document has been completely processed after being created and has had its status transitioned to sent. If you are using silent recipients and sending your own signing emails, this is when you will be able to request a signing url for each recipient.

    When you are not using silent recipients, this webhook event will generally be accompanied by a recipient.sent event for each recipient that has been sent a signing email. It is not gauranteed that this webhook event will be received before any of the recipient.sent events.

    Request body

    id string Unique event identifier.
    event string "document.created".
    document_id string The unique identifier for the document that was created.
    processed_date integer Unix timestamp of when the document was processed and had its status transition to sent.

    document.void

    Example request

    {
      "id": "fe6de8a8ebfa5fc13edea83ab35c298c",
      "event": "document.void",
      "document_id": "PLSDOC19704278f8c51564ff0c707817",
      "recipient_id": "52cc002fac06025cddad05de87f75b37",
      "void_date": 1531228693,
      "void_reason": "Lorem ipum solar sit amet."
    }
    

    This webhook event is registered when a recipient declines a document. The status of the document and the recipient will have already transitioned to void before this webhook is sent.

    Recipients are not required to enter a reason when declining a document and therefore you will need to expect that the void_reason field may be null.

    This webhook is not registered when a document is voided via direct API request, as the process of voiding a document is synchronous, it is expected you can execute the same workflow upon successful return of a void request.

    Request body

    id string Unique event identifier.
    event string "document.void".
    document_id string The unique identifier for the document that was voided.
    recipient_id string The unique identifier for the recipient that declined the document.
    void_date integer Unix timestamp of when the recipient declined the document.
    void_reason string The reason provided by the recipient when declining the document. This field is not required when declining a document and may be null.

    document.complete

    Example request

    {
      "id": "fe6de8a8ebfa5fc13edea83ab35c298c",
      "event": "document.complete",
      "document_id": "PLSDOC19704278f8c51564ff0c707817",
      "complete_date": 1531228693,
      "original": "https://ps-master.s3.ap-southeast-2.amazonaws.com/1afbd2c2181d32ddcf4324f07509290f.pdf",
      "signed": "https://ps-master.s3.ap-southeast-2.amazonaws.com/1afbd2c2181d32ddcf4324f07509290f.pdf",
      "certificate": "https://ps-master.s3.ap-southeast-2.amazonaws.com/1afbd2c2181d32ddcf4324f07509290f.pdf"
    }
    

    This webhook event is registered when PleaseSign has successfully verified all aspects of the document and placed an encrypted digital certificate, sealing the final copy. The status of the document will have already transitioned to complete before this webhook is sent.

    It is important to remember that the complete_date included in the request body may not match the complete_date of the last recipient that signed the document. A document is not considered complete until is has been certified and sealed with an encrypted digital certificate. Generally this process takes up to 5 seconds from the last recipient completing.

    Included in the request body are links that can be used to download the original document, signed document and certificate of authenticity. These links are active for 72 hours after which they will return a 403. 72 hours is used as this is the maximum amount of time a webhook event can be retried until stopping.

    It is important to remember when manually resending an expired webhook event for this event type, that the links will not be regenerated and will return a 403.

    Request body

    id string Unique event identifier.
    event string "document.complete".
    document_id string The unique identifier for the document that was completed.
    complete_date string The true unix timestamp of when the document was completed.
    original string A 72 hour link that can be used to download the original copy of the document before it was signed by any recipients.
    signed string A 72 hour link that can be used to download the signed and sealed copy of the document.
    certificate string A 72 hour link that can be used to download the certificate of authenticity.

    recipient.sent

    Example request

    {
      "id": "fe6de8a8ebfa5fc13edea83ab35c298c",
      "event": "recipient.sent",
      "document_id": "PLSDOC19704278f8c51564ff0c707817",
      "recipient_id": "52cc002fac06025cddad05de87f75b37",
      "first_name": "John",
      "last_name": "Doe",
      "email": "example@pleasesign.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:

    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.