<img height="1" width="1" style="display:none;" alt="" src="https://px.ads.linkedin.com/collect/?pid=4052188&amp;fmt=gif">

FlexAPI™ Documentation

Accessing the powerful, secure SIGNiX service is as easy as a few simple API calls. Whether you're automating the certified delivery of a single document to a known signer, having three documents signed by a variety of signers, integrating the extensive SIGNiX remote online notarization capabilities, or even building in aspects of the SIGNiX user experience, branded, into your own portal or application, the SIGNiX FlexAPI provides you with the tools needed to get the job done.

 

digital signature faq

Contents


digital signature faq

 

Introduction

This document specifies the business-to-business (B2B) interface for the SIGNiX Business to Business (B2B) interface (aka FlexAPI). This interface allows customer servers to interact directly with the SIGNiX servers to create new transactions, monitor their progress, and download finished documents.

A document sponsor ("Sponsor") makes B2B requests to SIGNiX and receives responses. The requests and responses are formatted as XML and carried over HTTPS on the Internet, so the B2B interface is also referred to as a web service. The operations that can be performed by the web service are also referred to as web methods. For each web method, this document describes the XML structure of the request and of the matching response.

Please note that the element positioning is in the correct order throughout this document. Variations from these specs will lead to error messages. (For example, don't place <Client> before <Sponsor> in the <CustInfo> element).

Items listed as "required" must be included while items listed as "optional" may be excluded from the XML (if it is included, then there may be a required value). Upper and lower case must be observed.

The detailed structure of this interface is specified in an set of XML schema files, which define the service namespace: urn:com:signix:schema:sdddc-1-1

[

[Back to top]

 

digital signature faq

 

Basic Integration Workflows

Most every workflow imaginable will use one or more of the SIGNiX API calls, but there are many factors to consider depending on how an integrator wants to expose the SIGNiX features.

 

Simple Document Delivery and Signature - No Embedded UI

When a use case can be met by programmatically sending a pre-tagged document out to a signer, and doesn't require any embedding of the SIGNiX user interface, a simple API call flow can be used. The progression of steps here (and below in other examples) includes push notifications so the integrated application can know when certain transaction milestones have been met.

 

 

Description / Steps

1. SubmitDocument transfers all information about the transaction to SIGNiX, including signer info, PDF document(s) and tasks to complete. Integrated application receives a response including a SIGNiX DocumentSetID which will be used in future calls. A push notification ('Send') is sent back to the system indicating the transaction is sent.

2. Email(s) sent to the signer(s) with a link to sign. Signers will click the link, authenticate (optionally) and review and sign the document(s). When each signer is finished, a push notification ('partyComplete') is returned to the integrated application. If all signers have completed their tasks, another push notification is sent ('complete') indicating the integrated application can now proceed to download the document(s) and audit trail.

3. The integrated application sends a DownloadDocument call to SIGNiX, referencing the DocumentSetID provided earlier. PDF documents and audit trail are returned.

4. Upon receiving the documents in the response from SIGNiX, the integrated application sends a ConfirmDownload call to SIGNiX, which allows SIGNiX to move the documents into a proper retention state.

 

Embedding the SIGNiX 'Wizard' Interface

Often, PDF documents intended for signature do not already have PDF fields / tags associated with the tasks that a signer may need to complete. In this case, an integrated application may choose to expose some of the SIGNiX 'wizard' interface which allows submitters to use a simple drag-and-drop experience to add tasks for various signers on transaction documents and then send them on to signers.

This example may also be used in remote online notarization, where a notary / submitter is manually adding a notary seal / stamp to the document as well as other pertinent information (i.e. online meeting scheduling).

Deeper levels of integration and embedding can be reached by using SIGNiX AJAX API calls.

 

 

Description / Steps

1. SubmitDocument transfers all information about the transaction to SIGNiX, including signer info, PDF document(s) and tasks to complete. In this use case not all tasks may be known. In addition, a 'Suspend on Start' parameter is added to the API call letting SIGNiX know to hold off on sending the transaction. Integrated application receives a response including a SIGNiX DocumentSetID which will be used in future calls.

2. Using the DocumentSetID returned by SIGNIX, the integrated application then sends a GetAccessLink - Submitter call to SIGNIX, which returns a short-lived URL which can be used to embed the SIGNiX interface in an iFrame or other browser window.

3. The submitter / user uses the SIGNiX drag-and-drop interface to add tasks (signatures, text fields, etc) to the document(s) and then clicks Send. Alternatively, the integrated application may send a Resume API call to SIGNiX to start the transaction at SIGNiX. A push notification ('Send') is sent back to the system indicating the transaction is sent.

4. Email(s) sent to the signer(s) with a link to sign. Signers will click the link, authenticate (optionally) and review and sign the document(s). When each signer is finished, a push notification ('partyComplete') is returned to the integrated application. If all signers have completed their tasks, another push notification is sent ('complete') indicating the integrated application can now proceed to download the document(s) and audit trail.

5. The integrated application sends a DownloadDocument call to SIGNiX, referencing the DocumentSetID provided earlier. PDF documents and audit trail are returned.

6. Upon receiving the documents in the response from SIGNiX, the integrated application sends a ConfirmDownload call to SIGNiX, which allows SIGNiX to move the documents into a proper retention state.

 

Embedding the SIGNiX Signing Experience

An integrated application may want to provide a 'portal' experience to a signer and not rely on SIGNiX delivering emails to notify clients of documents needing to be signed. This may be best employed when clients desire to control access to the signing experience based on a specific workflow requirement.

Deeper levels of integration and embedding can be reached by using SIGNiX AJAX API calls.

 

 

Description / Steps

1. SubmitDocument transfers all information about the transaction to SIGNiX, including signer info, PDF document(s) and tasks to complete. Integrated application receives a response including a SIGNiX DocumentSetID which will be used in future calls. A push notification ('Send') is sent back to the system indicating the transaction is sent.

2. Using the DocumentSetID returned by SIGNIX, the integrated application then sends a GetAccessLink - Signer call to SIGNIX, which returns a short-lived URL which can be used to embed the SIGNiX signing interface for a particular signer in an iFrame or other browser window.

3. Signers will authenticate (optionally) and review and sign the document(s). When each signer is finished, a push notification ('partyComplete') is returned to the integrated application. Repeated GetAccessLink calls may be used for other signers in the workflow, repeating steps 2 and 3. Once all signers have completed their tasks, another push notification is sent ('complete') indicating the integrated application can now proceed to download the document(s) and audit trail.

4. The integrated application sends a DownloadDocument call to SIGNiX, referencing the DocumentSetID provided earlier. PDF documents and audit trail are returned.

5. Upon receiving the documents in the response from SIGNiX, the integrated application sends a ConfirmDownload call to SIGNiX, which allows SIGNiX to move the documents into a proper retention state.

 

Embedding Both the SIGNiX 'Wizard' Interface & Signing Experience

There may be some use cases where PDF documents intended for signature do not already have PDF fields / tags associated with the tasks that a signer may need to complete. In this case, an integrated application may choose to expose some of the SIGNiX 'wizard' interface which allows submitters to use a simple drag-and-drop experience to add tasks for various signers on transaction documents and then send them on to signers. In addition, an integrated application may want to provide a 'portal' experience to a signer and not rely on SIGNiX delivering emails to notify clients of documents needing to be signed. This may be best employed when clients desire to control access to the signing experience based on a specific workflow requirement.

Deeper levels of integration and embedding can be reached by using SIGNiX AJAX API calls.

Description / Steps

1. SubmitDocument transfers all information about the transaction to SIGNiX, including signer info, PDF document(s) and tasks to complete. In this use case not all tasks may be known. In addition, a 'Suspend on Start' parameter is added to the API call letting SIGNiX know to hold off on sending the transaction. Integrated application receives a response including a SIGNiX DocumentSetID which will be used in future calls.

2. Using the DocumentSetID returned by SIGNIX, the integrated application then sends a GetAccessLink - Submitter call to SIGNIX, which returns a short-lived URL which can be used to embed the SIGNiX interface in an iFrame or other browser window.

3. The submitter / user uses the SIGNiX drag-and-drop interface to add tasks (signatures, text fields, etc) to the document(s) and then clicks Send. Alternatively, the integrated application may send a Resume API call to SIGNiX to start the transaction at SIGNiX. A push notification ('Send') is sent back to the system indicating the transaction is sent.

4. Using the DocumentSetID returned by SIGNIX, the integrated application then sends a GetAccessLink - Signer call to SIGNIX, which returns a short-lived URL which can be used to embed the SIGNiX signing interface for a particular signer in an iFrame or other browser window.

5. Signers will authenticate (optionally) and review and sign the document(s). When each signer is finished, a push notification ('partyComplete') is returned to the integrated application. Repeated GetAccessLink calls may be used for other signers in the workflow, repeating steps 4 and 5. Once all signers have completed their tasks, another push notification is sent ('complete') indicating the integrated application can now proceed to download the document(s) and audit trail.

6. The integrated application sends a DownloadDocument call to SIGNiX, referencing the DocumentSetID provided earlier. PDF documents and audit trail are returned.

7. Upon receiving the documents in the response from SIGNiX, the integrated application sends a ConfirmDownload call to SIGNiX, which allows SIGNiX to move the documents into a proper retention state.

 

[Back to top]

 

digital signature faq

Transport Details

This section describes more details of how B2B requests and responses are formatted and sent between the client and server and gives the URLs for communicating with the web service.

 

HTTP Request

B2B requests are submitted with HTTP POST where the HTTP request body (MIME content type "application/x-www-form-urlencoded") is formatted as an HTML form submission with the following form parameters:

 

Name

Value

method

The name of the web method.

request

The XML of the B2B request.

 

Note that the parameter names, which are case sensitive, must be in lowercase. The name of the web method is always the name of the outermost XML element of the request, with “Rq” removed.

For example, when sending a SubmitDocument request, the name of the outer XML element is "SubmitDocumentRq" and the method parameter should be set to “SubmitDocument”.

 

HTTP Response

The HTTP response body (content type "text/xml") contains the XML of the B2B response.

Normally, the HTTP response has a success status code (such as 200), and the content type is "text/xml". In this case, the client parses the XML response and processes it by examining the StatusCode, StatusDesc, and other elements.

If an unexpected error occurs or if the system is temporarily unavailable (for maintenance, for example), then the response will have one of the following forms:

1. The HTTP response has an error status code (such as 500). Typically caused by a software error, a network problem, etc.

2. The HTTP response has a success status code, but the content type is "text/html". Typically occurs when the server is down for maintenance and the URL fails over to a server that responds with a page announcing the server is down for maintenance. To test a similar case, use http://webtest.signix.biz/sdd/b2b/sdddc_ns.jsp as the web service URL. Note that this URL is for HTTP, not HTTPS; the response is an HTML page that says the SIGNiX site requires HTTPS.

3. The connection cannot be made or times out, and the client gets no response. Typically caused by a network problem at the client site, server site, or between.

 

[Back to top]

 

Web Service URL

The service is available at the following service endpoint URL:

https://server/sdd/b2b/sdddc_ns.jsp - This endpoint always validates service requests against the schema, and will return schema-valid responses.

The service is available on the following servers:

For demo/test use, server is webtest.signix.biz, and a demo user ID and password are used. This is the server to use for all development and almost all testing. Real documents and real identity information should not be submitted to this server.

• For production use, server is www.signix.net, and a real user ID and password are used. This is the server to use for real transactions.

NOTE: Be sure devices that will be accessing SIGNiX for signing or transaction editing (Wizard) have allow-listed the URLs above.

 

[Back to top]

 

Secure Communications

Communication with the web service is secured using HTTPS (HTTP over SSL). Using SSL provides:

• Privacy: traffic between the Sponsor and SIGNiX is encrypted to prevent eavesdropping.

• Data Integrity: traffic is protected from tampering with a Message Authentication Code.

• Server Authentication: the Sponsor can ensure it communicates with SIGNiX and not an imposter. The client (Sponsor) authenticates the server's identity by checking the SSL certificate presented by the web server; this is known as server-side SSL. The client's SSL library typically checks the SSL certificate by verifying that the signature on the server's certificate is from a trusted certificate authority (CA).

 

[Back to top]

 

Client Authentication

The server authenticates the client's identity by checking a user ID / password pair included in each web service request.

 

Timing

The web methods are synchronous, meaning that the client posts a request and waits for a response from the server.

Because the web method will take a few moments to execute, the client should update its user interface while the call is in progress. For example, the client could display "Please wait while the documents are submitted..." during the SubmitDocument call.

 

[Back to top]

 

digital signature faq

 

API Calls

The sections below provide details for each web method and describe the XML structure of the corresponding request and response.

 

SubmitDocument

The SubmitDocument method submits a set of documents for secure delivery to, and optional viewing and signature by, a set of end users (signers / parties). Note that despite the term 'Document,' the call is actually used to start an entire SIGNiX transaction. It can be used for multiple documents.

After the SIGNiX system successfully receives the set of submitted documents, it performs additional checks and then sends an email to the first party with a link to click to pick up the documents in order to sign and/or view them.

 

[Back to top]

 

SubmitDocument - Request XML

Because the request XML for SubmitDocument is large, an overview of its structure is given below. Only elements that contain other elements are shown here. As in the notation for regular expressions, '+' indicates the element appears once or more than once, and '|' indicates a choice of alternatives. Parenthesis indicates optional elements, and indentation indicates embedding.

SubmitDocumentRq

CustInfo

Data

(MemberInfo)+

(Form)+

(SignatureLine | InitialLine | View)+

 

The detailed structure of the response is specified in the XML schema file. An annotated example of the request XML is as follows.


<?xml version="1.0" ?>
<SubmitDocumentRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo>                          Occurs once only

<Sponsor>oem</Sponsor>            Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client>       Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId>        Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

Identifies the Billing Party for this transaction. Primarily used by Clients that need to differentiate between different divisions, end-users, etc. in order to either bill them in return or to allocate cost for reporting purposes. The BillingRef appears on billing reports generated by SIGNiX.

<BillingRef>SmithRealty</BillingRef>     Optional. Used to indicate who is the billable party.Can be left blank. Maximum length 50

 

Identifies the workgroup that will have access to this transaction.

<Workgroup>SDD</Workgroup>          Optional. Defaults to "SDD".

 

Demo identities and documents are flagged to avoid confusion with real ones. Must be 'yes' when submitted to a demo/test server; see Web Service URL, above.

<Demo>yes</Demo>     'yes' for demo/test, 'no' for real transaction

 

The post-completion availability period, in days. Refer to the DownloadDocument & ConfirmDownload methods for more about the post-completion availability period. Setting this and following up with a ConfirmDownload is required if custom retention policies are being used.

<DelDocsAfter>60</DelDocsAfter>     Required, minimum 0, maximum 366

 

 

Content of the pickup email.

<EmailContent>Your loan Documents are available.</EmailContent>       Length 1..10000

 

</CustInfo>

<Data>                  Occurs once only

Identifies the set of documents submitted in this request. This value is selected by the integrator and must be a unique identifier. NOTE: If a document set with the given TransactionID value has already been submitted by this Client, SIGNiX will return an error (SC_DOCUMENT_SET_ALREADY_SUBMITTED). This rule addresses the possible problem of duplicate deliveries from the OEM Application to SIGNiX if a communication error causes the OEM Application not to get the "success" result returned from SubmitDocument, which would cause the OEM Application to retry the call to SubmitDocument again at a later time. Note that this rule may not be enforced if the transaction has already been completed and the post-completion availability period has expired because after that time SIGNiX may choose to scrub the transaction ID from its database; however, this should not present a problem since communication errors should result in retries in a short timeframe compared to the much longer lifetime of the transaction.

<TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID> Required. Length must be exactly 36 characters

 

Used as the title of this transaction.

ATTENTION: because this title is displayed on reports, audit trails, and in the Document Center / Dashboard, it is important that the DocSetDescription be identifiable among a list of transactions. Do not, for example, set DocSetDescription to a generic title like "Car Loan". It is common practice to include the name of the primary party in the DocSetDescription.

<DocSetDescription>Car Loan: John Smith</DocSetDescription>      Required. Length 1..100

 

Used as the file name when end-user downloads the whole set of documents (i.e. Download All)

If provided, it is returned in the response for the DownloadDocument method

The extension of the <FileName> should be .ZIP

<FileName>J-Smith_02242005_032557.zip</FileName>         Optional, maxlen 255

 

Used to notify the submitter when the document set is completed or needs attention. While testing, please use a real email address...not a fake email, as the SIGNiX system will send an email and this can affect email sending reputation and workflow. IMPORTANT: This email is used to tie a transaction to a particular user and for license billing purposes.  This parameter should include a unique email address assigned to the submitter user.

<SubmitterEmail>demo@signix.com</SubmitterEmail>         Required, maxlen 50

 

Used to tie in a transaction to a particular user and for license billing purposes. IMPORTANT: This parameter must: (a) reference a single person; (b) include a full name in the format FirstName LastName, separated by a space; (c) not be a single word (i.e. 'Tom'); and (d) not be a combination of multiple names (ie: 'Thomas/Smith/Vivant').

<SubmitterName>Samuel Submitter</SubmitterName>         Required, maxlen 50 (total) and FirstName or MiddleName or LastName, but not more than 30 char each.

 

Text to display on emails as well as various Signing UI popups to signers. If no value is present here, SIGNiX uses the default of ‘If you have any questions, please contact your representative at [SubmitterEmail].’

<ContactInfo>If you need assistance, call 1-800-000-0000.</ContactInfo> Optional, maxlen 1000

Legacy parameter.

<DeliveryType>SDDDC</DeliveryType>       Required.

Indicates if transaction preprocessing is to suspend the transaction instead of notifying the first party upon submission of this request. Suspension is typically used ONLY in embedded scenarios where the SIGNiX interface will be accessed via GetAccessLink. In order to resume a suspended transaction, the submitter can gain access to the transaction by using a 60 second access link (See GetAccessLink-Submitter below), reaching the transaction's dashboard to make desired edits and Resume, or use an AJAX API call (see here) to send a Resume call.

IMPORTANT - Only set to 'yes' if you plan on the Submitter editing the document (ie via GAL-Submitter). If this transaction will be going straight to signing via email or GAL-Signer, set this to 'no' or omit the parameter entirely.

<SuspendOnStart>yes</SuspendOnStart>       Optional, defaults to 'no'

 

 

Text that is to be included in the distribution (aka CC) email sent when the transaction completes. The distribution email will also include an attachment of the signed document(s). If distribution is desired, indicate to whom the email should be sent using the <DistributionEmailList> and/or the <DistributeToSubmitter> element(s).

<DistributionEmailContent>Fully executed documents attached.</DistributionEmailContent>  Optional

 

 

A list of email addresses to whom the distribution (aka CC) email is to be sent when the transaction completes. Separate multiple addresses with a semi-colon. Note that distribution emails contain plaintext attachments of the signed PDFs. There is no security around the emails nor login requirements. If your transactions contain documents/PDFs with Personal Information, this element should not be used.

<DistributionEmailList>a@b.com; c@d.com</DistributionEmailList>      Optional

 

Indicate if the Submitter is to receive a copy of the distribution (aka CC) email when the transaction completes. The address provided in the <SubmitterEmail> element above will be used. Note that distribution emails contain plaintext attachments of the signed PDFs. There is no security around the emails nor login requirements. If your transactions contain documents/PDFs with Personal Information, this element should not be used.

<DistributeToSubmitter>yes</DistributeToSubmitter>        Optional, defaults to "no"

 

Some "Client Preference" settings in your service configuration can optionally be overridden for individual transactions. See Client Preference Overrides below for a list of the available preferences and the allowed values for each.

<ClientPreference name="DateSignedTimeZone">GMT</ClientPreference> Optional, repeating.

Currently, transactions will expire according to the Notification Schedule coded in the SIGNiX application, the default of which is {3,5,7,10}, which indicates that signing reminders will be emailed to the current party on days 3, 5, and 7; and on day 10 the transaction will expire. This Notification Schedule can be customized by default for a specific Client or it can be customized at a transaction level using the ClientPreference parameter. As shown below, SIGNiX will send the first notification email at 10 minutes, then another at 60 minutes, and expire the transaction after 180 minutes. The last number is always the time of the transaction expiration. If only one number is provided, no notifications will be sent and the transaction will expire at that time.

<ClientPreference name="NotificationSchedule">{10,60,180}minutes</ClientPreference>  Optional, a comma-separated list enclosed in curly braces, immediately followed by the units. In addition to ‘days’, the schedule can be specified in ‘hours’ or ‘minutes’.

 

 

Identifies a party to the transaction, someone who signs or views the documents. The order of the <MemberInfo> elements affects the workflow sequence.

<MemberInfo>             Occurs once for each party

 

 

A client-chosen identifier for this member. The RefID is returned in reports that include Member information.

<RefID>MemberID-1</RefID>         Optional, maxlen 50

 

 

Determines the order in which this signer will sign. If present, integers must start with 1 and be in sequential order (i.e. 1,2,3). If the same WorkflowOrder integer is used for multiple signers, those signers will be 'parallel' signers, in that they will both receive the notifications to sign at the same time. Anyone in the group can sign first, but only one can sign at a time. Once all members of the signing group have signed, the transaction will move to the next workflow order entry. 

<WorkflowOrder>1</WorkflowOrder>         Optional

 

 

 

Identity data that we can use to check whether the person has a SIGNiX identity and to create the identity. The user may have to provide additional information during registration if optional elements are not provided. Important information:

* Real values for SSN/DOB are ONLY used if the chosen authentication service requires it. Otherwise, use SSN=’910000000’ and DOB=’00/00/0000’.

* Email must be a real email address. Do not enter a random email address because SIGNiX will attempt delivery.

* Please do not send an email address as part of the <FirstName>, <MiddleName> or <LastName> elements. This will result in an error. (Added in Release 174.3 - July 2024)

 

<SSN>910000000</SSN>                       Required, format 123456789

<DOB>00/00/0000</DOB>                      Required, format mm/dd/yyyy

<FirstName>John</FirstName>               Required, maxlen 30

<MiddleName>Q</MiddleName>                Optional, maxlen 30, can be middle initial

<LastName>Smith</LastName>                Required, maxlen 30

<Email>demo@signix.com</Email>            Required, maxlen 50 (only one per party). Only one email is sent to a party to pick up the whole set of documents, not one per document.

<Street>1313 Mockingbird Ln</Street>     Optional, maxlen 30 (Mandatory if using KBAOneClick or KYC)

<Apartment>Unit 604</Apartment>         Optional, maxlen 30 (Mandatory if using KBAOneClick or KYC (and if it applies))
<City>Anytown</City>                      Optional, maxlen 30 (Mandatory if using KBAOneClick or KYC)
<State>NJ</State>                         Optional, format AA (USPS 2-letter code) (Mandatory if using KBAOneClick or KYC)
<Zipcode>07036</Zipcode>                  Optional, format 12345 or 12345-6789 (Mandatory if using KBAOneClick or KYC)

 

The <Service> parameter specifies the level of authentication required for this party in this transaction. Click here for currently available valid values.  SelectOneClick is commonly used as a base value for initial testing. In this mode, signers are asked to create a Signing Password which secures their signature and documents from access by others but provides no other factor of authentication. NOTE: Providing end users (ie: submitters) with the ability to choose stronger forms of authentication (Services) is a required part of any SIGNiX integration. 

<Service>SelectOneClick</Service>       Required, desired service (case sensitive)

For additional security, the <Service> can be changed to 'SMSOneClick' – this service sends a SMS/Text message with a one-time password (OTP) to the party's mobile phone. If used, the <Service> element must be followed by the real/valid mobile phone number to use as shown below. Do not use spaces. Hyphens can be used.

<MobileNumber>1112223333</MobileNumber>   Required for SMSOneClick. Otherwise not required.

</MemberInfo>

... Additional <MemberInfo> elements, if needed, appear here...

Describes one of the documents in the set of documents for this transaction. The order of the <Form> elements gives the order users will see them in lists and in the default workflow.
<Form>         Occurs once for each document

A client-chosen identifier for this form. The RefID is returned in reports that include form information.
<RefID>FormID-1</RefID>         Optional, maxlen 50

Used as the title of the document (when shown in the signing interface, etc.)
<Desc>Express Application #1</Desc>     maxlen 100

Used as the file name when end-user downloads the document. If provided, it is returned in the response for the DownloadDocument method. The extension of the <FileName> should be appropriate for the specified <MimeType>. The file name must be unique among the set of documents for this transaction.
<FileName>JSmith_Application_Form.pdf</FileName>          Optional, maxlen 255

Specifies the format of the document. The following types are supported: PDF - "application/pdf", FDF - "application/vnd.fdf". The F entry of the FDF dictionary must point to a PDF. The FDF will be merged into the referenced PDF to form the document.
<MimeType>application/pdf</MimeType>    The type of document, maxlen 100

Owner password if the document has one. Omit for documents without an owner password.
<FormPassword>d8gj3%i2$^cs</FormPassword>        Optional. Defaults to blank.

A sequence of <SignatureLine> and/or <View> elements describe which parties can or must sign this document. Parties who are not referred to in this section cannot view the document. There must be at least one <SignatureLine> or <View> element here. It is not necessary to add BOTH <SignatureLine> and <View> elements for the same party on the same document...choose one or the other, or neither.

 

For details on Editable Fields such as text boxes, check boxes, radio buttons, etc, click here.

 

For details on how to use text anchor tags (aka text tags, white text tags) in a SubmitDocument call (as opposed to PDF AcroForm Fields), please click here.

The order of the <SignatureLine> and <View> elements affects the workflow sequence. In this example, the first party must sign and then the second party must view. See the Party Actions section for more details. Indicates that a party must sign or can sign the document. To format the signature line for initials, replace <SignatureLine> with <InitialsLine>
<SignatureLine>

Indicated which Member will sign this line. Refer to a <MemberInfo> element above by the order it appears. Numbering starts at 1.
Within a Form, the MemberInfoNumber specified by the SignatureLine and View elements should always go in increasing order. In other words, it is not possible to have the first document signed by the primary applicant and then the spouse but the second document signed by the spouse and then the primary. To allow mixing up the signing order would require some parties to get control of the workflow more than once (in this case, primary would sign, spouse would sign twice, then primary would have to sign again). Within a Form, the SignatureLine element may be repeated multiple times with the same MemberInfoNumber so that the same party may sign the same document multiple times in different places.

<MemberInfoNumber>1</MemberInfoNumber>

Name of the PDF signature field to be signed by this Member.
<SignField>Signix_Sig_A_Signature1</SignField>         maxlen 100

PDF text field to hold the signing date, if any. The indicated PDF field will be filled in automatically with the date and time that the signature is created

<DateSignedField>Signix_Sig_A_Signature1_Date</DateSignedField>     Optional, maxlen 100

Specifies how to format the signing date/time. For the specifics of date/time formatting, refer to the Java 2 Platform Std. Ed. class java.text.SimpleDateFormat. It is strongly recommended that the format end with "z" in order to explicitly list the time zone that the date and time are reported in.
<DateSignedFormat>EEE, MMM d, yyyy, h:mm a z</DateSignedFormat>    Required if DateSignedField present, maxlen 100

Specifies the time zone in which to report the signing date and time. Available time zones include US/Eastern, US/Central, US/Mountain, US/Pacific, US/Alaska, US/Hawaii, GMT, UTC.
<DateSignedTimeZone>US/Pacific</DateSignedTimeZone>    Optional. The default is "US/Eastern".

PDF text field to hold the printed name of the signer. This field will be filled in automatically with the printed name of the signer.
<PrintedName>Signix_Sig_A_Signature1_PrintedName</PrintedName>     Optional, maxlen 100

An optional element used to indicate that the party can optionally sign. If optional signatures are not common in your process, simply omit this parameter. If included, the signer must take an action to 'Opt Out' of the signature / initial during the signing process. The Opt Out will be recorded on the audit trail.
<SignatureIsOptional>no</SignatureIsOptional>           Optional

 

</SignatureLine>

... Additional SignatureLine and/or InitialsLine elements, if needed, appear here. (max of 99, total) ...

The following <View> element indicates that a party must view or can view the document. IMPORTANT: This task cannot co-exist with Signature/Initial on same Form for same Party and is required ONLY when there is no signature or initial on that document for that party.

 

<View>

Indicated which party will be able to view this document. Refer to a <MemberInfo> element above
<MemberInfoNumber>2</MemberInfoNumber>    Refers to a MemberInfo above

<ViewIsRequired>yes</ViewIsRequired>       "no", "yes", "must-view", or "must-agree"  - “no” = Available to Read; “yes” OR “must-view” = Must Acknowledge; “must-agree” = Must Agree. Choosing the latter three will require the Party to click an Agree or Acknowledge button at the end of this specific Form/Document. The action will be reported in the transactional audit trail.

 

</View>

... Additional View elements, if needed, appear here (max of 99, total) ...

 

For each <Form> element, the document may be encoded in Base64 and included in the request or referenced via URL. PDF documents that are submitted must be consistent with the data in the request XML. For example, digital signature fields named by SignField elements must exist. Both options are presented below.

 

Length of Data, when decoded, in bytes
<Length>5631</Length>

The bytes of the entire document, encoded in Base64 format
<Data>JVBERi0xLjQNJeLjz9MNCj ... YgMCBvYmogPDwvTGluZWFy</Data>

Optionally, the document may be referenced via a URL, and SIGNiX will use the URL to retrieve the document. The URL must begin with 'http://' or 'https://'. SIGNiX will only download documents from approved sites. Please contact SIGNiX before using with a new download site. If this element is present, the <Length> and <Data> elements must be omitted. If desired, requests to the URL can require client authentication using any of the methods described in the SIGNiX guide titled "Authenticating SIGNiX as an HTTP/HTTPS Client".
<DocumentURL>https://www.- - -.com/form1.pdf</DocumentURL>

</Form>

... Additional <Form> elements, if needed, appear here. ...

 

</Data>

 

</SubmitDocumentRq>

 

[Back to top]

 

SubmitDocument - Additional Options & Capabilities

 

Document Subsets 

SIGNiX can provide additional 'folder' hierarchy within a transaction to allow integrated applications to present groups (aka subsets) of documents that may be mandatory or optional. If this seems pertinent to your use case, please contact SIGNiX for additional details.

 

 

Notarization - Notary Party (BETA)

Notaries are included in transactions via the MemberInfo element of SubmitDocument. Currently transactions can contain only ONE eNotary, and the eNotary MUST be the last signer.


The Notary must already be registered in SIGNiX. This allows the transaction to pull the appropriate commission information, etc from the notary's profile.
 If a registered Notary is found with the given email address, the system will use them as the notary and pick up all the other necessary information, including Service, from their account. If no matching Notary is registered at SIGNiX, the SubmitDocument request will return an error and the error message will indicate why the match failed.

 

The following example shows how to create an Notary party. A Notary MemberInfo must contain only the following elements, in the order they are shown.

 

 

 

<MemberInfo>

 

An optional client-chosen identifier for this party. The RefID is returned in reports that include party information.
<RefID>MemberID-1</RefID>    Optional, maxlen 50


If the WorkflowOrder element is used, the eNotary must have the highest WorkflowOrder number and must be the only party that has this number.
<WorkflowOrder>2</WorkflowOrder> Optional

 

Must be the email address of a registered eNotary.
<Email>jbhnotarydemo1@gmail.com</Email> Required

 

Set this element to true to indicate that this party is an eNotary. All the signatures associated with this party will be notarization signatures.
<NotaryInfoAdded>true</NotaryInfoAdded> Required for eNotary


</MemberInfo>

 

Notarization - Notary Signature & Stamp (BETA)

Notary signatures will be specified in SubmitDocument in the same way as any other party signature, except that it may contain a <NotaryStampField> element specifying the name of a field to display the Notary’s stamp. The stamp field must be an empty PDF text field that is already present in the document when it is uploaded. The document designer is responsible for ensuring that this field is present and is appropriately sized and placed. SIGNiX will not validate anything about this field other than its existence. The same stamp field can only be associated to one signature.


When a transaction starts, every field that a notary signs must have a unique notary stamp field. Therefore, every <SignatureLine> field for a notary must either specify a NotaryStampField or the transaction must be marked as SuspendOnStart so that the missing stamp fields can be added in the Wizard.


Note as well that using GetAccessLink to display the 'wizard' tagging UI to the submitter is another way in which Notary signature and stamp can be applied to the document via drag-and-drop, and is generally recommended for most use cases.

 

<SignatureLine>


<MemberInfoNumber>1</MemberInfoNumber>
<SignatureGroup>1</SignatureGroup>
<SignField>Signature2</SignField>
<DateSignedField>Signature2Date</DateSignedField>
<DateSignedFormat>MMMM dd, yyyy hh:mm a z</DateSignedFormat>
<NotaryStampField>Signature2NotaryStamp</NotaryStampField> Optional


</SignatureLine>

 

Notarization - Hold Email (BETA)

Commonly, notaries will prefer for signers to receive their links to sign when the notary is ready to host/launch the Zoom meeting and is engaged with the signers / principals. In this case, we offer the ability to set a notary transaction to 'hold' the signer emails until the notary releases them. Note that this 'release' will require the integration to display the Status page to the notary using the GetAccessLink-Submitter call as described below. In order to initiate the hold email function, simply add the following element after the <SuspendOnStart> parameter. (Added in Release 174.1 - June 2024)

 

...

     <HoldEmail>yes</HoldEmail>

...

 

Notarization - Schedule Meeting

A critical part of the remote online notarization process is the audio/visual communication / meeting. SIGNiX integrates with Zoom to accommodate this requirement. Typically, meetings are scheduled via a prompt in the manual MyDoX process, or via the GAL-Submitter API call, but not all use cases will require that. In these scenarios, please use the element below, placed below the <MemberInfo> section, but above the <Form> section. (Added in Release 170.)

 

...

     <MemberInfo>....</MemberInfo>

     <MeetingInfo>
       <Date>02/03/2022</Date> Required.
       <Time>12:01 PM</Time> Required.
       <Timezone>US/Eastern</Timezone> Required.
    </MeetingInfo>

 

    <Form>....

...

 

Signature Groups

Signatures can be grouped like radio buttons, allowing a party to sign at most one of the signature fields in the group. To put fields into such a group, give them matching SignatureGroup names. There must be at least two signatures in each group, and all the signatures in the same group must be for the same party (i.e. they must have the same MemberInfoNumber). Must be placed after <MemberInfoNumber>.

<SignatureGroup>1</SignatureGroup>       Optional

 

Signer Attachments (BETA)

By using the parameters below, an integrated application can prompt a signer to add supplemental documents to be returned back to the integrated application. These documents will not be signed; this is simply a way to ask signers to send back a copy of their utility bill, for example, or a copy of some other documentation. The attachment controls also allow the integrated, submitting application to customize the instructions shown to the signer, the number and type of documents / files requested, and finally whether the attachments are mandatory or not. NOTE: If attachments are made mandatory, the transaction will not be complete until that signer attaches the minimum number of file(s) requested. The transaction will remain 'in-process' until such time as attachments are added.

 

These parameters should be placed at the very bottom of the SubmitDocument xml, below the last <Form> (document) elements. If more than one signer will be prompted to add attachments, please use different values for the <RefID>, <Title> and update or remove any name-specific language. All elements & parameters are required unless otherwise stated.

 


<Length>16417</Length>

<Data>********</Data>

</Form>

 

<UserAttachments>

<RefID>ATT01</RefID> Required. If more than one signer will be prompted to add attachments, please use different values.

<MemberInfoNumber>1</MemberInfoNumber>

<Title>Jack's Attachments</Title> Optional, but recommended. Title at the top of screen (shown below as '1'). 

<Description>This is a description of Jack's Attachments</Description> Optional, but recommended. Informational text displayed to the signer regarding the nature of the requested attachments, etc. (shown below as '2')

<FileSet>

<Min>1</Min> Required. Does your signer have to add an attachment to sign (Mandatory vs Optional)? If yes, set min to ‘1’ (aka Mandatory). If no, set to ‘0’ (aka Optional).

<Max>2</Max> Required. Is more than 1 document possibly required? If no, choose ‘1’. If yes, might need to add other docs, choose max amount allowed.

<AcceptFewerThanMin>no</AcceptFewerThanMin> Required. If you want to allow Signer to sign without attaching, set to ‘yes’. Otherwise, choose ‘no’.

<FewerThanMinChallenge>You have to attach something</FewerThanMinChallenge> Optional, but recommended. Message displayed to Signer if they don’t attach all necessary documents.

<AcceptableTypes>PDF,JPG</AcceptableTypes> Required. Dependent on back-end storage requirements, choose the MIME types your company can work with and that fall within this SIGNiX-compatible grouping: PDF, JPG, JPEG, DOC, DOCX, XLS, XLSX, TIF, TIFF

<CapturePriority>Primary</CapturePriority> Required. Setting to primary allows user to capture pictures/scans on a mobile device at the time of attachment.

</FileSet>

</UserAttachments>

</Data>

</SubmitDocumentRq>

 

 

Attached documents will be returned with the DownloadDocument response, but only if additional parameters are added to the call per below. Note that attachments will also be noted as an event in the audit trail.

 


<DocumentSetID>...</DocumentSetID>

...

<IncludeAttachmentData>true</IncludeAttachmentData>  Mandatory, if attachments are used. NOTE: This parameter must be placed ABOVE the <IncludeAuditData> element, otherwise an error will be thrown.

...

</Data>

</DownloadDocumentRq>

 

SIGNiX Digital Billboard™

Released in November 2024, the Digital Billboard feature allows you to take advantage of the screen real estate shown to the signer after they complete the signing process on the Thank You for Signing page. With this new feature you can specify an image to show to each individual signer, a separate hover image, Alt text and a link that will open in a new tab when the signer clicks on it. In addition, you can control the location of the image above or below the text on the screen and even control the relative width of the image on the page.

 

Please use the elements below, placed at the end of any signer's <MemberInfo> section. (Added in Release 176.)

...

 

     <MemberInfo>...

    ...

       <PostSignatureImageLink> 
                <ImageURL>add in URL for image</ImageURL> Required. Provide the image URL for the image to display to the signer.
                <TargetURL>add in URL to redirect the signer to in a new tab</TargetURL> Required. Provide the link to redirect the signer.
                <ImageAltText>Post Signature Image Link</ImageAltText> Required. Provide the alt-text to display to the signer.
                <ImageHoverURL>add in URL for image</ImageHoverURL> Optional. Provide an image which appears when the signer hovers over the image.
                <IsImageLocationAboveText>yes</IsImageLocationAboveText> Required. Choose whether the images are displayed above the 'Thank you'                                                  text on this page.

                <ImageWidth>250</ImageWidth> Optional. Width of image in pixels. The aspect ratio will be maintained if the image is made larger or smaller.
         </PostSignatureImageLink>

    </MemberInfo>


...

 

 

[Back to top]

 

SubmitDocument - Response XML

An annotated example of the response XML is as follows. See the Status Codes section for the possible values and meanings of the StatusCode and StatusDesc elements.


<?xml version="1.0" ?>
<SubmitDocumentRs xmlns ="urn:com:signix:schema:sdddc-1-1">


<Status> Occurs once only
<StatusCode>0</StatusCode> One of the numeric SC_* values
<StatusDesc>success</StatusDesc> Human-readable version of StatusCode
</Status>


<Data>

The SIGNiX identifier for the transaction
<DocumentSetID>-5cb1ea45:119ddcc67bb:-7ad7-hkq0ep</DocumentSetID>

Pickup token. Present when a <PickupLink> is present. See Appendix C for optional DocID/Document Pickup Link.
<PickupToken>IeCAsVBUv0ImkEStJuyDPd</PickupToken> Length 22 characters

Pickup link for the first party
<PickupLink>https://webtest.signix.biz/enter.jsp?m=102&amp;i=IeCA...yDPd</PickupLink>

</Data>


</SubmitDocumentRs>

 

[Back to top]

 

digital signature faq

 

DownloadDocument

The DownloadDocument method allows for the pickup/downloading of all the completed documents for a Transaction along with its accompanying Audit Trail PDF. This method allows the completed documents to move from the SIGNiX system back to the integrated / OEM / Client application. This call IS REQUIRED for all Transactions.

 

In order to implement a retention policy (document deletion / purge schedules) set by the <DelDocsAfter> parameter in SubmitDocument, BOTH the UseConfirmDownload parameter must be set to ‘true’ in the DownloadDocument call AND the ConfirmDownload call must be made post-download in order to confirm successful receipt of all the documents by the receiving Application. If not, retention polivcies will not be enforced. These are mandatory requirements if retention is desired. (In addition, you must contact SIGNiX to enable your account for document deletion.)


If a document set is complete, the client receives the downloaded documents, and the Confirm Download has been received and responded to, then this method has the side effect of changing the status of the document set on the SIGNiX Dashboard.


• If the document set is in the post-completion availability period, then the document set status becomes "Pending Deletion".
• If the document set's post completion availability period has expired, then the document set is ready for immediate deletion.
• The post-completion availability period of a document set begins at the moment the document set becomes complete. Documents remain available on the server in the completed status until the client receives and confirms the downloaded documents, even if the post-completion availability period expired. 


When the document set is deleted, the following happens:

1. The individual documents (the PDF files) are deleted.
2. The status of the transaction is set to Deleted, and the transaction is removed from the "Pending Deletion" folder.
3. The transaction may still be accessed when, for example, a user follows a URL link from the original pickup notification. After the user logs in, the transaction still displays the names of the parties and of the documents, but clicking the name of a document no longer displays it. The interface instructs the user to contact the Client/Submitter to obtain a copy of the documents if they did not save a copy when they first went through the pickup and signing process.


The IncludeAuditData parameter is REQUIRED and must be set to ‘true’ so a copy of the transaction Audit Trail will be included in the response. The Audit Trail may be received in digitally-signed PDF format (most common for easy storage and pull for clients needing a copy for legal purposes), digitally-signed XML format (useful for Applications that need values from the XML Response for back-office actions), or Both PDF and XML (for applications that need easy/human-readable for clients but servers also need to read the Response data). Note that SIGNiX does archive and may delete transaction data because OEM/Applications are expected to retrieve and store all transaction data. In the event that an Audit Trail is needed and it has been archived, there may be a Professional Services fee applied for its retrieval. If data has been found to have been deleted (per contract or other record retention rules), it is no longer retrievable.

 

[Back to top]

 

DownloadDocument - Request XML

An annotated example of the request XML is as follows.


<?xml version="1.0" ?>
<DownloadDocumentRq xmlns="urn:com:signix:schema:sdddc-1-1">
<CustInfo> Occurs once only


<Sponsor>oem</Sponsor> Assigned by SIGNiX When Client is set up (Case Sensitive)
<Client>oemclient</Client> Assigned by SIGNiX when Client is set up (Case Sensitive)
<UserId>oemclient</UserId> Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)


Identifies the Billing Party for this transaction. Primarily used by Clients that need to differentiate between different divisions, end-users, etc. in order to either bill them in return or to allocate cost for reporting purposes. The BillingRef appears on billing reports generated by SIGNiX.
<BillingRef>SmithRealty</BillingRef> Optional. Used to indicate who is the billable party. Can be left blank. Maximum length 50


</CustInfo>


<Data> Occurs once only

Identifies the document set with an opaque identifier.
<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID>

Determines whether data entered into fields during the signing process will be provided back as discrete data as part of the response. Can be useful to help populate integrated applications with data entered on the PDF.
<IncludeFieldData>true</IncludeFieldData> Optional

Determines whether audit data (aka audit trail) will be included in the response. 
<IncludeAuditData>true</IncludeAuditData> Both element and value (true) are required.

Determines what format the audit trail will be provided in. IMPORTANT: Regardless of format, the receiving platform must store the resulting file (PDF, XML or both).
<AuditDataFormat>pdf</AuditDataFormat> Required. pdf (most common), xml, or both

Determines whether the client must use ConfirmDownload to acknowledge receipt.

<UseConfirmDownload>true</UseConfirmDownload> Mandatory and required to implement retention policy.

In addition to other audit trail, download a summary 'certificate of completion' that includes a subset of the larger audit trail's data. Not to be used as a substitute for the longer, more comprehensive audit trail (<IncludeAuditData>), but it may be added as additional evidence in certain use cases. 

<IncludeCertificateOfCompletion>true</IncludeCertificateOfCompletion> Optional

OPTIONAL: If the integrator wishes to only download the audit trail and NO other transaction documents, submit the call with the following element. Note that the <UseConfirmDownload> parameter MUST be omitted if you are using this option.

<ExcludeDocuments>true</ExcludeDocuments> Optional. Used to exclude documents from the download and, in coordination with the <IncludeAuditData> element, download only the audit trail.

</Data>


</DownloadDocumentRq>

 

[Back to top]

 

DownloadDocument - Response XML

An annotated example of the response XML is as follows. See the Status Codes section for the possible values and meanings of the StatusCode and StatusDesc elements.


See the Audit Trail schema [AuditTrailXMLSchema] and/or the Understanding SIGNiX Signatures and Audit Trails document available from SIGNiX for more information on the content and format of the audit trail.

 

<?xml version="1.0" ?>
<DownloadDocumentRs xmlns ="urn:com:signix:schema:sdddc-1-1">

<Status> Occurs once only
<StatusCode>0</StatusCode> One of the numeric SC_* values
<StatusDesc>success</StatusDesc> Human-readable version of StatusCode
</Status>

<Data> Occurs when Status.StatusCode is 0.

Identifies the set of documents returned in this response. This value is the same as the unique <TransactionID> value included in the original SubmitDocument request. Document Set ID can also be used.

<TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID>

If the <Data.FileName> element was present in the SubmitDocument method request, it is returned here with the same value.
<FileName>J-Smith_02242005_032557.zip</FileName> Optional, maxlen 255


Order of the <Form> elements matches the order in the original SubmitDocument request.
<Form> Occurs once for each document.

Document title. (Appears when the document is listed in the transaction, etc.)

<Desc>Express Application #1</Desc>

If the <Form.FileName> element was present in the SubmitDocument method request, it is returned here with the same value.
<FileName>J-Smith_Express_Application.pdf</FileName> Optional, maxlen 255

The next three elements provide the document itself. Presently, PDF is the only document format supported.
<MimeType>application/pdf</MimeType>

The type of document length of Data, when decoded, in bytes.
<Length>5631</Length>

The bytes of the entire document, encoded in Base64 format
<Data>JVBERi0xLjQNJeLjz9MNCj...YgMCBvYmogPDwvTGluZWFy</Data>
</Form>


... Additional <Form> elements, if needed, appear here. ...

 

Long-form transactional audit trail. This section occurs only if the <IncludeAuditData> element is present in the request with value "true" and the format is set to pdf.


<AuditReport> 

File name for the audit trail itself.
<FileName>J-Smith_Express_Application_audit_trail.pdf</FileName> 

Document format - PDF.
<MimeType>application/pdf</MimeType>

The type of document length of Data, when decoded, in bytes.
<Length>5631</Length>

The bytes of the entire document, encoded in Base64 format
<Data>JVBERi0xLjQNJeLjz9MNCj...YgMCBvYmogPDwvTGluZWFy</Data>
</AuditReport>

 


Transaction audit log. This section occurs only if the <IncludeAuditData> element is present in the request with value "true" and the format is set to XML.
<AuditTrail xmlns ="urn:com:signix:schema:audit-trail-1-1" xmlns:ds="http://www.w3.org/2000/09/xmldsig#"reportGenerationDateTime="2007-12-21T10:14:56Z" >
<AuditData>
... List of audit entries
</AuditData>
<ds:Signature>
... XML Digital Signature on the content of the audit trail.
</ds:Signature>
</AuditTrail>

 

</Data>
</DownloadDocumentRs>

 

[Back to top]

 

digital signature faq

 

ConfirmDownload

Confirms that a DownloadDocument call successfully returned all of the signed/acted upon PDFs and its accompanying Audit Trail. This call is REQUIRED and assumes that once received, SIGNiX can safely archive or delete transaction data.


The ConfirmDownload completes the download process by changing the transaction status from "Complete" to "PendingDeletion". See the description of the DownloadDocument method for details.

 

[Back to top]

 

ConfirmDownload - Request XML

An annotated example of the request XML is as follows.

<?xml version="1.0" ?>
<ConfirmDownloadRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo> Occurs once only

<Sponsor>oem</Sponsor> Assigned by SIGNiX When Client is set up (Case Sensitive)
<Client>oemclient</Client> Assigned by SIGNiX when Client is set up (Case Sensitive)
<UserId>oemclient</UserId> Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

Identifies the Billing Party for this transaction. Primarily used by Clients that need to differentiate between different divisions, end-users, etc. in order to either bill them in return or to allocate cost for reporting purposes. The BillingRef appears on billing reports generated by SIGNiX.
<BillingRef>SmithRealty</BillingRef> Optional. Used to indicate who is the billable party. Can be left blank. Maximum length 50

</CustInfo>

<Data> Occurs once only

Identifies the document set with an opaque identifier. This value is the same as the unique <DocumentSetID> value included in the original SubmitDocument response. Note that <TransactionID> can also be used here.
<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID>

</Data>

</ConfirmDownloadRq>

 

[Back to top]

 

ConfirmDownload - Response XML

An annotated example of the response XML is as follows. See the Status Codes section for the possible values and meanings of the StatusCode and StatusDesc elements.


<?xml version="1.0" ?>
<ConfirmDownloadRs xmlns="urn:com:signix:schema:sdddc-1-1" >

<Status> Occurs once only
<StatusCode>0</StatusCode> One of the numeric SC_* values
<StatusDesc>success</StatusDesc> Human-readable version of StatusCode
</Status>

</ConfirmDownloadRs>

 

[Back to top]

 

digital signature faq

 

GetAccessLink

Requests a non-reusable link to a transaction, in the context of either the transaction submitter, a workgroup signer, or a normal signing party. Because it expires after 60 seconds, the link returned by this method must be quickly consumed by the sponsor's application to redirect the user to SIGNiX. Do not use the URL provided in the response to this call in an email to the signer, as the signer will most likely NOT be clicking it within that 60 second period. 

For the transaction submitter and the workgroup signer, this single sign-on solution requires that the user be logged in to the sponsor's application. The link is very powerful in that it takes the user to either the MyDoX Wizard (in the case of a submitter link) without any authentication by SIGNiX. However, for a normal signing party, GetAccessLink (GAL) returns a link similar to the email pickup link that takes the user to the transaction log-in process that requires authentication before displaying the signing interface.

For the submitter transaction role, there are three parameters that control how the submitter may edit the transaction. The parameters are AllowTransactionContextEditing, AllowDocumentEditing, and AllowParticipantEditing. These parameters all default to false. If none of them are set to true, the user will not be able to access the MyDoX Transaction Editor.

For examples on how this might be used as part of a workflow, please see examples above. If even deeper levels of integration are required (i.e. integrated application elements controlling aspects of the SIGNiX interface), SIGNiX can share additional information once integration is underway.

 

Important Considerations When Using GetAccessLink:

GetAccessLink requests should always be handled one at a time during a transaction workflow. Due to the temporary nature of the link, plus natural workflow issues, NEVER request multiple signer GAL links at the same time. For example, don't request links for all parties in a transaction at the same time. Always build a step into your own application workflow to ask the submitter which signer should be signer, or have the application logic choose the appropriate signer whose link should be requested in real-time.

Also, do NOT submit a request for a Submitter GAL at the same time as a Signer GAL.

Finally, do not request a Signer GAL for a signer out of order with the transaction workflow, as it will not be able to be processed. That is, if you have two signers sequentially in a transaction and Signer One hasn't completed their tasks, a Signer GAL for Signer Two will not allow Signer Two to access the transaction. Always match the Signer GAL with the expected workflow order and transaction status.

 

How Do I Know When My Signer is Finished Signing in an Embedded Window?

SIGNiX passes a message into the browser when a signer completes their task and hits the Finish Signing screen.

Signix says: transactionComplete

This message can be used to let the application embedding the SIGNiX signing experience know the signer is done, and to then close the iFrame and move on to the next screen.

 

[Back to top]

 

GetAccessLink - Submitter Request

An annotated example of the request XML for a submitter to access elements of the SIGNiX interface is as follows. <SuspendonStart> must be set to yes in the SubmitDocument call if the workflow requires the user/submitter to edit the transaction immediately prior to signer interactions. When transactions are created with SuspendOnStart, the normal constraints for a runnable transaction are not checked. The transaction can be an empty shell with no parties or documents, contain partial information that will be filled in later, or it can be fully populated and ready to run.

 

<?xml version="1.0" ?>
<GetAccessLinkRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo> Occurs once only

<Sponsor>oem</Sponsor> Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client> Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId> Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

 

<Data> Occurs once only

Specify a specific document set with the SIGNiX identifier for the transaction (DocumentSetID) returned in the SubmitDocument response.
<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID>

Indicate for whom the link is intended. 
- Submitter - link takes the user to the MyDoX Wizard without authentication.
<TransactionRole>Submitter</TransactionRole> Required

Controls availability of the Wizard Signer (Party) tab. 
<AllowParticipantEditing>false</AllowParticipantEditing>

Controls availability of the Wizard Document tab.
<AllowDocumentEditing>false</AllowDocumentEditing>

Controls availability of the Wizard Document Editor (tagging) tab. 
<AllowDocumentFieldAndTaskEditing>true</AllowDocumentFieldAndTaskEditing>

Controls availability of the Wizard Send tab.
<AllowTransactionContextEditing>true</AllowTransactionContextEditing>

Controls availability of the Wizard Status tab. This would typically ONLY be invoked AFTER a transaction is started or completed.
<AllowTransactionStatusViewing>true</AllowTransactionStatusViewing>

An optional parameter that assist the SIGNiX application in formatting the content to be presented. Value must be one of the following: “no”, “iframe”, “sepframe”, “sameframe”, “signixframe”

<Embedded>sameframe</Embedded> Optional, recommended.

Specifies the scheme, hostname and port of the page that will contain the embedded content. May be set when embedding is enabled. Must be set to enable control of the embedded content from the parent window, and in order for the parent to receive notifications from the embedded content.
<ContainerOrigin>http://h5.yourco.com</ContainerOrigin> Required if using <Embedded>

<FinishURL>http://www.yourco.com</FinishURL> Optional. URL to load in the Wizard's frame when the Wizard exits. NOTE: This does not redirect currently if user Quits or Cancels transaction. <Embedded> tag must be included.

</Data>

</GetAccessLinkRq>

 

[Back to top]

 

GetAccessLink - Signer Request

An annotated example of the request XML for a particular signer to access the signing interface is as follows.

 

<?xml version="1.0" ?>
<GetAccessLinkRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo> Occurs once only

<Sponsor>oem</Sponsor> Assigned by SIGNiX When Client is set up (Case Sensitive)
<Client>oemclient</Client> Assigned by SIGNiX when Client is set up (Case Sensitive)
<UserId>oemclient</UserId> Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data> Occurs once only

Specify a specific document set with the SIGNiX identifier for the transaction (DocumentSetID) returned in the SubmitDocument response.
<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID>

Indicate for whom the link is intended. 
- 1 - link takes the user to the signing view after authentication as the first party.
- 2 - link takes the user to the signing view after authentication as
the second party.
- etc.
<TransactionRole>MemberInfoNumber</TransactionRole> Required, integer for signer party. 

An optional element used to generate a permanent link for the signer (akin to what's provided in the signer's pick up link email) instead of generating only the temporary, 60 second link. This is better used for integrators who plan to send their own notifications to clients or for those who are NOT embedding the signing interface in their application / service. (Added in Release 174.3 - July 2024.)

<GetNormalPickupLink>false</GetNormalPickupLink> Optional...if not using, can be omitted. Set to true if you wish to receive the long-standing link.

An optional parameter to be used in very specific use cases when a signer is 'in-person' and presenting other authentication methods to staff / application operators that negate the need for SIGNiX authentication. Adding 'yes' to this parameter will BYPASS any authentication (<Service>) set by the SubmitDocument call. Confer with SIGNiX to determine if this parameter makes sense in your integration.

<InpersonAuthentication>yes</InpersonAuthentication> Optional...if not using, can be omitted.

An optional parameter that assist the SIGNiX application in formatting the content to be presented. Value must be one of the following: “no”, “iframe”, “sepframe”, “sameframe”, “signixframe”

<Embedded>sameframe</Embedded> Optional, recommended.

Specifies the scheme, hostname and port of the page that will contain the embedded content. May be set when embedding is enabled. Must be set to enable control of the  embedded content from the parent window, and in order for the parent to receive notifications from the embedded content.
<ContainerOrigin>http://h5.yourco.com</ContainerOrigin> Required if using <Embedded>

<FinishURL>http://www.yourco.com</FinishURL> Optional. Once signer completes signing, integrated application wants to land the signer back on a page typically on the integrated application's platform (i.e. account opening). For example, a page with a message for that signer: ‘Thank you for signing and here are your next steps.’ <Embedded> tag must be included. NOTE: This does not redirect currently if user Quits or Cancels transaction.

<CancelURL>http://www.yourco.com</CancelURL> Optional. If a signer Quits and chooses an option that causes the transaction to go into a Cancelled state, open a new web page. For example, a page with a message for that signer: ‘Sorry you had issues signing.’ <Embedded> tag must be included.

</Data>

</GetAccessLinkRq>

 

[Back to top]

 

GetAccessLink - Response

An annotated example of the response XML is as follows. See the Status Codes section for the possible values and meanings of the StatusCode and StatusDesc elements.

<?xml version="1.0" ?>
<GetAccessLinkRs xmlns="urn:com:signix:schema:sdddc-1-1">

<Status> Occurs once only

<StatusCode>0</StatusCode> One of the numeric SC_* values
<StatusDesc>success</StatusDesc> Human-readable version of StatusCode

</Status>

<Data> Occurs when Status.StatusCode is 0.

<AccessLink>https://webtest.signix.biz/enter.jsp?m=103&amp;i=uLf8K...3WWr</AccessLink>

</Data>

</GetAccessLinkRs>

 

[Back to top]

 

digital signature faq

 

Other API Calls

The sections below provide additional details on less commonly used API calls that may be important in certain vertical markets / use cases.

 

[Back to top]

 

CertifyDocument

This function is often used when a PDF document simply needs to be locked down and a time reference added to it to show that it was produced at a certain time. It does so by requesting a covering signature be applied to a document.


The type of signature to be applied is controlled by the signature policy, as specified the policy OID in the SignaturePolicyID element. The following policies are supported:


• 1.3.6.1.4.1.6693.4.2.20 - SIGNiX Certifying time-stamp. SIGNiX will insert a new, hidden signature field into the document and sign it with a PDF Document Modification Prevention and Detection (DocMDP) signature.


The certificate on the signature belongs to the SIGNiX Signature Authority, and is issued under the Adobe AATL program, like other signer signatures. It will cause a blue ribbon mark to appear above the document in the default configuration of Adobe Acrobat and Reader.


DocMDP signatures limit the types of changes that can be made after signing. The limitation desired can be specified in the "SubsequentChanges " element. Choices are NO_CHANGES, FORM_FILLING, or FORM_FILLING_AND_ANNOTATIONS.


This type of signature must be the first digital signature on a document, so the document must not have any digital signatures on it when submitted.


Digital signatures made under this policy have the legal effect of a pure time stamp: SIGNiX only asserts (in the signature reason field) that the signature represents a time stamp, showing that the document existed in the signed form at the time of signing. Verification of the signature provides evidence that the document has not changed since signing, other than in the ways allowed by the SubsequentChanges setting.


Any assertions about the trustworthiness of other information in the document, including any text or images of signatures, and communication of any information on how to evaluate the trustworthiness of the content are left to the customer.

 

[Back to top]

 

CertifyDocument - Request

An annotated example of the request XML is as follows.


<?xml version="1.0" ?>
<CertifyDocumentRq xmlns="urn:com:signix:schema:sdddc-1-1">


<CustInfo> Occurs once only

<Sponsor>oem</Sponsor> Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client> Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId> Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>


<Data> Occurs once only

The signature policy to be used to sign the form.
<SignaturePolicyID>1.3.6.1.4.1.6693.4.2.20</SignaturePolicyID> Required

For use with policies that create a DocMDP signature, to specify what changes will still be allowed after the signature is made. Options are NO_CHANGES, FORM_FILLING, or FORM_FILLING_AND_ANNOTATIONS.
<SubsequentChanges>NO_CHANGES</SubsequentChanges> Optional. Defaults to NO_CHANGES. Case-sensitive.

Describes the document to be signed.
<Form>

A client-chosen identifier for this form. The RefID appears in the audit trail record of the signing, and is returned in the response.
<RefID>FormID-1</RefID> Optional, no default. maxlen 50

The title of the document. Appears in the audit trail entry for the signing.
<Desc>Express Application #1</Desc> maxlen 100

Specifies the format of the document. The following types are supported: * PDF - application/pdf
<MimeType>application/pdf</MimeType> The type of document, maxlen 100

Owner password if the document has one. Omit for documents without an owner password.
<FormPassword>d8gj3%i2$^cs</FormPassword> Optional. Defaults to blank.

Length of document to be signed, when decoded, in bytes.
<Length>5631</Length>

The bytes of the entire document, encoded in Base64 format
<Data>JVBERi0xLjQNJeLjz9MNCj...YgMCBvYmogPDwvTGluZWFy</Data>

Optionally, the document may be referenced via a URL, and SIGNiX will use the URL to retrieve the document. The URL must begin with 'http://' or 'https://'. SIGNiX will only download documents from approved sites. Please contact SIGNiX before using with a new download site. If this element is present, the <Length> and <Data> elements must be omitted.
<DocumentURL>https://www.- - -.com/form1.pdf</DocumentURL>

</Form>


</Data>

</CertifyDocumentRq>

 

[Back to top]

 

CertifyDocument - Response

An annotated example of the response XML is as follows. See the Status Codes section for the possible values and meanings of the StatusCode and StatusDesc elements.


<?xml version="1.0" ?>
<CertifyDocumentRs xmlns="urn:com:signix:schema:sdddc-1-1">

<Status> Occurs once only
<StatusCode>0</StatusCode> One of the numeric SC_* values
<StatusDesc>success</StatusDesc> Human-readable version of StatusCode
</Status>

<Data> Occurs when Status.StatusCode is 0. Returns the signed document.

<Form>

A client-chosen RefID, echoed from the request.
<RefID>FormID-1</RefID>

Document title, echoed from the request.
<Desc>Express Application #1</Desc>

Specifies the format of the document. Matches the MimeType from the request.

<MimeType>application/pdf</MimeType>

Length of the signed document, when decoded, in bytes.
<Length>5631</Length>

The bytes of the entire signed document, encoded in Base64 format.
<Data>JVBERi0xLjQNJeLjz9MNCj...YgMCBvYmogPDwvTGluZWFy</Data>

</Form>

</Data>

</CertifyDocumentRs>

 

[Back to top]

 

digital signature faq

 

Update Notary List

The goal of the Notary List is to allow clients to make lists of frequently used, recommended, or required eNotaries. The Notary List section of the SIGNiX FlexAPI is not designed to serve as a search function across all SIGNiX notaries. Rather, it's designed as a way for companies to create bespoke lists of notaries and associate certain criteria with them. Due to this fact, it's not intended to be used with every notary use case - only those where (a) notaries are known in advance, (b) those notaries have a need to be categorized, and (c) there is a need outside of the host application to display lists of those notaries.

For example, let's say a Company has an East office with 3 known SIGNiX notaries and a West office with two.

Company could create a Notary List using the Update Notary List function for all 5 notaries, and associate the East and West criteria with all of them respectively, as well as perhaps State Commission, etc as other criteria. Then, when Company wanted to pull a list of notaries in the East office, the Read Notary list function could be called to list the 3 notaries and their email addresses. The user could then choose one of those, and that notary info could be added to a SubmitDocument request.

Notary lists will be created and maintained via B2B API calls. Each eNotary can be given up to three criteria that can be used to get filtered lists for different purposes.

 

[Back to top]

 

Update Notary List - Request

Update the criteria for the specified notary if they are already in the client’s list, otherwise add them to the list or in fact, create one.

 

<?xml version="1.0"?>
<NotaryListUpdateEntryRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo> Occurs once only
<Sponsor>oem</Sponsor> Assigned by SIGNiX When Client is set up (Case Sensitive)
<Client>oemclient</Client> Assigned by SIGNiX when Client is set up (Case Sensitive)
<UserId>oemclient</UserId> Assigned by SIGNiX when Client is set up (Case Sensitive)
<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)
</CustInfo>


