ConsignO Cloud Basic API documentation

host/api/v1

Introduction

The ConsignO Cloud API enables, within your application, simple and quick integration with the Notarius ConsignO Cloud platform to create great electronic signature experiences for your customers.

Using the ConsignO Cloud API, you can:

  • Fully automate the signature workflow end to end: Your platform creates and launches the signature project (upload document, define zones, signers, 2nd factor, etc.). Email notifications are sent out to obtain the signatures.
  • Automate in part the signature workflow: Your platform creates the project (upload the document, set some properties that you know) and redirect the initiator within the project workspace interface to define zones and/or signers and launch the project.
  • Integrate the signature action directly within your web application: Redirect the signer to a URL to complete the signature step right away. This is called the Embedded signer mode.


The API provides key functionalities such as:

  • Platform and user level authentication
  • Upload of documents in multi-part or base64 encoding
  • Creation and launch of signature projects
  • Definition of signature zones location and size
  • Definition of signer's information (first name, last name, phone number, email address, etc.)
  • Setting the 2nd factor (SMS, call, shared secret)
  • Management of the language of notification (English, French) per signer
  • Support of free text zones
  • Sending out notification to specific contact when project at project completion
  • Set sequential or parallel signatures
  • Control of email notifications
  • Download of signature documents and audit trail
  • Webhooks for event notifications
  • Event for project status

AND MORE!

This page details the basic calls and functionalities. A more detailed API Implementation Guide can be shared by contacting Notarius.


Endpoint & API Version

The endpoint is host/api/v1. The host URL can vary based on the environment assigned to your account. Please make sure to define the complete path.


API access and Authentication

Access to the API is currently restricted to Enterprise subscription only in production. Sandbox account can be requested for lab testing.

API access is done using different set of credentials from the regular user GUI access. Both are typically exclusive. To use the same set of credentials for both, contact Notarius.

Two modes are supported for authentication:

Authenticate as a platform

  • The project initiator is seen as the platform.
  • You log using an authentication key and secret defined for your organization. To define key and secret, access the My Organization menu as an Administrator and go under the API sub-section.
  • The platform name and email address as defined under the API section are used in the notification and audit trail as the project initiator when set in the parameters.

Authenticate as a user behind a platform (loginAs)

  • The project initiator is seen as the user, but login is authorized via a third-party platform with specific credentials.
  • In addition to the platform authentication key and secret, a third-party application password created by the end user must be used. Each user can create a third-party password by accessing the Preferences menu. The end user must define this password within your app.
  • The user name and email address are used in the notification and audit trail as the project initiator. There is also a reference to the platform.
  • To use this mode, platform must be authorized to use to "loginAs" functionality and have permission "ROLE_API_LOGINAS" set. A specific configuration and account is required (contact Notarius).


Document Upload

Document can be uploaded either using the /documents or /worklfows resources.

  • /documents is used to upload document using multi-part encoding.
  • /workflows is used to upload document using base64 encoding.

Only PDF format is currently supported and can be signed using ConsignO Cloud.

If you want to include/attach documents (PDFA/3) with the PDF to be signed, this should be done before uploading the document within ConsignO Cloud.


URL Redirection

To provide the best user experience possible when integrating with a third-party application, the API provides both ways URL redirection mechanism to allow end to end seamless integration between applications.

This is very useful if you want to:

  • Create a signature project (name project, upload document), but redirect the initiator within the project draft creation window so he can define the signers details or the signature zones for example if those parameters are variable and can't be determined in advance. Refer to the editUrl parameter part of the /workflows response.
  • Force, following completion of the previous step, user to go back to your web page after launching the project. Refer to the workflow.returnUrl property in the /workflow.
  • Force, following completion of the signature step in the embedded mode, user to go back to your web page. Refer to the workflow.actions[i].returnUrl property in the /workflow.


Webhook Events

When a webhook is defined at workflow creation, all events normally sent to the workflow owner will be sent to the webhook endpoint as POST requests, with the event details in the request body. The following events will be emitted:

  • workflow.created: A worflow has been created
  • workflow.launched: A worflow has been launched
  • workflow.updated: A worflow has been updated
  • workflow.completed: A workflow has been completed
  • workflow.declined: A workflow has been declined (associated with signature refused)
  • workflow.signature.requested: A signature request has been sent out (available soon in 2.13)
  • workflow.signature.completed: A signature has been completed
  • workflow.signature.declined: A signature has been refused
  • workflow.warnings.expiration: A workflow will expire
  • workflow.expired: A workflow has expired
  • workflow.warnings.deletion: A workflow will be archived/deleted
  • workflow.deleted: A workflow has been archived/deleted
  • workflow.user.deleted: A user has been deleted from the workflow
  • workflow.signer.poke: A reminder has been sent out

Every event contains the following details:

  • The event date (ISO format)
  • A context object containing event related information, like workflowId, signers details, number of signatures left, expiration date, etc.
  • The event name

An hosted service like https://requestinspector.com/ can be used to catch webhooks events and inspect their content.


Workflow Examples

Basic project creation with Remote signers (email notification sent out to signers)

  1. Authenticate ==> POST /auth/login
  2. Upload document ==> POST /documents (optional if document is encoded in base64 and passed using /workflows)
  3. Create and launch workflow ==> POST /workflows
  4. Monitor webhooks ... Email notifications can be received as well by project initiator
  5. Get signed final document ==> POST /workflows/{workflowId}/documents
  6. Get signed final audit ==> POST /workflows/{workflowId}/audit
  7. Archive docs based on your requirements
  8. Delete workflow ==> DELETE /workflows/{workflowId}

Basic project creation with Embedded Signer (Signature directly embedded within your web app, no email notification to signers)

