OpenText Core Signature API

Number of APIs: 40

Core Signature Service OCP Developer Guide

Core Signature APIs are designed to accept requests made with OAuth 2.0 access tokens retrieved using OCP's integrated OTDS OAuth 2.0 clients.

This guide is intended to provide steps needed to set up you development Site to be able to request tokens and access the Core Signature APIs.

About your Development Sandbox Site and Production Site

Your Opentext Sales Representative will set up your Development / Trial Sandbox, as well as your Production Site when you are ready to make your application live and commercially available.

Sandbox Site

Your Sandbox Site is set up for you to begin trial and development with Core Signature Service API. Note that all users and clients created in your sandbox Site are for testing purposes and will not be available in production once you move to your Production Site.

Production Site

When you are ready to make the move to production you will need to work with your Opentext Sales Representative to make your production Site available to you.

Available OCP Environments

The Core Signature Service is available on several OCP environments. To be sure you're using the correct one, please refer to the table below which outlines the Core Signature environments and the corresponding OCP Admin Center environments.

Getting Started with Admin Center

Admin Center is where you as a developer can administer your Site to add your subscriptions for applications and services available on the OCP platform.

In this guide we provide a high-level view into Admin Center Sites and Subscriptions.

To begin developing with Core Signature API you will need to have a Site created from within OCP Admin Center, and also add a Subscription to that Site.

Step 1: You need your Site.

Your Site is the place where you manage users and subscriptions to access other OCP services and applications. You also create API Access Credentials (OAuth 2.0 clients) that allow you to retrieve access tokens for your users.

For OCP customers, you will need to have your Site and Subscription provisioned for you by your Opentext provisioning representative.

Step 2: You need a Core Signature API Subscription added to your site.

When requesting an Access Token to access the Core Signature API, you will need to have a Subscription added to your Site.

For OCP customers, you will need to have your Site and Subscription provisioned for you by your Opentext provisioning representative.

Adding Admins and Users to your Subscription

Once your subscription is set up, you may want to create additional admin users and start adding other users to your subscription.

From your Site page in Admin Center, click on the Subscriptions side bar menu item.

Then click on the Core Signature subscription under the Subscriptions page. Note the name of the Core Signature subscription will be unique to your Site name and will not look exactly as shown in the screen shot below:

Once you've selected your subscription, from the side bar menu click on Admins.

NOTE: If you just want to add a regular user, click on the Users side bar menu item and follow the same steps.

Click the ( + ) button in the top-right corner of the Admins page.

In the modal page that pops up, you can now enter a valid email address of the user you want to invite.

An email invite will be sent to that user with instructions on how to accept the invitation.

That's it! You can repeat this process as many times as your subscription allows.

Accessing the Core Signature API (OCP Developers)

Prerequisites

In order to be able to access the Core Signature Service API, you will need to carry out and familiarize yourself with the following steps:

• Creating your OAuth 2.0 Credentials

• Getting an Access Token

Creating your OAuth 2.0 Credentials

In order to obtain an Access Token that allows you to make requests to the Core Signature Service API you will need to set up your API Service Credentials from within Admin Center for your site.

Prerequisites

• Set up your Admin Center Site

• Ensure a Subscription to Core Signature Service API is available and added to your Site.

Sign in to Admin Center with your Site's admin user credentials and navigate to your Site's console.

From the left-hand navigation menu, select 'API service credentials'.

From the API service credentials view, select the 'plus' ( + ) icon in the top right-hand corner.

Give your new API service credentials a name and click the 'Add' button. Note, this name is for your own organizational purposes and is not needed when accessing the OAuth 2.0 client and making requests.

Follow the instructions and take note of the Client Id and Client Secret. You will need these to make requests to the OAuth 2.0 client and retrieve your access token.

You're done! You can now use your API service credentials to obtain an Access Token.

Getting an Access Token

Getting an Access Token using Password Grant

Your API Access Credentials (OTDS OAuth 2.0 client) supports Password Grant as a method to retrieve an access token. For more information about OCP OAuth 2.0 capabilities see OCP Oauth 2.0 Documentation

To obtain an Access token you will execute a POST request to the Token Route as follows.

Token Route

To form the Token route you will need your Site's Tenant id from the Admin Center console.

Use your Tenant id in the path for the token route:

POST https://otdsauth.ot2.opentext.com/otdstenant/{YOUR_TENANT_ID}/oauth2/token

Request Parameters

Note: It is important that you include your Subscription name in the scope parameter below. Additionally, if you wish to use an endpoint that requires tenant admin access (like /brandings/) you must include otds:roles in your scope so that your token includes the tenant admin role.

Request must include the following header and parameters in the body:

header:
    Content-Type: "application/x-www-form-urlencoded"


body = {
    grant_type: password,
    username: {some_username},
    password: {some_password},
    scope: "subscription:{some_subscription_id}",
    client_id: {some_client_id},
    client_secret: {some_client_secret}
}

Sending your First Signature Request

This example will walk you through a simple user flow to upload a document, and send a Signature Request.

The flow is as follows:

Signer > Upload Document > Send Signature Request > Signer Receives Document via Email

Topics will include:

• Getting an access token