<Data> Occurs once only

Must be the email address of a registered eNotary.
<Email>jbhnotarydemo1@gmail.com</Email> Required.

Depending on configuration settings, this feature can be used to limit the available eNotaries that a transaction submitter can search for or use. A given submitter is linked to all eNotaries with Global availability, all that are linked to the workgroup the submitter is operating in, and all that are linked directly to the submitter themselves.
<Availability> Optional.

Indicates this eNotary is available to all users in all Workgroups for the named client or sponsor.
<Global> Optional.

Indicates this eNotary is available to all users in the specified workgroup.
<Workgroup>SDD</Workgroup> Optional. Occurs once per linked workgroup. Max 50 chars.

Indicates this eNotary is available to the indicated submitters in every workgroup.
<Submitter> Optional. Occurs once per linked submitter.

<UserId>jharris</UserId> Required. The SIGNiX user ID of a submitter.

</Submitter>

</Availability>


Optional filtering criteria associated with this eNotary. These criteria can be used by integrators to get filtered lists of eNotaries.
<Criteria1>New Jersey</Criteria1> Optional, max 25 characters.
<Criteria2>Office 25</Criteria2> Optional, max 25 characters.
<Criteria3>Blue Team</Criteria3> Optional, max 25 characters.

</Data>

</NotaryListUpdateEntryRq>

 