A demo page of the Embedded Signer functionality can be accessed here: https://consignocloud.com/embedded-signer-demo/en/index.html

  1. Authenticate ==> POST /auth/login
  2. Upload document ==> POST /documents (optional if document is encoded in base64 and passed using /workflows)
  3. Create and launch workflow ==> POST /workflows . Include a returnURL to redirect user to your app once signature is completed.
  4. Get signing URL ==> GET /workflows/{workflowId}/links/current
  5. Show signing URL in iFrame or redirection window for user to complete the signature step
  6. Check signature result in return URL: (http://my.return.url/?status=success) or monitor webhook
  7. Get signed final document ==> POST /workflows/{workflowId}/documents
  8. Get signed final audit ==> POST /workflows/{workflowId}/audit
  9. Archive docs based on your requirements
  10. Delete workflow ==> DELETE /workflows/{workflowId}

Basic project creation with Remote signers (email notification sent out to signers) and redirection URL

  1. Authenticate ==> POST /auth/login
  2. Upload document ==> POST /documents (optional if document is encoded in base64 and passed using /workflows)
  3. Create workflow ==> POST /workflows. Set workflow.status to 0 to create the project, but not launch it. Set the workflow.returnUrl accordingly.
  4. Retrieve the editUrl from the response and redirect project initiator to it in your app.
  5. Project initiator can define the signature zones and/or signers if not done and launch the project.
  6. User is sent back to the returnUrl site you have set.
  7. Monitor webhooks ... Email notifications can be received as well by project initiator.
  8. Get signed final document ==> POST /workflows/{workflowId}/documents
  9. Get signed final audit ==> POST /workflows/{workflowId}/audit
  10. Archive docs based on your requirements.
  11. Delete workflow ==> DELETE /workflows/{workflowId}


Resources Details

/auth

This resource and operations allow external platform to login, logout and verify the token validity.

Based on how authentication is done, parameters will vary. Refer to the API access and Authentication section above.

On a successful authentication, a token is returned in the X-Auth-Token response header. The token is a signed JWT token which, when decoded, contains various details about the logged-in user.

The token must be sent in every subsequent request, in the X-Auth-Token header or as a request parameter with name X-Auth-Token. Please refer to each operation details.

The token expires after 30 minutes of inactivity. The integrator must re-authentify if token has expired.

The token MUST be secured when stored locally.

The token contains some mutable fields. When at least one of these fields changes, a new token is returned in the X-Auth-Token response header. The new token MUST be used for subsequent requests, and the previous one destroyed.

post

post

User login using a username, a password and a tenant.

User login using a username, a password and a tenant.

Headers

  • Content-Type: required (string)

    Must be set to application/json

  • X-Client-Id: (string)

    Platform Authentication Key. Must be set only when using the loginAs authentication mode.

  • X-Client-Secret: (string)

    Platform Authentication Secret. Must be set only when using the loginAs authentication mode.

Body

Media type: application/json

Type: object

Properties
  • username: required (string)

    Platform authentication key or the user's username (email) based on authentication mode.

  • password: required (string)

    Platform authentication secret, user's third party password or user's password based on the authentication mode.

  • tenantId: required (string)

    The tenant name. This corresponds to your subdomain, if any. If authentication is on the main tenant, the value must be cloud.

Example:

{
  "username": "myusername@dot.org",
  "password": "password123",
  "tenantId": "cloud"
}

HTTP status code 200

Successful authentication

Headers

  • X-Auth-Token: required (string)

    The auth token to use in authentified requests

HTTP status code 401

Wrong credentials

post

post

User logout

User logout

Headers

  • X-Auth-Token: required (string)

    Auth token

HTTP status code 200

Successful logout

head

head

Method to verify if X-Auth-Token is still valid

/documents

This resource and operations allow external platform to upload document to be used in a given workflow.

Should be used to upload document in multi-part. If the platform supports base64 encoding, document should be uploaded using the resource /workflows.

Only PDF document can be uploaded. The file content must NOT be encoded in the request.

Document upload is required before the workflow initialization.

Document can be assigned to a single workflow. If it should be used in different workflows, it must be uploaded multiple times.

A signing project can consist of one or multiple documents. Each document must be uploaded separately as IDs are returned and must be referred in the /workflows operations.

Each document can have zero, one or multiple signers (to be defined using the /workflows resource). A signing project must have at least 1 signer defined in order to be launched.

Each document can be converted to the PDF/A standard if required at upload time.

When using this resource, the documentId property must be saved in the response and used in subsequent /workflows call.

post

post

Document upload

Document upload

Headers

  • X-Auth-Token: required (string)

    Auth token

Body

Media type: multipart/form-data

Type: object

Properties
  • uploadData: required (object)

    Information regarding the file upload.

    • pdfaPolicy: required (integer)

      PDF/A policy to apply to the uploaded document. 0 = None, 1 = Preferred, 2 = Mandatory.

    Example:

    {"pdfaPolicy":1}
  • file: required (file)

    The actual file to upload. Warning: The file content must NOT be encoded (base64 or another encoding)

    Example:

    Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z

HTTP status code 201

Body

Media type: application/json

Type: object

Properties
  • metadata: required (object)

    The uploaded file metadata.

    • originalDocumentId: The original document identifier, as uploaded by the client.
    • documentId: The current document identifier.

    Example:

    {
    "msg":"ok",
    "response":
    {
        "metadata":
        {
          "originalDocumentId": "5ac7b5b1ea2d441bdca0f661",
          "documentId": "5ac7b5aaea2d441bdca0f62f"
        }
    }
}

HTTP status code 400

Cannot convert to PDF/A

/workflows

This resource is the main one to be used to set the project various properties and retrieve information (documents, audit trail, URL, state). Here are few key concepts to understand first.


Signature Modes

Two modes are currently supported: remote signing or embedded signing. The mode is set using the workflow.actions[i].mode property.


Remote Signing

Remote Signing is the normal mode of signing where the signature process is triggered by an email sent to the signer. It is also used to fill Text Zone.

Following completion of the 2nd authentication method (sms,call,secret), the signer can complete its step and workflow will continue (either end or move to next signer).

To add a remote signer, the following parameters should be set:

  • workflow.actions[i].mode: must have value remote.


Embedded Signing

Embedded Signing allows integration of the signature process into an existing platform, either through an iframe or a redirect. In this mode, the external platform is responsible to authenticate the signer, as the email+link verification step is skipped.

Embedded Signing is not available on the main tenant. An organization must have its own tenant and configured accordingly to enable embedded signing.

An embedded signer cannot be defined in a parallel sequence. Secret amr cannot be used with embedded signer.

To add an embedded signer, the following parameters should be set:

  • workflow.actions[i].mode: must have value embedded.
  • workflow.actions[i].returnUrl: a callback URL where signature result will be sent.
  • workflow.actions[i].signer.clientUserId: Optional signer identifier which will be added to the signature reason and audit trail.

Once the workflow has been launched, the signing url can be retrieved and redirected to or used as an iframe source.

After signature, the page will be redirected to the returnUrl URL. The status will be appended as a query parameter (?status=) with the following values possible: success, failure, expired.


Signature Zones

A zone is defined within the workflow.documents[i] property. It can host a signature or a text field. Each zone is associated with a document (either by embedding the document directly or using the documentId reference)

In case of remote signers, it is not mandatory to define signature zones to create a project. It is mandatory to launch it however. If zones are not known in advance, project initiator should be redirected to project workspace to complete this step (see Redirection URL).

There are two ways to define a signature zone: either by seeting the zone coordinates or by defining anchors where to apply the zone.


Using x,y coordinate:

To define coordinate, use the array fields (workflow.documents[i].fields[j]) to set its position (x,y,width,height, page) as well as a reference to a given signer.


How to set the coordinates of the zone?

ConsignO Cloud uses the term "units" as a unit length. 1 unit = 1 / 72". Origin is in the top left corner of the document.

To define the location of the zone:

  • Convert your PDF document size in units. Ex.: A 8.5" x 11" (letter format) will be 612 x 792 units.

  • Based on the location of the zone, derive the right coordinates.

  • By default, size of the signature zone is set to width = 165 and height = 37.

  • To use non-default and variable value, manual configuration is needed in your profile (contact Notarius).


Using anchors as a placeholder:

An anchor is a reference within the document that will indicate where to apply a signature. It is a text tag, present within the document, that typically would be of the same color of the document background (white on white). This text can't be seen by a human eye, but can be detected by the platform and be used as a placeholder to apply the signature.

To define anchors, use the array fields (workflow.documents[i].anchors[j]).

If a tag has many occurrences within a document, it will be used as often as found, unless page restrictions are set.

Tag must be different from any word within the document. It is recommended to use square or curly brackets to make it unique.


Signer Details

Signer details are defined within the workflow.actions[i].signer property.

This signer parameter is used to set the signer information (firstName, lastName, email, etc.) including which authentication methods should be used and language for communication.

A signer is either one of the following three types: esig (for electronic signature), certifio (for signing using Certifio certificate) or freezone (for text zone only).

A given signer is associated to a given zone by defining a common random numerical value to the workflow.documents[i].fields[j].assignedTo parameter and to the workflow.actions[i].signer.ref parameter.

In case of remote signers, it is not mandatory to define signers to create a project. It is mandatory to launch it however. If signers are not known in advance, project initiator should be redirected to project workspace to complete this step (refer to Redirection URL section).

If signer is not know, properties workflow.actions[i].signers[j].role should be defined as well as workflow.actions[i].signers[j].placeHolder


Authentication Method Reference (AMR)

Four AMR are currently supported: link, sms, call or secret.

Link is always needed as it refers to the email being sent with URL to remote signer or the returnUrl in case of embedded signer.

For SMS and Call, the phone number assigned to the signer or contact will be used to share the code to be entered.

For AMR Secret, you must define properties secretQuestion, secretAnwser and isSecretAnswerChanged. Secret is not supported in Embedded Signing mode.

By default, two factors must be defined. Upon request, it is possible to deactivate the second one (Contact Notarius). Supported AMR can be set at the organisation level.


Signature Sequence

If there are multiple signers for a given workflow, it is possible to allow signatures to happen in parallel or to force all or some of them to happen in sequence.

Parallel signers can be grouped together using the workflow.actions[i].step . All signers sharing same step will be allowed to sign in parallel.

If omitted, signers will be requested to complete their action per the defined order within the workflow.

If two or more steps are defined within a workflow, the steps will be done in sequence. Signers with same step will sign in parallel.


Redirection URL

  • Use editUrl parameter part of the /workflows response to redirect user to the project creation workspace.
  • Set workflow.returnUrl property to define return URL once previous step is completed.

  • Status is appended in the returnUrl, for example: https://my.return.url/?status=success. The status can cover to workflow or the signature, if the project initiator was set as a signer.

    Possible workflow status:

    • WORKFLOW_UPDATED
    • WORKFLOW_LAUNCHED
    • WORKFLOW_CANCELED
    • SIGNATURE_SUCCESS
    • SIGNATURE_CANCELLED
    • SIGNATURE_DECLINE
  • Set workflow.actions[i].returnUrl property to define return URL once signature is completed in Embedded signer mode

  • Status is appended in the returnUrl, for example: https://my.return.url/?status=success.

    Possible signature status:

    • success
    • decline


Notifications

Person to Notify

When launching a project, it is possible to define a person to be notified at project completion. This person will receive a link to download the final version of the documentation.

This can be set using the workflow.notifications[i]. property. Authentication factor and associated parameters must be defined when applicable based on the tenant.


Email notification to project initiator

Email notification to project initiator can be enable or disable by using the workflow.workflowOwnerEmailsEnabled property to either true or false.

When no webhook is set, it is set to true by default. When webhook is set, it is set to false by default.

This email refers to email sent to owner at project completion and when a given signature step is completed.

post

post

Creates a new workflow. A new workflow is created from an uploaded document. A workflow defines various actions to be done on the document.

Creates a new workflow. A new workflow is created from an uploaded document. A workflow defines various actions to be done on the document.

Headers

  • Content-Type: required (string)

    Must be set to application/json

  • X-Auth-Token: required (string)

    Auth token

Body

Media type: application/json

Type: object

Properties
  • name: required (string)

    The workflow name.

  • expiresOn: required (integer)

    The workflow expiration date (epoch) in milliseconds or "YYYY-MM-DD".

  • pdfaPolicy: (integer)

    Needed when uploading document within /workflows. PDF/A policy to apply to the uploaded document. 0 = None, 1 = Preferred, 2 = Mandatory.

  • documents: required (array of Document)

    Items: Document

    • documentId: (string)

      Reference to the document id obtained in the response of the /documents resource. Not applicable when document is uploaded in /workflows.

    • name: (string)

      The name of the pdf uploaded in base64. Required only when document is uploaded with /workflows

    • data: (string)

      The file data to be used, encoded in base64. Required only when document is uploaded with /workflows

    • fields: (array of FormField)

      Form fields to set on the document. Either Field or Anchors must be used

      Items: FormField

      • x: required (number)

        X coordinate

      • y: required (number)

        Y coordinate

      • height: (number)

        Field height, in units. Set to 165 by default. To use non default value, manual configuration is needed in your profile.

      • width: (number)

        Field width, in units. set to 37 by default. To use non default value, manual configuration is needed in your profile.

      • page: required (string)

        Page on which to apply the field (page:"2"). Support ranges, wilcard and word as well such as 1-4 ; 1,4 ; 1,4-6 ; * ; first ; last.

      • assignedTo: required (string)

        Associates a field to a signer, numerical only (1234). Equals the WorkflowAction.ref value. Numerical only.

    • anchors: (array of FormAnchor)

      Form anchor to set on the document. Either Field or Anchors must be used

      Items: FormAnchor

      • tag: required (string)

        Tag to be used to assign the signature.

      • assignedTo: required (string)

        Associates a tag to a signer, numerical only (1234). Equals the WorkflowAction.ref value.

      • xOffset: (integer)

        Offset from the bottom left corner of the tag

      • yOffset: (integer)

        Offset from the bottom left corner of the tag

      • height: (number)

        Field height, in units. Set to 165 by default. To use non default value, manual configuration is needed in your profile.

      • width: (number)

        Field width, in units. set to 37 by default. To use non default value, manual configuration is needed in your profile.

      • page: (string)

        Page on which to apply the field only. Won't search other pages. Support ranges, wilcard and word as well such as 1-4 ; 1,4 ; 1,4-6 ; * ; first ; last.

      • SkipIfNotFound: (boolean)

        true or false. On false (by default), will generate an exception if tag is not found.

  • status: required (integer)

    Workflow status. 0 to create.Must be 1 to create and launch.

  • actions: required (array of WorkflowAction)

    Set of actions to perform

    Items: WorkflowAction

    • mode: (string)

      The action mode. Either remote or embedded. If omitted, value is remote.

    • returnUrl: (string)

      In case of embedded signing only, the page will be redirected to this url upon signature completion.

    • zoneLabel: (string)

      Label to set on the signature field.

    • step: (integer)

      All signers sharing same step will be allowed to sign at the same time.

    • ref: required (string)

      Random value, numerical only (1234). Must be unique to a workflow and is used to associate an action to a form field.

    • signer: required (object)

      Signer which will perform this action

      • type: (string)

        Signer type. Either esig or certifio or freezone. This will determine if signer will use an e-signature (esign), a digital signature (certifio) or if this is a Text Field (freezone). For notification, it must be set to esign.

      • firstName: (string)
      • lastName: (string)
      • email: (string)
      • phone: (string)

        Signer's phone/mobile. Ex:+14445556666.

      • secretQuestion: (string)

        Question to be shown for signer authentication. Must be defined when AMR set to secret.

      • secretAnswer: (string)

        Answer to be entered for signer authentication. Must be defined when AMR set to secret.

      • isSecretAnswerChanged: (boolean)

        Must be set to true when AMR secret is used.

      • amr: (array of )

        Signer's auth methods. Either "link","sms" or "secret" based on the need. "Link" is mandatory as the first one for remote signer.

      • subjectDN: (string)

        Needed with type= certifio to match proper certificate.

      • lang: (string)

        Preferred language. Either fr or en. Default is en.

      • clientUserId: (string)

        Optional signatory identifier which will be added to the signature reason and audit trail. Valid for embedded signer only.

      • role: (string)

        Optional Role text to be shown in the signature zone (Signer Company Z) when Signer is not known in advance.

      • placeHolder: (boolean)

        Must be set to true if signer is unknown.

  • notifications: (array of NotificationAction)

    Set of notifications to be sent to specific contacts at project completion

    Items: NotificationAction

    • contact: required (object)

      Person to be notified

      • firstName: required (string)
      • lastName: required (string)
      • email: required (string)
      • phone: (string)

        Signer's phone/mobile. Ex:+14445556666.

      • secretQuestion: (string)

        Question to be shown for signer authentication. Must be defined when AMR set to secret.

      • secretAnswer: (string)

        Answer to be entered for signer authentication. Must be defined when AMR set to secret.

      • isSecretAnswerChanged: (boolean)

        Must be set to true when AMR secret is used.

      • amr: required (array of )

        Signer's auth methods. Either "link","sms" or "secret" based on the need. "Link" is mandatory as the first one.

      • lang: required (string)

        Preferred language. Either fr or en.

  • webhooks: (array of Webhook)

    Items: Webhook

    • url: required (string)

      The callback endpoint.

    • insecure: (boolean)

      Defaults to false (secure). When true, http and invalid https are tolerated.

    Example:

    {
  "url": "https://client.domain.com/webhooks/consume"
}

Examples:

Basic_Remote_Signer_+_Notify_Contact_+_anchors:
Workflow with one remote signer, one contact to be notified at project completion and a webhook to receive callbacks. Document uploaded previously with /documents

{
  "name": "Basic Remote Signer",
  "expiresOn": "2018-12-31",
  "documents": [
    {
    "documentId": "5a8ae7f71475eb19bcdb867f",
    "anchors":[
        {
          "tag": "/signature1/",
          "assignedTo": 1,
          "xOffset": 0,
          "yOffset": 5,
          "skipIfNotFound": "false",
      ]
    }
  ],
  "status": 1,
  "actions": [
    {
      "mode": "remote",
      "ref": "1",
      "signer":
        {
        "type": "esig",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@domain.com",
        "phone": "+15552345678",
        "amr": [
          "link",
          "sms"
          ],
        "lang": "en"
        }
    }
  ],
  "notifications": [
    {
      "contact": {
        "firstName": "Valid",
        "lastName": "Notification",
        "email": "notification@domain.com",
        "phone": "+155551234569",
        "amr": [
          "link",
          "sms"
          ],
        "lang": "en"
        }
    }
  ],
  "webhooks": [
    {
    "url": "https://requestinspector.com/inspect/01cd0hsfdjhfkhfsjhfhewfkhew"
    }
  ]
}

Embedded_Signer_+_ReturnUrl_+_Coordinates:
Workflow with one embedded signer, returnUrl, clientUserId & webhook to receive callbacks. (2FA disable, if tenant configured accordingly)

{
  "name": "Embedded_Signer",
  "expiresOn": "2018-12-31",
  "documents": [
    {
    "documentId": "5a8ae7f71475eb19bcdb867f",
    "fields":[
        {
          "x": 83.084480285645,
          "width": 0,
          "y": 635.568359375,
          "page": "1",
          "assignedTo": "1",
          "height": 0
        }
      ]
    }
  ],
  "status": 1,
  "actions": [
    {
      "mode": "embedded",
      "returnUrl": "https://platformxyz.com",
      "ref": "1",
      "signer":
        {
          "type": "esig",
          "firstName": "John",
          "lastName": "Doe",
          "clientUserId": "ID:104055",
          "email": "john.doe@biz.com",
          "phone": "+15553456789",
          "amr": [
            "link"
            ],
          "lang": "en"
        }
    }
  ],
  "webhooks": [
    {
    "url": "https://requestb.in/17d9p691"
    }
  ]
}

Remote_Signer_+_Notification_Initiator_+_Document_Embedded_Base64_Secret_Call_AMR_+_anchors:
Workflow with two remote signers, shared secret and call as AMR, notification sent to project initiator & document embedded in base64 within the /worklflow and anchors for the signature zone.

{
  "name": "Remote Signers V2",
  "expiresOn": "2018-12-31",
  "documents": [
    {
    "name": "document.pdf",
    "data": "DataInBase64withTags",
    "anchors":[
        {
          "tag": "/signature1/",
          "assignedTo": 1,
          "xOffset": 0,
          "yOffset": 5,
          "skipIfNotFound": "false",
        },
        {
          "tag": "/signature2/",
          "assignedTo": 2,
          "xOffset": 0,
          "yOffset": 5,
          "skipIfNotFound": "false",
        },
      ]
    }
  ],
  "status": 1,
  "workflowOwnerEmailsEnabled": true,
  "actions": [
    {
      "mode": "remote",
      "ref": "1",
      "signer":
        {
        "type": "esig",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@domain.com",
        "phone": "+15552345678",
        "amr": [
          "link",
          "call"
          ],
        "lang": "en"
        }
    },
    {
      "mode": "remote",
      "status": 0,
      "ref": "2",
      "signer":
        {
        "type": "esig",
        "firstName": "Bill",
        "lastName": "Doe",
        "email": "bill.doe@domain.com",
        "phone": "+15553256981",
        "secretQuestion": "meal",
        "secretANswer": "lasagna",
        "isSecretAnswerChanged: true",
        "amr": [
          "link",
          "secret"
          ],
        "lang": "en"
        }
    },
  ],
  "notifications": [
    {
      "contact": {
        "firstName": "Valid",
        "lastName": "Notification",
        "email": "notification@domain.com",
        "phone": "+155551234569",
        "amr": [
          "link",
          "sms"
          ],
        "lang": "en"
        }
    }
  ],
  "webhooks": [
    {
    "url": "https://requestinspector.com/inspect/01cd0hsfdjhfkhfsjhfhewfkhew"
    }
  ]
}

No_Zone_+_No_Signer_+_returnUrl:
Creation and upload of document, no launch (Status = 0) and return URL from workspace. Use editUrl from response to redirect project initiator in the project creation workspace.

{
  "name": "No Zone + no signers",
  "expiresOn": "2018-12-30",
  "returnUrl": "http://www.myplatform.com/returnUrl",
  "pdfaPolicy" : 1,
  "documents": [
    {
    "name": "document.pdf",
    "data": "DataInBase64"
    }
  ],
  "status":0,
  "actions": [
    ],
  "webhooks": [
  {
    "url": "https://requestinspector.com/inspect/01cd0hssa21rzadr6chr8q4p7n"
  }
  ]
}

Set_Zone_+_No_Signer_+_Assign_Role_Zone:
Creation and upload of document, set zone, no launch (Status =0) and return URL from workspace. Define Role for signer Use editUrl from response to redirect project initiator in the project creation workspace.

{
"name": "Zone + no signers",
"expiresOn": "2018-12-30",
"returnUrl": "http://www.myplatform.com/returnUrl",
"pdfaPolicy" : 1,
"documents": [
  {
  "name": "document.pdf",
  "data": "DataInBase64",
  "fields":[
    {
      "x": 83,
      "y": 635,
      "page": "1",
      "assignedTo": "1"
    }
   ]
  }
],
"status":0,
"actions": [
  {
    "mode": "remote",
    "ref": 1,
    "signer":
      {
        "role" : "Acheteur 1",
        "placeHolder": true
      }
    }
  ],
"webhooks": [
  {
  "url": "https://requestinspector.com/inspect/01cd0hssa21rzadr6chr8q4p7n"
  }
  ]
}

Parallel_Signature_Sequence:
Multiple signers in two parallel sequences (step:0 and step:1).

{
  "name": "SingleDoc-MultiSign_Parallel",
  "expiresOn": "2018-12-31",
  "documents": [
    {
    "documentId": "5a8ae7f71475eb19bcdb867f",
    "fields":[
        {
          "x":83,
          "y": 635,
          "page": "1",
          "assignedTo": "1"
        },
        {
          "x": 343,
          "y": 635,
          "page": "1",
          "assignedTo": "2"
        },
        {
          "x": 83,
          "y": 335,
          "page": "1",
          "assignedTo": "3"
        },
        {
          "x": 343,
          "y": 335,
          "page": "1",
          "assignedTo": "4"
        }
      ]
    }
  ],
  "status": 1,
  "actions": [
    {
      "mode": "remote",
      "ref": "1",
      "step": 0,
      "signer":
        {
          "type": "esig",
          "firstName": "Signer",
          "lastName": "One",
          "email": "signer1@domain.com",
          "phone": "+14445556666",
          "amr": [
            "link",
            "sms"
            ],
          "lang": "en"
        }
    },
    {
      "mode": "remote",
      "ref": "2",
      "step": 0,
      "signer":
        {
          "type": "esig",
          "firstName": "Signer",
          "lastName": "Two",
          "email": "Signer2@domain.com",
          "phone": "+15149990123",
          "amr": [
            "link",
            "sms"
            ],
          "lang": "fr"
        }
    },
    {
      "mode": "remote",
      "ref": "3",
      "step": 1,
      "signer":
        {
          "type": "esig",
          "firstName": "Signer",
          "lastName": "Three",
          "email": "Signer3@domain.com",
          "phone": "+14445555555",
          "amr": [
            "link",
            "sms"
            ],
          "lang": "en"
        }
    },
    {
      "mode": "remote",
      "ref": "4",
      "step": 1,
      "signer":
        {
          "type": "esig",
          "firstName": "Signer",
          "lastName": "Four",
          "email": "signer4@domain.com",
          "phone": "+14445557777",
          "amr": [
            "link",
            "sms"
            ],
          "lang": "en"
        }
    }
  ],
  "webhooks": [
      {
    "url": "https://requestb.in/17d9p691"
      }
    ]
  }

TextField_Zone:
Workflow with 2 zones, one for text field and one for signer with document encoded base64

{
  "name": "TextField_Project",
  "expiresOn": "2018-12-31",
  "pdfaPolicy" : 1,
  "documents": [
    {
      "name": "pdf_tosign.pdf",
      "data": "{{database64}}",
      "fields":[
        {
        "x":83,
        "width": 0,
        "y": 635,
        "page": "1",
        "assignedTo": "1",
        "height": 0
        },
        {
        "x": 343,
        "width": 0,
        "y": 635,
        "page": "1",
        "assignedTo": "2",
        "height": 0
        }
      ]
    }
  ],
  "status": 1,
  "actions": [
    {
      "mode": "remote",
      "ref": "1",
      "zoneLabel": "Reason",
      "signer": {
          "type": "freezone",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@domain.com",
          "phone": "+15141234567",
          "amr": [
            "link",
            "sms"
                ],
          "lang": "en"
        }
    },
    {
      "mode": "remote",
      "ref": "2",
      "signer": {
        "type": "esig",
        "firstName": "Bill",
        "lastName": "Doe",
        "email": "bill.doe@domain.com",
        "phone": "+15142345678",
        "amr": [
          "link",
          "sms"
          ],
          "lang": "fr"
        }
    }
  ],
  "webhooks": [
      {
        "url": "https://requestb.in/17d9p691"
      }
  ]
}

MultiDocs_Example:
Multiple Documents with embedded and remote signers

{
  "name": "Multidoc-Multisigners",
  "expiresOn": 1549680906000,
  "documents": [
    {
      "documentId": "5a8b26e31475eb19bcdb8b11",
      "fields":[
          {
            "x":83,
            "width": 0,
            "y": 635,
            "page": "1",
            "assignedTo": "1",
            "height": 0
          },
          {
            "x": 343,
            "width": 0,
            "y": 635,
            "page": "1",
            "assignedTo": "2",
            "height": 0
          }
        ]
    },
    {
      "documentId": "5a8b272a1475eb19bcdb8b1d",
      "fields":[
          {
            "x":83,
            "width": 0,
            "y": 635,
            "page": "1",
            "assignedTo": "2",
            "height": 0
          },
          {
            "x": 343,
            "width": 0,
            "y": 635,
            "page": "1",
            "assignedTo": "3",
            "height": 0
          }
      ]
  }
  ],
  "status": 1,
  "actions": [
    {
      "mode": "embedded",
      "returnUrl": "https://requestb.in/qbc519qb",
      "ref": "1",
      "signer":
        {
          "type": "esig",
          "firstName": "John",
          "lastName": "Doe",
          "clientUserId": "ID:1028336",
          "email": "john.doe@biz.com",
          "phone": "+14445556666",
          "amr": [
            "link",
            "sms"
            ],
          "lang": "en"
        }
    },
    {
      "mode": "remote",
      "ref": "2",
      "signer":
        {
          "type": "esig",
          "firstName": "Bill",
          "lastName": "Doe",
          "email": "bill.doe@domain.com",
          "phone": "+15147778888",
          "amr": [
            "link",
            "sms"
            ],
          "lang": "fr"
        }
   },
   {
      "mode": "remote",
      "ref": "3",
      "signer":
        {
          "type": "esig",
          "firstName": "Jack",
          "lastName": "Doe",
          "email": "Jack.Doe@domain.com",
          "phone": "+15149990000",
          "amr": [
            "link",
            "call"
            ],
          "lang": "fr"
        }
   }
  ],
  "webhooks": [
    {
      "url": "https://requestb.in/17d9p691"
    }
    ]
}

MultiDocs_Embedded_Base64:
Multiple Documents with file included in base64.

{
    "name": "multidoc_multisign_base64",
    "expiresOn": "2018-12-31",
    "pdfaPolicy" : 1,
    "documents": [
  	{
  	 "name": "pdf_tosign1.pdf",
     "data": "{{database64}}",
  	  "fields":[
  	      {
  	        "x":83,
  	        "width": 0,
  	        "y": 635,
  	        "page": "1",
  	        "assignedTo": "1",
  	        "height": 0
  	      },
        	  {
  	        "x": 343,
  	        "width": 0,
  	        "y": 635,
  	        "page": "1",
  	        "assignedTo": "2",
  	        "height": 0
  	      }
  	    ]
  	},
  	{
  	 "name": "pdf_tosign2.pdf",
     "data": "{{data_base64}}",
  	 "fields":[
  	      {
  	        "x":83,
  	        "width": 0,
  	        "y": 635,
  	        "page": "1",
  	        "assignedTo": "3",
  	        "height": 0
  	      },
        	  {
  	        "x": 343,
  	        "width": 0,
  	        "y": 635,
  	        "page": "1",
  	        "assignedTo": "4",
  	        "height": 0
  	      }
  	    ]
  	}
    ],
    "status": 1,
    "actions": [
      {
        "mode": "embedded",
        "returnUrl": "https://requestb.in/qbc519qb",
        "ref": "1",
        "signer": {
          "type": "esig",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@domain.com",
          "clientUserId": "my_client_user_id",
          "phone": "+14445556666",
          "amr": [
            "link",
            "sms"
          ],
          "lang": "en"
        }
      },
  	 {
        "mode": "remote",
        "ref": "2",
        "signer": {
          "type": "esig",
          "firstName": "Bill",
          "lastName": "Doe",
          "email": "bill.doe@domain.com",
          "phone": "+15141234569",
          "amr": [
            "link",
            "sms"
          ],
          "lang": "fr"
        }
  	 },
  	 {
        "mode": "remote",
        "ref": "3",
        "signer": {
          "type": "esig",
          "firstName": "Jane",
          "lastName": "Doe",
          "email": "jane.doe@domain.com",
          "phone": "+15418385698",
          "amr": [
            "link",
            "sms"
          ],
          "lang": "fr"
        }
  	 },
  	 {
        "mode": "remote",
        "ref": "4",
        "signer": {
          "type": "esig",
          "firstName": "Tom",
          "lastName": "Pouce",
          "email": "tom.pouce@domain.com",
          "phone": "+12356587412",
          "amr": [
            "link",
            "sms"
          ],
          "lang": "fr"
        }
  	 }
    ],
    "webhooks": [
  	 {
  		"url": "https://requestb.in/17d9p691"
  	 }
    ]
  }

HTTP status code 201

Body

Media type: application/json

Type: object

Properties
  • response: required (object)

    The created workflow

    • id: required (string)

      Workflow id.

    • name: required (string)

      Workflow name

    • status: required (integer)

      Workflow status

      • 0: Created but not launched
      • 1: launched and in progress
      • 2: Completed
      • 3: Expired
      • 4: Created from Template (not launched)
      • 5: Declined
    • documents: required (array of Document)

      Set of documents contained in this workflow.

      Items: Document

      • documentId: (string)

        Reference to the document id obtained in the response of the /documents resource. Not applicable when document is uploaded in /workflows.

      • name: (string)

        The name of the pdf uploaded in base64. Required only when document is uploaded with /workflows

      • data: (string)

        The file data to be used, encoded in base64. Required only when document is uploaded with /workflows

      • fields: (array of FormField)

        Form fields to set on the document. Either Field or Anchors must be used

        Items: FormField

        • x: required (number)

          X coordinate

        • y: required (number)

          Y coordinate

        • height: (number)

          Field height, in units. Set to 165 by default. To use non default value, manual configuration is needed in your profile.

        • width: (number)

          Field width, in units. set to 37 by default. To use non default value, manual configuration is needed in your profile.

        • page: required (string)

          Page on which to apply the field (page:"2"). Support ranges, wilcard and word as well such as 1-4 ; 1,4 ; 1,4-6 ; * ; first ; last.

        • assignedTo: required (string)

          Associates a field to a signer, numerical only (1234). Equals the WorkflowAction.ref value. Numerical only.

      • anchors: (array of FormAnchor)

        Form anchor to set on the document. Either Field or Anchors must be used

        Items: FormAnchor

        • tag: required (string)

          Tag to be used to assign the signature.

        • assignedTo: required (string)

          Associates a tag to a signer, numerical only (1234). Equals the WorkflowAction.ref value.

        • xOffset: (integer)

          Offset from the bottom left corner of the tag

        • yOffset: (integer)

          Offset from the bottom left corner of the tag

        • height: (number)

          Field height, in units. Set to 165 by default. To use non default value, manual configuration is needed in your profile.

        • width: (number)

          Field width, in units. set to 37 by default. To use non default value, manual configuration is needed in your profile.

        • page: (string)

          Page on which to apply the field only. Won't search other pages. Support ranges, wilcard and word as well such as 1-4 ; 1,4 ; 1,4-6 ; * ; first ; last.

        • SkipIfNotFound: (boolean)

          true or false. On false (by default), will generate an exception if tag is not found.

    • totalActions: required (integer)

      Total number of actions

    • remainingActions: required (integer)

      Total number of remaining actions

    • createdBy: required (string)

      Creator id

    • createdOn: required (string)

      Creation date

    • modifiedBy: required (string)

      Modifier id

    • modifiedOn: required (string)

      Modification date

    • workflowOwnerEmailsEnabled: required (boolean)

      true or false based on notification scheme.

    • returnUrl: required (string)

      returnUrl associated with teh project

    • editUrl: required (string)

      URL associated to the project edition workspace

    • expiresOn: required (string)

      Expiration date

    Example:

    {
  "id":"5833118bb19ab41d94298008",
  "name":"My workflow",
  "status":1,
  "documents": [
    {
      "documentId":"5833115fb19ab41d94297ff9",
      "fields":[
        {
          "x": 83,
          "width": 0,
          "y": 635,
          "page": "1",
          "assignedTo": "1",
          "height": 0
        }
      ]
    }
  ],
  "totalActions":1,
  "remainingActions":1,
  "createdBy":"5818f176d586662d58615920",
  "createdOn":"2018-09-06T14:59:43.233Z",
  "modifiedBy":"5818f176d586662d58615920",
  "workflowOwnerEmailsEnabled": false,
  "returnUrl": "https://myplatform.com",
  "editUrl": "/#/workflow/5b9140df683e6e23b058bc55/edit",
  "modifiedOn":"2018-09-06T14:59:43.287Z",
  "expiresOn":"2018-12-31T00:00:00.000Z"
}

get delete

get

Retrieves a specific workflow

delete

Deletes a specific workflow

Retrieves a specific workflow

URI Parameters

  • workflowId: required (string)

Headers

  • X-Auth-Token: required (string)

    Auth token

HTTP status code 200

Body

Media type: application/json

Type: object

Example:

{
  "msg": "ok",
  "code": null,
  "parameters": {},
  "response": {
  "id": "5b916d40683e6e23b058c045",
  "version": 2,
  "name": "ProjectName",
  "status": 1,
  "documents": [
    {
    "documentId": "5b916d38683e6e23b058c03c",
    "name": null,
    "data": null,
    "originalDocumentId": "5b916d40683e6e23b058c03e",
    "fields": []
    }
  ],
  "originalDocumentId": null,
  "documentId": null,
  "totalActions": 1,
  "remainingActions": 1,
  "createdBy": "5ad68d6b355dc917a0fad689",
  "assignTo": "5ad68d6b355dc917a0fad689",
  "createdOn": "2018-09-06T18:09:04.518Z",
  "createdInVersion": "2.10.0",
  "modifiedBy": "5ad68d6b355dc917a0fad689",
  "modifiedOn": "2018-09-06T18:09:04.659Z",
  "archivedOn": null,
  "expiresOn": "2018-12-30T00:00:00.000Z",
  "auditTrailDocumentId": null,
  "reminderBeforeExpirationSent": false,
  "acls": {},
  "webhooks": [
  {
  "url": "https://requestinspector.com/inspect/01cd0hssdedaesfwrfwefewfwn",
  "insecure": false
}
],
"workflowOwnerEmailsEnabled": false,
"parallelActions": false,
"finalizedInVersion": null,
"groupId": null,
"signatureInProgress": false,
"returnUrl": null,
"editUrl": null,
"pdfaPolicy": null,
"actions": [
{
"id": "5b916d38683e6e23b058c03b",
"step": 0,
"type": null,
"signer": {
    "type": "esig",
    "email": "john.doe@domain.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "155552365689",
    "phoneExt": null,
    "amr": [
      "link",
      "sms"
      ],
    "lang": "en",
    "fields": null,
    "subjectDN": null,
    "productName": null,
    "productNames": null,
    "productType": null,
    "secretQuestion": null,
    "isSecretAnswerChanged": null,
    "originalSecretAnswer": null,
    "secretAnswer": null,
    "tenantId": null,
    "oauthProvider": null,
    "from": null,
    "clientUserId": "ID:104055",
    "contactOwner": "USER",
    "contactOwnerId": null,
    "role": null,
    "contactId": null,
    "placeHolder": false,
    "iv": "basic"
    },
    "status": "STARTED",
    "statusDate": 1536257344733,
    "ref": 1,
    "errorState": null,
    "errorReason": null,
    "errorDate": null,
    "zoneLabel": null,
    "zoneContent": null,
    "returnUrl": "https://google.com",
    "mode": "embedded",
    "declineReason": {}
  }
  ],
  "notifications": null,
  "statusDate": 1536257344659,
  "toSignByOwner": null,
  "ownerFirstName": "Bill",
  "ownerLastName": "Boe",
  "ownerEmail": "bill.boe@domain.com",
  "organizationId": "5a1edf448c39df1d2a596e70",
  "identificationText": "Bill Boe",
  "groupName": null
  }
}

Deletes a specific workflow

URI Parameters

  • workflowId: required (string)

Headers

  • X-Auth-Token: required (string)

    Auth token

HTTP status code 204

Workflow deleted. No content available

post

post

Downloads document(s). WARNING the auth token must be passed as a request parameter for this call.

Downloads document(s). WARNING the auth token must be passed as a request parameter for this call.

URI Parameters

  • workflowId: required (string)

Body

Media type: application/x-www-form-urlencoded

Type: object

Properties
  • X-Auth-Token: required (string)

    Auth token

HTTP status code 200

Headers

  • Content-Type: required (string)

    Either application/pdf (if single document) or application/zip (if multi documents)

post

post

Downloads audit trail report. Workflow must be completed. WARNING the auth token must be passed as a request parameter for this call.

Downloads audit trail report. Workflow must be completed. WARNING the auth token must be passed as a request parameter for this call.

URI Parameters

  • workflowId: required (string)

Body

Media type: application/x-www-form-urlencoded

Type: object

Properties
  • X-Auth-Token: required (string)

    Auth token

HTTP status code 200

get

get

Returns the current signing URL. Only possible if action is in mode embedded and caller is owner of workflow.

Returns the current signing URL. Only possible if action is in mode embedded and caller is owner of workflow.

URI Parameters

  • workflowId: required (string)

Headers

  • Content-Type: required (string)

    Must be set to application/json

  • X-Auth-Token: required (string)

    Auth token

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • response: required (array of SigningUrl)

    Items: SigningUrl

    • url: required (string)

      The url which points to the documents to be signed. This url can be used as an iframe source or a redirect when in mode embedded.

    • actionRef: required (string)

      Reference to an action

    • expiresOn: required (string)

      When this link will expire .