• Creating a Document

• Sending a Signature Request
  
  

Note: This document uses Qodex to illustrate how to set up the http requests. If you don't have Qodex you can download it [here]

Step 1: Get an Access Token

Before continuing, ensure you have completed and understood these steps:

• Getting Started with Admin Center

• Creating your OAuth 2.0 Credentials

• Getting an Access Token

Start by adding a new tab in Qodex, and click on the Authorization tab below the URL entry field.

Here's an example of using the Qodex Authorization tab, using OAuth 2.0 as the TYPE, to get an access token. Note, you will need to input your own Client Secret, as well as the User credentials for the person sending the Signature Request (the Sender).

Using the Authorization Tab will automatically create the correct Authorization Header when executing your requests.

When clicking on 'Request Token' you should see the token like so:

Click on 'Use Token' to use the token for your request.

Step 2: Upload a Document

Create a new tab in Qodex and change the request method to 'POST'.

For the URL, we will be using our Documents API route: https://sign.core.opentext.com/api/v1/documents/

You may need to select the Authorization Tab again, to refresh the access token. You should not have to change your OAuth 2.0 credentials that you provided in the above step.

We'll be using a sample document which can be downloaded here: signaturerequestdemo_document.pdf

The simplest way to upload a document for a user to be used in a Signature Request, is to use form-data file upload. This allows you to use the original file as-is. Other methods can be used like using a base-64 representation of the document, or simply providing a URL for the document. Using either depends on your application. More can be read in the Create a Document section.

Select the Body tab. Ensure the key name is exactly written as file, and select your file from the browser provided.

Execute the request and you should now have a JSON response that includes the document url, and the document uuid. You will need the document url for the next step.

Step 3: Create a Signature Request

To create a simple Signature Request, you will need:

• The value for 'url' in the above response.
• The email address of the intended recipient (the person signing).
• The same OAuth 2.0 credentials you used to get your access token.

Create a new request in Qodex by opening a new tab.

This will be a POST request to the Signature Request API: https://sign.core.opentext.com/api/v1/signature-requests/

Select the Body tab and enter the url and email address for the signer as JSON:

Again, ensure you have a valid Access Token by selecting the Authorization tab and request a new token with your credentials.

With your new token, execute the request. You should receive a http Success status code 201 Created.

You will also receive a JSON representation of the Signature Request you just created in your response body. This will allow you to further track the signing process of your signature request. Review the Documentation for more about what you can do with a Signature Request.

That's it! Your Signature Request is on its way! The signer will shortly receive an email requesting them to sign the document.

Getting Help for OCP Developers

For more help or if you have questions that are not covered in these documents please see the following:

• Browse resources for OCP Developers
• Or, please contact your Opentext Sales Representative.

Getting Started

The OpenText Core Signature REST API enables you to create documents and send them for signature. Using the API, have all the functionality of the frontend and more.

It is also possible to receive events from OpenText Core Signature when, for example, a document has been signed. This way you can keep your application in sync with OpenText Core Signature without polling document endpoints. For this a callback url needs to be provided when creating a document, or by setting up a Webhook.

API Authentication

In order to use the API you need a valid OCP token. Use tokens with an Authorization: Bearer YOUR_TOKEN_HERE header in your requests when making requests to the OpenText Core Signature API. Additionally, ensure that your requests have Content-Type: application/json.

Example headers: bash curl -H 'Authorization: Bearer YOUR_TOKEN_HERE' -H 'Content-Type:application/json'

Creating a Document

In order to send a signature request, we first need to create a document. There are three ways to create a document by sending a POST request to the documents endpoint. 1. Includes a file in a multipart/form-data request 2. Provide a file_from_url, in which case Core Signature will download the document from that location 3. Provide base64 encoded document content in file_from_content, together with the filename for this content in file_from_content_name.

The third option can be useful if you have trouble POSTing the file together with other configuration data (in the case of the signature-request-quick-create endpoint).

Note that when using file_from_url, the URL needs to be available for Core Signature to download. If the download location returns a content type of text/plain or text/html, OpenText Core Signature will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. external_id is optional and can be used in order to have a reference to the document in your own system. The name field is also optional and can be customized; it defaults to the filename.

Document Limitations

Currently, the following limitations exist on the size and complexity of files uploaded as documents; if a document exceeds these limits we recommend breaking up the document and only sending the portion required for signing. * Documents must be smaller than 25MB in size * Documents must be less than 110 pages in length

Sending a Signature Request

Once you have successfully created a document, you can use the signature-requests endpoint to send a signature request using the url returned from the documents endpoint.

The minimal data needed to send out a signature request is the following:

{
    "document": "https://sign.core.opentext.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/",
    "message": "Please sign this document.\n\nThanks!",
    "signers": [
        {
            "email": "otcoresupport@opentext.com"
        }
    ]
}

Note that we always also create a signer for the from_email sending the signature request, however for this signer the needs_to_sign flag is set to false meaning that this signer will not get a signature request. If you want a signer to be notify_only (not need to sign or approve), you must set needs_to_sign=false. If a request is sent where multiple signers are accidentally included with the same email and order, we will use the last one provided as the valid configuration for that signer.