[Back to top]

 

Update Notary List - Response

 

<?xml version="1.0" ?>
<NotaryListUpdateEntryRs xmlns="urn:com:signix:schema:sdddc-1-1">

<Status> Occurs once only

<StatusCode>0</StatusCode> One of the numeric SC_* values
<StatusDesc>success</StatusDesc> Human-readable version of StatusCode

</Status>

<Data> Occurs when Status.StatusCode is 0.

Action taken. Value is either Added or Updated.
<Action>Added</Action>

</Data>

</NotaryListUpdateEntryRs>

 

[Back to top]

 

digital signature faq

 

Read Notary List

Retrieve lists of linked eNotaries filtered by given criteria.

 

[Back to top]

 

Read Notary List - Request

 

<?xml version="1.0"?>
<NotaryListReadRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo> Occurs once only

<Sponsor>oem</Sponsor> Assigned by SIGNiX When Client is set up (Case Sensitive)
<Client>oemclient</Client> Assigned by SIGNiX when Client is set up (Case Sensitive)
<UserId>oemclient</UserId> Assigned by SIGNiX when Client is set up (Case Sensitive)
<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data> Occurs once only

Filter the list by availability to submitters.
<Availability> Optional.

Include any eNotary that is available to all users in all Workgroups.
<Global> Optional.

Include any eNotary that is available to all users in the specified workgroup.
<Workgroup>SDD</Workgroup> Optional. Max 50 chars. Occurs once per desired workgroup.

Include any eNotary that is available to the indicated submitters in every workgroup.
<Submitter> Optional. Occurs once per desired submitter.
<UserId>jharris</UserId> Required. The SIGNiX user ID of a submitter.
</Submitter>

</Availability>

Other filtering criteria. The response will only contain entries that exactly match the given criteria. Any criteria not given will match all values of that criteria. To return the whole list, omit all the criteria.
<Criteria1>New Jersey</Criteria1> Optional, max 25 characters.
<Criteria2>Office 25</Criteria2> Optional, max 25 characters.
<Criteria3>Blue Team</Criteria3> Optional, max 25 characters.


</Data>

</NotaryListReadRq>

 

[Back to top]

 

Read Notary List - Response

 

<?xml version="1.0" ?>
<NotaryListReadRs xmlns="urn:com:signix:schema:sdddc-1-1">

<Status> Occurs once only

<StatusCode>0</StatusCode> One of the numeric SC_* values
<StatusDesc>success</StatusDesc> Human-readable version of StatusCode

</Status>

<Data> Occurs when Status.StatusCode is 0.

<NotaryData> Occurs once for each eNotary in the list.