By default, sending the signature request will send an email to the first signer who needs to sign the document. If you wish to control the signing link and delivery yourself, you can do so using an Embed url.

Quick Create a Signature Request

In some cases it may be desirable to create a document and send the signature request in one API call. This can be done using the signature-request-quick-create endpoint. This endpoint takes all of the fields of the documents and signature-requests endpoints together, creates the document, and sends the signature request.

Document Data Segregation Between OCP Site Users

Core Signature Service data segregation follows standard OCP user tenancy as it relates to data isolation of documents created by SignatureRequests. When you create a SignatureRequest with an access token from a specific Site on OCP, the signer will need to have an account within that same Site to be able to access the document in the Core Signature frontend (documents list) or via API requests. Otherwise, a non-registered user can access the signed document via public link, or email as specified by the developer. Public links can be enabled on a per-document basis when creating a document in the documents endpoint. Additional information in relation to general OCP tenancy can be found in OCP Developer Experience.

Filtering with Query Parameters

Several endpoints allow you to filter your results by providing values for certain fields. This can even be done in nested fields by using __ syntax to access a child field. It should be noted that when filtering, emails which contain a + (e.g user+1@opentext.com) will not be filtered correctly; this is a limitation of current filtering capabilities.

Working with a Signature Request

Adding Attachments to a Signature Request

Attachments can be added to a signature request using the document-attachments endpoint. Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments must be added to a document before a signature request is created; you cannot add or remove attachments from a document which has been sent for signature.

When retrieving attachments with the document-attachments endpoint, you will see results for attachments you personally have uploaded. If you wish to see attachments that a signer has uploaded, you must retrieve the document, which will have both sender and signer attachments included.

Overriding Signer Name

For signaturerequests and quickcreate API endpoints, it is now possible to specify the signer's name without having to explicitly define first and last name in two separate parameters (firstname and lastname), making it easier to define a signer's name from other data or user identity sources where the names are themselves not split out.

Functionally, setting fullname will override firstname and lastname for a given non-managed user (signer), although firstname and lastname will continue to exist in the user record. If present, **fullname will replace all places in the UI presented as part of generating a signature request with the signaturerequests or quickcreate API**.

Customizing the Core Signature Email

The subject and message fields can be used to customize the email sent to a signer. The message may contain the following html tags: - <a> - <abbr> - <acronym> - <b> - <blockquote> - <code> - <em> - <i> - <ul> - <li> - <ol> - <strong>

Be aware that when the HTML to text ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed.

When the from_email_name field is provided, this name will be used in the From email header as {from_email_name} <no-reply@opentext.com>. By default Sender Name (sender@email.com) | OpenText Core Signature is used as the from_email_name.

Resend the OpenText Core Signature email(s)

The resend endpoint can be used to resend the signature request email as a reminder to all signers who didn't sign yet and have previously received an email to sign the document. There is a minimum wait period of 10 minutes between sending the initial signature request and resending.

Cancel a Signature Request

A signature request that has not been fully signed or declined can be cancelled using the cancel endpoint. By doing so, all signers that have not yet signed will be unable to open and sign the document anymore.

Download a Signed Document

When a signature request has been signed the pdf field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the pdf field contained within the signing_log object field on the document resource.