<FirstName>John</FirstName> Required
<MiddleInitial>B</MiddleInitial> Optional
<LastName>Stamper</LastName> Required

<Email>jbhnotarydemo1@gmail.com</Email> Required

<NotaryState>NJ</NotaryState> Required
<NotaryCommissionNumber>274649375</NotaryCommissionNumber> Required
<NotaryCommissionExpirationDate>10-01-2056</NotaryCommissionExpirationDate> Required

<Availability> Optional.

Indicates this eNotary is available to all users in all Workgroups.
<Global> Optional.

Indicates this eNotary is available to all users in the specified workgroup.
<Workgroup>SDD</Workgroup> Optional. Max 50 chars. Occurs once per linked workgroup.

Indicates this eNotary is available to the indicated submitters in every workgroup.
<Submitter> Optional.  Occurs once per linked submitter.
<UserId>jharris</UserId> Required. The submitter’s SIGNiX user ID.
</Submitter>

</Availability>

<Criteria1>New Jersey</Criteria1> Optional, max 25 characters.
<Criteria2>Office 25</Criteria2> Optional, max 25 characters.
<Criteria3>Blue Team</Criteria3>  Optional, max 25 characters.

</NotaryData>

</Data>

</NotaryListReadRs>

 

[Back to top]

 

digital signature faq

 