The recommended way to download the files and store them in your own systems is to setup the Events callback functionality and have your application download the files on the signed (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback, so download the files right away when needed.

Public Linking a Signed Document

When creating a document, you can optionally provide the link_expire_days field to allow unauthenticated access to signers after the signature request has finished. This will allow signers to click the download links for the document and signing log and be able to access them without signing in to Core Signature for a number of days, after which this option will expire. If no value is set, the signers will also need to be registered Core Signature users in order to access the document and signing log.

Deleting Documents

To delete a document, the owner of the document must send a DELETE request to the document resource url. By default, you cannot delete a document for which there is an unfinished signature request. If you wish to cancel the signature request and delete the document, you may use the force_delete field when deleting the document.

Note that for completed documents, a deletion only makes the document unavailable for the user who requested the deletion (usually the sender). For all signers that do not have a registered OpenText Core Signature account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered OpenText Core Signature account and the grace period has lapsed, the document will be fully deleted.

If a signer is also an API user, they can send a DELETE request on the document; however this only soft deletes the document. The signer will lose access to the document (as if it's been deleted), and they will decline the document if it has an active signature request which they have yet to action.

Automatic Document Deletion

To automatically delete a document, the auto_delete_days field on a document can be set to a number of days after which a finished document (signed / cancelled / declined) will be automatically deleted. The behaviour is the same as doing a DELETE on the document resource X number of days after the document is finished. When the document is scheduled to be deleted, the auto_delete_after will hold the date after which it will be deleted.

Redirecting After Signing

A redirect_url field is available both on a signature request as well as individual signers. The signature request redirect URL acts as a default for the document, and will be overridden by an individual signer's redirect URL. When specified, Core Signature will redirect to this URL after the document is signed.

Note If no redirect_url is specified by the sender on signature request level or signer level, product defaults are followed. To learn more about redirecturl default configuration, refer to Signature-Completion-Redirect-URL API endpoint. In this case, it is expected to see a null value for redirecturl field returned in the signature-request API response. Signers will be redirected as per the defaults after completing a signing flow.

Given below is the behaviour of the redirect_url when signature request may have in-person and non-in-person signers.

Signature Request has in-person signers 1. If redirecturl is set on any non-last in-person signers or sender, then that redirecturl will be ignored. This will be reflected in the API response with null set for redirect_url field. Similarly, if any non-last in-person signer declines a document, the redirect_url set for the last in-person will be used for redirection.

1. If redirecturl is set on the last in-person signer, then that redirecturl will be called, once the last in-person signer has signed the document.

2. If redirecturl is set at the document level then redirecturl will be called only after the last in-person signer has signed the document.

3. For non in-person signers, if redirecturl is set on signer level or at document level , those non-in-person signers will be redirected to that url (document level redirecturl used if not set at signer level), once they log-in to Core Signature and sign the document.

Signature Request has no in-person signers 1. If redirecturl is set on the sender, then that redirecturl will be called once the sender signs the document.

Disabling Signing Tools / Features

It is possible to disable certain tools and features signers have when signing a document. The following flags can be set to true when creating a signature request to disable these features.

• disable_checkbox: Disable adding a checkbox placeholder
• disable_text: Disable adding a text placeholder
• disable_date: Disable adding a date placeholder
• disable_attachments: Disable uploading / adding attachments
• disable_text_signatures: Disable usage of signatures generated by typing (text)
• disable_upload_signatures: Disable usage of uploaded signatures (images)

Please note that we strongly discourage disabling features, as these are carefully chosen for optimal usability of the Core Signature product.

Required Attachments

To require signers to upload attachments (like a passport picture), the required_attachments field can be used. This field takes an array of objects with a name parameter. Example: required_attachments: [{"name": "Passport"}]

Templates

In the frontend application it is possible to create templates. These templates can be found in the templates endpoint. In order to send a signature request using a template, reference the URL of the template in the template field. This works in both the documents and the signature-request-quick-create endpoints.

Automatic Reminders

To enable automatic reminders, set the send_reminders boolean to true on the signature request resource. When enabled, Core Signature will automatically remind signers to sign a document.

Preparing a Document

Using the OpenText Core Signature frontend web application you have the option to prepare a document. This helps the receiver as they can only sign the document at the designated place(s) on the document.

Using the API you can also prepare a document by using tags to specify where a signer needs to add a date, text, checkbox, and/or a signature.

Tags need to start with [[ and end with ]]. The tag data is separated by a pipe |. The first letter of the tag represents the tag type and must be one of the following:

• t for text
• d for date
• s for signature
• c for checkbox

The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer.

The template tags are assigned to the order in which the email addresses are added to the contact field, and are not the same as the order of signing. This means that for example s|1 can be the first or last signer depending on what you specified in the order of signing (if used of course).

As the sender is always the first email address added, meaning the sender is always s|0. If the sender does not need to add a signature or other data input, then s|0 will be assigned to the next in line.

Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers OR signers just get an unprepared document to sign when there were no placeholders declared for them.

Examples:

[[s|0                 ]]  // A signature for the first signer OR the owner/sender when they need to sign.
[[c|0                 ]]  // A checkbox placeholder for the first signer
[[d|1                 ]]  // A date input placeholder for the second signer
[[t|2                 ]]  // A text input placeholder for the third signer

The height / width (font size) and the position of the tag in your document matters. Also, since you do not want the placeholder tag to show up in the document, you need to make the font color match the background.

Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger, as desired. For this reason make sure to leave enough space or double the line height in order for the placeholder to not overlap the line above.

Tag modifiers

There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index.

• r to make a placeholder required: 1 / true for required, 0 / false for not required
• m to make a text placeholder multiline: 1 / true for multiline, 0 / false for single line (default)
• n to set a label / name on a text placeholder: 'a string'
• p to prefill text / dates on a text / date placeholder: 'a string'. For a date placeholder this can also be set to 0 / false to not prefill the current date.
• id to assign an external_id to the placeholder: your_id (see also Retrieving signer input and Prefill tags)

Examples: [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is checked by default (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags').

Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening [[ and closing ]] tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly.

Prefill Tags / Templates

Instead of generating a new document and using the p tag modifier to prefill signer input data, it is also possible to use prefill_tags. For this to work all tags need to have an id as this is needed to reference the tag.

Example:

[[c|0|id:checkbox_1                      ]]  // Should be checked
[[c|0|id:checkbox_2                      ]]  // Should not be checked
[[d|0|n:Birth date|id:birth_date         ]]  // Should be prefilled with the birth date of the signer
[[t|0|n:City|id:customer_city            ]]  // Should be prefilled with 'New York'

When a document contains the tags above, you can prefill them using the prefill_tags field on document by referencing the 'id'.

"prefill_tags": [
    {"external_id":"checkbox_1", "checkbox_value":"true"},
    {"external_id":"checkbox_2", "checkbox_value":"false"},
    {"external_id":"birth_date", "date_value":"1984-12-31"},  // must be in ISO format ([YYYY]-[MM]-[DD])
    {"external_id":"customer_city", "text":"New York"}
]

If you are using templates created from within the Core Signature app, you can also set the external_id of a template tag in the advanced section when editing a tag.

Note that it's also possible to add these tags when using the OpenText Core Signature JS client and the Frontend API.

For more information & examples of how to use prefill tags, see this document.

Prepare Using the Web Interface

It is also possible to have the sender of a signature request prepare the document before sending the request out. To use this functionality, set the is_being_prepared flag on the signature request resource to true. Should you like to have a seamless login flow just append ?auth_provider=<your_auth_provider>&site=<your_tenant_id> to the end of the prepare_url. For OCP, the auth_provider is opentext_ot2, and the tenant_id is the ID for the application being built as defined in OpenText Admin Center. If SSO is enabled for the user/tenant on OCP, an additional parameter otds_username is required to be added to the url by the integrating application. The url would then look like ?auth_provider=<your_auth_provider>&site=<your_tenant_id>&otds_username=<user's email address>. When is_being_prepared is set to true, the signature request will not be sent out to the recipient(s) and the prepare_url field will be set to a URL where your application can redirect the sender to prepare the document. Please note that if the sender does not have an Core Signature account they will be asked to verify their email after preparing the document.

You may wish to have the sender redirected after sending the signature request using the web interface (back to your application, for example). To do this, append a redirect_url parameter to the prepare_url returned when creating the signature request (e.g {prepare_url}?redirect_url=https://your.application.com/). Be sure to include the full URL, including protocol, when using this parameter. Note that this will take precedence over in-person signing, and the sender will always be redirected after sending.

Example:

{
    "file_from_url": "https://sign.core.opentext.com/static/demo/signature_request_demo_document.pdf",
    "who": "mo",
    "is_being_prepared": "true",
    "signers": [{"email": "you_the_sender@yourcompany.com", "embed_url_user_id": "unique_id_of_your_choice"}, {"email": "otcoresupport@opentext.com"}]
}

Note that it's possible to include tags in the document. The sender will be able to change / remove them.

Retrieving Signer Input

All text, date, and boolean inputs of signers after a signer signs are available in the inputs field of a signer. This can be helpful if you need to update your systems based on data signers add to a document.

"inputs": [
    {
        "type": "d",                    // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input)
        "page_index": 0,                // Index of the page on which this input resides
        "text": "09-25-18",             // Text as seen on the document (only for date and text inputs)
        "checkbox_value": null,         // true or false (checkbox inputs only)
        "date_value": "2018-09-25",     // The date in ISO format ([YYYY]-[MM]-[DD])
        "external_id": null             // (Optional) The external ID assigned to a tag (helpful if you need to identify a specific input. See 'Tag Modifiers')
    }
]

Accessing the Core Signature UI

The Core Signature UI is fully available to users who are integrating with the API via OCP. As described above in the Prepare using the web interface section, to log in to the UI you simply hit Core Signature with the URL parameters ?auth_provider=<your_auth_provider>&site=<your_tenant_id>. If SSO is enabled for the user/tenant on OCP, an additional parameter otds_username is required to be added to the url by the integrating application. The url would then look like ?auth_provider=<your_auth_provider>&site=<your_tenant_id>&otds_username=<user's email address>.

Below you can find a comprehensive list of all of the Core Signature UI pages you are able to navigate to, along with their purpose.

Events

Event Polling

If you wish to poll for events, you can do so by creating GET requests for the Events resource. This endpoint supports queries for several parameters, enabling you to poll for specific events.

However, it should be noted that polling is not the optimal method to retrieve event-based data in asynchronous flows like signing a document. We recommend using Event Callbacks or Webhooks to react to events, as polling can in rare cases lead to inconsistent results if a document is being processed when the polling occurs.

Event Callbacks

In order to receive the events as a callback to your application a callback url needs to be set. This can be set on a per-document basis, or by creating a webhook. To set this for a document, you can set the callback url using the events_callback_url field when creating a document or when using the signature-request-quick-create endpoint.

It is also possible to change the callback url on a per document basis. To use this functionality you can set the callback url using the events_callback_url field when creating a document.

When set, Core Signature will POST events as application/json to this endpoint. Your endpoint should return a 200 OK response. OpenText Core Signature will retry delivering events in the case of a timeout or a 500 response from your server according to a set schedule. The wait times between retries are shown below.

Callback Validation

When you provide a events_callback_url we attempt a simple POST request to ensure that the url is reachable by our system. If the url is not reachable you will receive an error message in the response payload.

Event Types

By default, events will be generated as a document and its signature request progress through a signature request flow. The following event types are available: - convert_error: Document conversion error - converted: Document converted - sent: Document sent - declined: Document declined - cancelled: Document cancelled - signed: Document signed - signer_signed: Signer signed - signer_email_bounced: Signer email bounced - signer_viewed_email: Signer viewed email - signer_viewed: Signer viewed document - signer_forwarded: Signer forwarded document - signer_downloaded: Signer downloaded - signrequest_received: Signature request received

It should be noted that only the signer-specific events (signer_signed, signer_email_bounced, etc) will have signer information in the event.

Event status codes: - ok: ok - error: error

The event status will be error for the following events: - convert_error - signer_email_bounced

The document status field can have the following codes: - co: converting - ne: new - dr: draft - se: sent - vi: viewed - si: signed - do: downloaded - sd: signed & downloaded - ca: cancelled - de: declined - ec: error converting

Example callback request: json { "document": { "api_used": true, "attachments": [], "external_id": "your_id_of_this_document", "file_from_url": "url where OpenText Core Signature downloaded the document, if this functionality was used", "name": "document.pdf", "pdf": null, "prefill_tags": [], "security_hash": null, "signing_log": null, "signrequest": null, "status": "co", "template": null, "url": "https://sign.core.opentext.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/", "user": null, "uuid": "f2bac751-4fa1-43f1-91de-a1b8905c239a" }, "event_hash": "89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7", "event_time": "1537889008", "event_type": "converted", "signer": null, "status": "ok", "timestamp": "2018-09-25T15:23:28.836457Z", "uuid": "ffffd4dd-89c7-4133-ba2d-960f65c8d395" }

All event data can also be fetched using the REST API Events resource. This is a helpful tool to see how the data is structured when developing your application.

You can check the authenticity (that the event really came from Core Signature) by generating and comparing the event_hash that comes with the event. The event_hash is generated with the HMAC algorithm using your Token as a key in SHA256 digest mode.

OpenSSL shell example: bash echo -n "${event_time}${event_type}" | openssl dgst -sha256 -hmac "YOUR_TOKEN_HERE"

Which expands to: bash echo -n "1537889008converted" | openssl dgst -sha256 -hmac "YOUR_TOKEN_HERE" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7

Always use SSL enabled endpoints!

Event Webhooks

To receive only specific event callbacks, webhook subscriptions can be created. The resource takes an event_type, callback_url and optionally a name to easily identify what the webhook is used for. The webhooks resource details all possible event types to which you can subscribe. Webhooks also receive the signrequest_received event, which can be used to notify users that they have received a new signature request.

Disable all Core Signature Email Events

It is possible to disable all Core Signature status emails as well as the email that contains the signed documents. When using this functionality, the following events will not generate a Core Signature email:

• sent: Document sent
• signer_email_bounced: Signer email bounced
• signer_viewed_email: Signer viewed email
• signer_viewed: Signer viewed document
• signer_signed: Signer signed document
• signer_downloaded: Signer downloaded document
• signed: Document signed
• downloaded: Document downloaded
• declined: Document declined
• cancelled: Document cancelled

To enable this feature set the disable_emails flag on the signature request resource to true.

Note that event emails will only be disabled if there is an events_callback_url available for the document or a webhook has been registered for the event type, as your application is expected to notify users instead of Core Signature. If you are using webhooks, you need to register a webhook for each event type for which you do not wish to receive emails. The initial Core Signature email (which contains the link to sign) can only be disabled by using the Embed url functionality.

Frontend API

Another option to help your users send signature requests is using the frontend API. This involves no token and is merely used to prefill the OpenText Core Signature box found at the homepage for your users.

GET params for prefilling the box: api=v1 // The version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // Emails of 'signers', comma separated from_email=you@yourcompany.com // Email of the person sending the signature request doc_url=https%3A%2F%2Fsign.core.opentext.com%2Fstatic%2Fdemo%2Fsignature_request_demo_document.pdf // The URL from which Core Signature can download the document

Example resulting URL: https://sign.core.opentext.com/#/send-for-signature?api=v1&who=mo&signers=tech-support@opentext.com&doc_url=https%3A%2F%2Fsign.core.opentext.com%2Fstatic%2Fdemo%2Fsignature_request_demo_document.pdf

Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON. A JavaScript example: javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d

OpenText Core Signature JS Client

To use the Core Signature JavaScript library, include the following in your page: html <script src="https://sign.core.opentext.com/ot-core-signature-js/v1/ot-core-signature-js.min.js"></script>

Or, for async loading use: html <script> !function(t,e,n,i){var s=function(e,n){t.CoreSignature&&t.CoreSignature.loaded||setTimeout(function(){t.CoreSignature.init(e,n)},50)};t.CoreSignature=t.CoreSignature||{loaded:0,init:s};var o="https:"==e.location.protocol?"https://":"http://",u=e.createElement("script");u.async=!0;var c=e.scripts[0];u.src=o+"sign.core.opentext.com/ot-core-signnature-js/v1/ot-core-signature-js.min.js",c.parentNode.insertBefore(u,c),t.CoreSignature.init(n,i)}(window,document,{ // this initial configuration is optional, may also be undefined }, function (CoreSignature) { // This callback is optional, it may also be undefined // The OpenText Core Signature library is loaded and also passed as first argument // Execute your code here... }); </script>

The library uses UMD (Universal Module Definition).

Usage

// same as the frontend API GET parameters, these are all optional. We recommend setting auth_provider and site to show the proper login.
const conf = {
    api: 'v1',
    who: 'mo',
    signers: 'first_email@example.com,second_email@example.com',
    close: true,    // Close the popup when done. Default: true
    // or use next:
    next: '',       // Redirect to this URL when done signing
    auth_provider: 'opentext_ot2',
    site: 'your_ocp_tenant_id'
}
// these are also optional, the popup will be centered in the window opening the popup
const popup_conf = {
    width: 460,  // Width of the popup in pixels. Default: 460
    height: 600, // Height of the popup in pixels. Default: The height of the window opening the popup
}

// To open a specific document, first create a document using the REST API with your backend
const doc_uuid = 'the-uuid-of-the-document';
CoreSignature.browser.openSetupPopupWithDocUUID(doc_uuid, conf, popup_conf);

// Create a document from a URL
const doc_url = 'https://sign.core.opentext.com/static/demo/signature_request_demo_document.pdf'
CoreSignature.browser.openSetupPopupWithDocURL(doc_url, conf, popup_conf);

// Create a document from a template UUID
const template_uuid = 'the-uuid-of-the-template'
CoreSignature.browser.openSetupPopupWithTemplateUUID(template_uuid, conf, popup_conf);

// Open a popup using custom params
const popup = CoreSignature.browser.openPopup(conf, popup_conf);

// If your document contains template tags / placeholders that have an 'external_id',
// it is possible to 'prefill' these for a particular signature request by updating your conf object:
conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}];
// Now all template tags with this external_id will be prefilled with 'New York'

// All popup openers return an instance of the popup to which event callbacks can be registered (they can be chained)
// The possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any'
// Note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true)
// When sending a signature request and the sender also needs to sign, you can receive the 'signed' or 'declined' event
// after the 'sent' event (signature request created).
// When the sender is done (sending and possibly siging) the 'finished' event is fired.
popup = popup.on('closed', function (event_type, payload, event) {
    // This would fire when the popup closes, allowing you to update your page on the event
    console.log(event_type, payload, event);
})

// Shortcut to fire on all events ('any')
popup.onAny(function (event_type, payload, event) {
    // This would fire on all events
    console.log(event_type, payload, event);
})

// To set a default configuration for all future calls
CoreSignature.browser.setConfig({
    // Add your configs here
});

// When creating a document for your users using our REST API and opening that document in the popup in response to clicking a button,
// you might need to open the popup before you know the UUID of the document from your backend.
// This is to prevent popup blockers from kicking in when doing async work before we open a popup.
// For this use case, you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later.

$('button#your_button').on('click', function () {           // Using jQuery in the following example (not required for ot-core-signature-js)
    var popup = CoreSignature.browser.openLoadingPopup();   // Open a popup on button click right away
    popup.onAny(function (event_type, payload, event) {
        // All listeners created on the loading popup will also be registered on the popup events fired later after the call
        // CoreSignature.browser.openPopupForDocUuid...
        console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload);
    });
    // Async call to some endpoint on your backend that creates a document using the REST API.
    $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){
        // Instead of opening a new popup we use the one that is 'loading', as otherwise
        // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click).
        // We assume here your endpoint returns the UUID of the document created in the response
        CoreSignature.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup});
        // `{sr_popup: popup}` makes the library use an existing popup instead of creating a new one
    });
});

CoreSignature.browser.openPopupForDocUrl('https://sign.core.opentext.com/static/demo/signature_request_demo_document.pdf');

Additional Signing Methods

Embed URL

Normally, Core Signature will send the signature request email to signers containing a personal link to sign a document. This is how Core Signature validates an email address, and is the preferred signature request flow. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an embed_url and redirect a signer to that link. Combining this with a redirect_url allows a continuous flow to be achieved.

Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log, as Core Signature cannot guarantee that a document is signed by someone having access to an email address.

To generate the embed_url you need to declare the ID of the logged in user in YOUR application in the embed_url_user_id field. This ID will also show in the signing log for any users with unverified credentials.

The generated embed_url can only be used until the document is signed. Note that you are able to combine signers with and without a generated embed_url. The order field also behaves as you would expect. For example, if the first signer (order = 0) has an embed_url generated and the second (order = 1) not, the second signer will only receive the signature request email when the first one has signed.

When using this embed_url, you can add any of the following url parameters to hide some elements in the header:

• hide_decline=1 (hide the option to decline)
• hide_forward=1 (hide the forward button)
• hide_login=1 (hide the login button)
• hide_logo=1 (hide the logo)
• hide_title=1 (hide the document title in the header)

Be aware that the embed_url may already contain other URL parameters. Also note that hiding the login button does not disable the login prompt for signers that already have a Core Signature account. This cannot be disabled.