Remove from Notary List

Remove an eNotary from a client’s notary list.

 

[Back to top]

 

Remove from Notary List - Request

 

<?xml version="1.0"?>
<NotaryListRemoveEntryRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo> Occurs once only

<Client>oemclient</Client> Assigned by SIGNiX when Client is set up (Case Sensitive)
<UserId>oemclient</UserId> Assigned by SIGNiX when Client is set up (Case Sensitive)
<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data> Occurs once only

Must be the email address of a registered eNotary.
<Email>jbhnotarydemo1@gmail.com</Email> Required.

</Data>

</NotaryListRemoveEntryRq>

 

[Back to top]

 

Remove from Notary List - Response

 

<?xml version="1.0" ?>
<NotaryListRemoveEntryRs xmlns="urn:com:signix:schema:sdddc-1-1">

<Status> Occurs once only

<StatusCode>0</StatusCode> One of the numeric SC_* values
<StatusDesc>success</StatusDesc> Human-readable version of StatusCode

</Status>

<Data> Occurs when Status.StatusCode is 0.

Action taken. Value is either Removed or Not Found.
<Action>Removed</Action>

</Data>

</NotaryListRemoveEntryRs>

 

[Back to top]

 

digital signature faq

 

Additional Information

The sections below contain pertinent information relating to authentication, status codes and other items relevant to development.

 