If you also want to disable all other Core Signature emails, see Disable all OpenText Core Signature email events.

In Person Signing

In person signing can be achieved with the API by using the Embed url in your signature requests. This allows for instant generation of a signing link, and in combination with the approve_only field also allows for in-person approving.

Note that each in-person approving signer will need to have an embed_url_user_id set. The following is an example of such signer configuration.

{
    "who": "mo",
    "signers": [
        {
           "email": "signer@company.com",
           "embed_url_user_id": "your ID",
           "approve_only": true
        }
    ]
}

In some cases, your application might want to generate one URL for both the sender of the document and the receiver to sign a document immediately after each other in person.

This can be achieved by the following signer configuration example, where you can redirect the user to the embed_url of the sender. After the sender has signed they will be redirected to the next in_person signer. Since an email will not be sent for an in person signer, you must use the embed_url to generate the signing link for the first signer. Then, the UI will handle the document as each in person signer signs in sequence.

{
    "who": "mo",
    "signers": [
        {
           "email": "you@yourcompany.com",
           "order": 1,
           "embed_url_user_id": "your ID",
        },
        {
            "email": "otcoresupport@opentext.com",
            "order": 2,
            "in_person": true
        }
    ]
}

It should be noted that when you have more than one in person signer, the first signer needs to have an embed_url_user_id set. If the sender is not of the signers, then the first in person signer also needs to have an in_person attribute set. The following configuration can be used with only others case.

{
    "who": "o",
    "signers": [
        {
           "email": "first+signer@company.com",
           "embed_url_user_id": "your ID",
           "in_person": true
        },
        {
           "email": "second+signer@company.com",
           "in_person": true
        }
    ]
}

This way you can redirect the user to the embed_url of the signer. After the signer has signed they will be redirected to the next in_person signer. Since an email will not be sent for an in person signer, you must use the embed_url to generate the signing link for the first signer. Then, the UI will handle the document as each in person signer signs in sequence.

Integrations

The Core Signature API has the ability to support specific behaviours or logic you may require for your integration with our service. If you require additional functionality, please reach out to your representative.

Once an integration is established, the specific behaviour can be achieved by supplying your integration name when creating a document. By providing the integration type along with any necessary accompanying data, we can handle and apply any additional logic.

For example, you may desire for the sender's department to be shown in signature request emails in addition to their name. In that case, an implementation might include providing a department field to the API. The request to create a document would then include the following field, along with the regular fields:

"integrations": [{
    "integration_data": {
        "type": "your_integration_name",
        "department": "department_name"
    }
}]

Branding

Our customers have the ability to customize their branding using the Core Signature API. If a custom branding has been set for a tenant, that branding will always be used over the default Core Signature branding. It should be noted that only a tenant admin has the ability to make changes using this API.