[Back to top]

 

Client Preference Overrides

The ClientPreference request element allows service configuration parameters to be overridden for a specific transaction. Each parameter is specified as a name/value pair. The format is as follows:

<ClientPreference name="NAME">VALUE</ClientPreference>

There are other preferences that SIGNiX can configure outside of a specific transactional context. Please contact SIGNiX for more details of additional customization options are required.

The available parameters are shown in the following table:

 

Name / Meaning

Allowed Values

AllowSignatureGraphic

Determines whether a user can drawn their signature when they register. If set to required, they will not be allowed to use a font-based signature.

yes

no

required

AuditTrailWithCC

The audit trail of the transaction will be included as a PDF attachment to the CC (Carbon Copy) email.

yes
no

BrowserAutofill

Toggles the browser's autocomplete attribute of HTML

form input fields.

yes
no

DateSignedFormat

Sets the format of the date field associated with a signature line.

MM/dd/yyyy hh:mm a z

MMMM dd, yyyy hh:mm a z dd MMMM yyyy hh:mm a z dd/MMM/yyyy hh:mm a z

dd/MM/yy hh:mm a z

dd/MM/yyyy hh:mm a z

DateSignedTimeZone

This preference sets the default time zone for the Wizard's date field Properties Dialog.

 

GMT
US/Eastern
US/Central
US/Mountain
US/Pacific
US/Alaska
US/Aleutian
US/Hawaii

EmailFromName

Allows all transaction emails (pickup, reminder, expiration) to feature a custom 'friendly' from name in the From email address. 

 

50 characters

MiddleName

Determines how middle names appear.

no preference
as submitted
middle initial
full middle name

 

NextPartyLink

This preference determines whether the party completion page supports immediate login by the next party. When a party finishes all their signatures and other actions in a transaction, a completion page appears. If there is a next party, the next party is authenticated via interactive questions, and this preference is set to "yes", then the completion page will contain a link that the next party can click on to log in to the transaction. Otherwise, the completion page just indicates that the next party has been notified, but does not provide a login link.

 

yes
no

 

 

[Back to top]

 

digital signature faq

 

Authentication / Service Types

When using SIGNiX e-Sign, there are several options for authentication (<Service>) for each signer. Whatever method is chosen for each Party, in a Transaction, is applicable to the entire transaction for that specific Party. Below is each authentication option available for each Party as well as the specific Authentication Behavior, Signing Flow and XML Specs to deliver. The ($) next to the title in the descriptions below specifies which authentication types may incur additional costs.

 

Email Only

One-time Password to SMS

Knowledge-based Authentication (KBA) with Credential Analysis (KBA-ID)

Credential Analysis with Face Biometrics (IDVerify)

 

The following authentication options are no longer available for new integrations, but the API details are provided for informational purposes.

Know Your Customer (KYC) - DEPRECATED

Knowledge-based Authentication (KBA) Questions - DEPRECATED

Email Only w/ Submitted Questions - DEPRECATED

Know Your Customer (KYC) w/Submitted Questions - DEPRECATED

 

Email Only 

Behavior

Signer will not go through external authentication – SSN/DOB not required.

 

Flow

1. Signer accepts Consent (may open it to read it)

o Creates Signing Password (SelectOneClick) or no Signing Password (express)
o Gains access to doc(s)

2. Signer clicks on each initial/signature
3. Signer clicks “Finish” button

 

NOTE: Using express will omit the creation and use of a Signing Password. This means that access to signed documents on the return link will not be secured, other than through email. Also, the signature appearance will not be saved.

 

XML Specs

To be delivered in SubmitDocument Call for Party (Test & Production).

 

• SSN = 910000000
• DOB = 00/00/0000
• Service = ‘SelectOneClick’ (Signing Password) or 'express' (no Signing Password)

 

Secret Code (OTP) Sent Via Text Message (SMS) ($)

Behavior

Signer will be prompted to enter a one-time password code sent via SMS text message to their mobile phone.

 

Flow

1. Signer accepts Consent (may open it to read it)

o Receives text to their Mobile Phone with a one-time code. Enters code.

o Creates Signing Password (SMSNoIntent) or no Signing Password (SMSNoPassword)
o Gains access to doc(s)

2. Signer clicks on each initial/signature 
3. Signer clicks “Finish” button.

 

NOTE: Using SMSNoPassword will omit the creation and use of a Signing Password. This means that access to signed documents on the return link will not be secured by a password, but the signer will be required to enter a new one-time password / text code. Also, the signature appearance will not be saved.

 

XML Specs

To be delivered in SubmitDocument Call for Party (Test & Production).

 

• SSN = 910000000
• DOB = 00/00/0000
• Service = ‘SMSNoIntent’ (requires creation of Signing Password) OR 'SMSNoPassword' (Signing Password not created or required)

• <MobileNumber> (Domestic 10-digit numbers only. International SMS support is available for an additional fee.)

    • NOTE: If international numbers are sent, the following format rules apply
      • All international numbers must start with a '+' (plus) sign and country code. Also do not include the prefix for 'international' dialing (i.e 011).
      • A space may or may not be used after the country code. After that, NO spaces allowed.
      • Examples
        • WRONG: <MobileNumber>+01154 9 11 3011 ****</MobileNumber>
        • WRONG: <MobileNumber>+54 9 114937****</MobileNumber>
        • CORRECT: <MobileNumber>+54 9113011****</MobileNumber>
        • CORRECT: <MobileNumber>+549113011****</MobileNumber>



Knowledge-based Authentication (KBA) with Credential Analysis (KBA-ID) ($)

Behavior