NOTE: Branding is always rendered in real time for users. So, if you modify the branding for your tenant, any in-flight signature requests will start showing the new branding in subsequent emails, UI pages, etc even if the branding was different when it was sent.

Product Logo

To update product logo using our API we support the following image types:

['jpg', 'jpeg', 'png', 'tiff', 'gif', ‘bmp’]

Any other image type will return a 400 Bad Request. The logo image should be a file in a multipart/form-data format. Uploading file via URL is not supported. If an invalid request encoding is used, a 400 with the error message ERROR_FILE_PARSING_FAILED will be returned. The expected dimensions for the logo image is 480x47 pixels. All images uploaded in our API will be rescaled to this size while preserving its original aspect ratios.

Product Name

We provide the ability to customize brand name through this API. Your custom product name will be displayed in document viewer, emails, and tool tip help texts appended with (Powered by OpenText Core Signature). We support product_name input to be 100 characters long.

Defaults

Similar to branding, several functional aspects of the signing flow can be customized to make your signature flows as seamless as possible given your product's specific requirements.

NOTE: Like branding, defaults are used in real time, so if you modify your defaults before a signer actions a document, they will see the new behaviours you've set.

Signer Login Behaviour

The login behaviour for signers can be customized via login_modal so that all signers have a frictionless signing experience. When set to optional, the login modal will appear for signers to choose if they want to login or skip and sign without authenticating. When set to required, signers must log in before being able to sign the document. When set to bypassed, upon accessing the document (including via clicking the signing link), signers will not see the login modal. Additionally, when the signer is in the signing UI they will not have the option to log in. The default behaviour is optional.

Signature Completion Redirect URL

The default URL to which signers will be redirected after successfully signing can be provided via the signature_completion_redirect_url field. This default can be overridden on a per-signature request basis when creating the signature request via /signature-requests/ or /signature-request-quick-create/.

Contact Support: Email: support@sign.core.opentext.com

1. document-attachments-{uuid} - Retrieve a Document Attachment GET {{baseUrl}}/document-attachments/:uuid/

2. brandings-{uuid} - Partially update a Branding customization PATCH {{baseUrl}}/brandings/:uuid/

3. signature-requests - Create a signature request POST {{baseUrl}}/signature-requests/

4. Retrieve a list of allowed file types for upload GET {{baseUrl}}/allowed-file-types/

5. Search documents GET {{baseUrl}}/documents-search/?page=19875956&limit=19875956&q=velit et&name=velit et&signer_emails=velit et&status=velit et&who=velit et&format=velit et&signer_data=-1040341.9640929699

6. Quick create a signature request POST {{baseUrl}}/signature-request-quick-create/

7. templates - Retrieve a list of Templates GET {{baseUrl}}/templates/?page=19875956&limit=19875956

8. defaults/signing-flow-customizations - Retrieve a list of Signing Flow customizations GET {{baseUrl}}/defaults/signing-flow-customizations/?page=19875956&limit=19875956

9. brandings-{uuid} - Retrieve a Branding customization GET {{baseUrl}}/brandings/:uuid/

10. brandings-{uuid} - Update a Branding customization PUT {{baseUrl}}/brandings/:uuid/