Required for most states for remote online notarization (RON). Signer will go through external authentication – SSN, Name, DOB required. Confirms association of name with DOB and SSN. Confirms if alive and other checks. Signer must then answer several multiple choice questions from 30 years of public database information. Finally, signer will be prompted to take a picture of their driver's license or passport for automated analysis. NOTE: This authentication method may ONLY be used for notarization transactions. It cannot be used in non-notary scenarios.

 

Flow

1. Signer accepts Consent (may open it to read it)

o Enters last 4 of SSN & full DOB (unless SubmitDocument required that signer would enter, in which case full 9 digit SSN required)

o Answers public record-based questions

o Takes pictures of ID

o Creates Signing Password 
o Gains access to doc(s)

2. Signer clicks on each initial/signature.
3. Signer clicks “Finish” button.

 

XML Specs

To be delivered in SubmitDocument Call for Party (Test & Production).

 

• SSN = 'real’ data (Production) OR 000000000 (Production, if signer will provide for KBA-ID) OR 0000 (Production, if signer will provide for KBA-ID-SSN4); “0001 + random 5” (Webtest) – avoid ‘0001234..’, ‘0001111…’, etc.

• DOB =‘real’ data (Production) OR 00/00/0000 (Production, if signer will provide); Use any DOB over 18 yrs old (Webtest)
• Service = 'KBA-ID-SSN4' (preferred) OR ‘KBA-ID’ (requires 9 digit SSN)

 

 

Credential Analysis with Face (selfie) Biometrics (IDVerify) ($)

Behavior

Can be used for both RON (in certain states) as well as traditional digital signature transactions. Signer will be prompted to take a picture of their driver's license or passport for automated analysis and then also asked to take a picture of their face multiple times at different angles. These pictures will be compared to the face on the identity credential and must match.

 

Flow

1. Signer accepts Consent (may open it to read it)

o Takes pictures of ID and face as prompted

o Creates Signing Password 
o Gains access to doc(s)

2. Signer clicks on each initial/signature.
3. Signer clicks “Finish” button.

 

XML Specs

To be delivered in SubmitDocument Call for Party (Test & Production).

 

• SSN = 910000000
• DOB = 00/00/0000
• Service = ‘IDVerify’ 

 

 

 

 

Know Your Customer (KYC) ($) - NOT AVAILABLE / DEPRECATED

Behavior

Signer will go through external authentication – SSN, Name, DOB required. Confirms association of name with DOB and SSN. Also confirms if alive and other checks.

 

Flow

1. Signer accepts Consent (may open it to read it)

o Enters last 4 of SSN & full DOB (unless SubmitDocument required that signer would enter, in which case full 9 digit SSN required)

o Creates Signing Password (KYCNoIntent) or no Signing Password (express)
o Gains access to doc(s)

2. Signer clicks on each initial/signature 
3. Signer clicks “Finish” button 

 

XML Specs

To be delivered in SubmitDocument Call for Party (Test & Production).

 

• SSN = 'real’ data (Production) OR 000000000 (Production, if signer will provide); “0001 + random 5” (Webtest) – avoid ‘0001234..’, ‘0001111…’, etc.

• DOB =‘real’ data (Production) OR 00/00/0000 (Production, if signer will provide); Use any DOB over 18 yrs old (Webtest)

• Service = ‘KYCNoIntent’ (Signing Password) or 'express' (no Signing Password)

 

 

 

 

Knowledge-based Authentication (KBA) ($) - NOT AVAILABLE / DEPRECATED

Behavior

Signer will go through external authentication – SSN, Name, DOB required. Confirms association of name with DOB and SSN. Confirms if alive and other checks. Signer must answer several multiple choice questions from 30 years of public database information.

 

Flow

1. Signer accepts Consent (may open it to read it)

o Enters last 4 of SSN & full DOB (unless SubmitDocument required that signer would enter, in which case full 9 digit SSN required)

o Answers public record-based questions

o Creates Signing Password 
o Gains access to doc(s)

2. Signer clicks on each initial/signature 
3. Signer clicks “Finish” button.

 

XML Specs

To be delivered in SubmitDocument Call for Party (Test & Production).

 

• SSN = 'real’ data (Production) OR 000000000 (Production, if signer will provide); “0001 + random 5” (Webtest) – avoid ‘0001234..’, ‘0001111…’, etc.

• DOB =‘real’ data (Production) OR 00/00/0000 (Production, if signer will provide); Use any DOB over 18 yrs old (Webtest)

• Service = ‘KBANoIntent’ 

 

 

 

Email Only w/Submitted Questions - NOT RECOMMENDED / DEPRECATED

NOTE

Question and answer pairs such as these may be abused in certain situations as the submitter or an organization representative can find the answer(s) readily and could possibly authenticate themselves as the signer. Therefore, SIGNiX does NOT recommend using this authentication type unless proper risk mitigation and acceptance discussions have taken place in your organization.

 

Behavior

Signer will not go through external authentication, but will be asked to answer questions which are provided by submitting system. SSN/DOB not required.

 

Flow

1. Signer accepts Consent (may open it to read it)

o Answers Submitter's Question(s)

o Creates Signing Password
o Gains access to doc(s)

2. Signer clicks on each initial/signature
3. Signer clicks “Finish” button

 

XML Specs

To be delivered in SubmitDocument Call for Party (Test & Production).

 

• SSN = 910000000
• DOB = 00/00/0000
• Service = ‘SelectOneClick’

• Question and Answer (max of 9) within <MemberInfo> element, underneath <Service>

 

<Q1>What is the last name of your best friend?</Q1> maxlen 1000
<A1>Smith</A1> maxlen 1000

 

<Q2>What is the passphrase provided by your agent?</Q2>

<A2>applesauce</A2>

 

... Additional question/answer pairs, if needed.

 

Know Your Customer (KYC) w/Submitted Questions ($) - NOT AVAILABLE / DEPRECATED

NOTE

Question and answer pairs such as these may be abused in certain situations as the submitter or an organization representative can find the answer(s) readily and could possibly authenticate themselves as the signer. Therefore, SIGNiX does NOT recommend using this authentication type unless proper risk mitigation and acceptance discussions have taken place in your organization.

 

Behavior

Signer will go through external authentication – SSN, Name, DOB required. Confirms association of name with DOB and SSN. Also confirms if alive and other checks. Will also be asked to answer questions which are provided by submitting system.

 

Flow

1. Signer accepts Consent (may open it to read it)

o Enters last 4 of SSN & full DOB (unless SubmitDocument required that signer would enter, in which case full 9 digit SSN required)

o Answers Submitter's Question(s)

o Creates Signing Password

o Gains access to doc(s)

2. Signer clicks on each initial/signature and enters Signing Password
3. Finishes after last mandatory signature.

 

XML Specs

To be delivered in SubmitDocument Call for Party (Test & Production).

 

• SSN = 'real’ data (Production) OR 000000000 (Production, if signer will provide); “0001 + random 5” (Webtest) – avoid ‘0001234..’, ‘0001111…’, etc.

• DOB =‘real’ data (Production) OR 00/00/0000 (Production, if signer will provide); Use any DOB over 18 yrs old (Webtest)

• Service = ‘select' 

• Question and Answer (max of 9) within <MemberInfo> element, underneath <Service>

 

<Q1>What is the last name of your best friend?</Q1> maxlen 1000
<A1>Smith</A1> maxlen 1000

 

<Q2>What is the passphrase provided by your agent?</Q2>

<A2>applesauce</A2>

 

... Additional question/answer pairs, if needed.

[Back to top]

 

digital signature faq

 

Status Codes

This section describes the various StatusCode and StatusDesc values that can be returned and explains them. Note that in addition to being a human-readable form of StatusCode, StatusDesc often provides additional detail about the cause of an error.

SIGNiX has some generic Status Codes already in use for other web services that are reused here. This is not an inclusive list. Other errors may be returned. Please submit any questions to your SIGNIX representative.

 

SC_OK

0

 

SC_INTERNAL_ERROR

100

Generic errors start here.

SC_BAD_REQUEST

101

 

SC_UNAUTHORIZED

102

 

SC_BAD_FUNCTION

103

 

SC_BAD_PARAMETER

104

 

SC_NOT_FOUND

105

 

SC_TOO_MANY_REQUESTS

106

Customer request rate limit. May retry.

SC_BUSY

107

Global request rate limit. May retry.

SC_MEMBER_REGISTERED

200

Specific errors start here.

SC_MEMBER_NOT_REGISTERED

201

Deprecated.

SC_MEMBER_NOT_REGISTERED_PING_PASS

201

As of Jul'2007.

SC_SSN_EXISTS_DOB_MISMATCH

202

 

SC_SSN_EXISTS_NAME_MISMATCH

203

 

SC_MEMBER_CANNOT_USE_SDDDC

204

 

SC_DOCUMENT_SET_ALREADY_SUBMITTED

205

 

SC_MEMBER_NOT_REGISTERED_PING_FAIL

206

 

 

 

[Back to top]

 

digital signature faq

 

PDF Details and Requirements

For AcroForms (PDFs made with Acrobat), we support PDF version 1.5 and up. The older the version, the more likely clients will be able to open it without upgrading their installation of Acrobat or Reader.

The documents must be unencrypted.

For signature fields, we just need regular PDF signature fields. Each field must be positioned over a signature line in the document, and each field must have a name that is unique within the document.

In addition to signature fields, we also support what we call signature information fields. These are regular PDF fields that we automatically update at signing time with information about specific signatures.

Right now we support one kind of signature information field, the signing date field. This is a plain text field that we will fill automatically with the time of signing. By default, the date is in U.S. Eastern time zone, and only shows the date, not the time. When the documents are
uploaded, there is a field in the transaction metadata that allows this field to be formatted arbitrarily, include the time, and be reported in other time zones, or in UTC (Zulu). The time zone and format that this field will be reported in is fixed at the time we receive the documents.

 

[Back to top]

 

digital signature faq

Glossary

 

Transaction

A Transaction is a set of one or multiple documents that can be digitally signed, acknowledged or reviewed by one or multiple signers and is submitted together for execution through SIGNiX.

PDF

Portable Document Format, aka ISO 32000-1. This is the document format that SIGNiX utilizes due to its capability to embed legal evidence, maturity and backwards compatibility. It must be AcroForm (most common format) and not XFA (Adobe LiveCycle).

Audit Trail

This is a critical piece of evidence that captures every action and event that transpired during a transaction, including emails sent, identity authentications, signatures and other items. An audit trail is a separate record (in either PDF or XML format) that lets relying parties understand who interacted with any and all of the documents throughout a transaction lifecycle.

Push Notifications

Throughout the transaction lifecycle, these real-time alerts are sent from SIGNiX to your systems to notify them as various milestones occur, including, for example, when a signer completes all of his tasks or when they decide to opt out of using a digital signature, as well as notices of completed or expired transactions. More information is available here.

 

 

[Back to top]

 

digital signature faq

 

References

 

• Supporting Files (Code examples, schemas, XML examples, test documents, Base64 encode/decode and JAR files) - .ZIP File (Virus scanned) - Updated July 2018

Understanding SIGNiX Signatures & Audit Trails, v2 - January 2021

• 

 

 

[Back to top]

 

digital signature faq