Skip to content

ProgrammingGuide_Integration_API

Jump to bottom
Yozons Open eSignForms edited this page Aug 9, 2015 · 49 revisions
        is brought to you by        

Point & Click Programming Integration API Guide

Because of the conversion from Google Code to GitHub, there are likely cross-wiki links that may be broken. Please report to [email protected] any errors you find in the documentation and we'll get it fixed ASAP. Thank you!

How-To Guides

Integration Interface (API)

There are various ways to integrate other applications and web sites with Open eSignForms. They all assume the ability to access HTTPS links to the web site.

Start a transaction

Each transaction template shows the "Start URL" which is used to start a new transaction of its type. There are two standard options you can include on the URL (or as HTTPS POST parameters):

  • ESFTEST=Yes means that you want to start a Test transaction. We recommend using this during all integration testing. If you omit this parameter, it will be assume to be a Production transaction, but you can send it as ESFTEST=No to make it explicit.
  • ESFLIKEPRODUCTION=Yes is only examined if ESFTEST=Yes is also included and controls whether the Test transaction should run using any Test versions found or not. When set to Yes it means even though it is a Test transaction, it will only select Production-level versions. We recommend setting this to Yes on your final integration tests to ensure it is working as expected using only Production-level versions. If this param is not present, it is assumed to have a No value.

Note that the Start URL includes the transaction template EsfPathName. As that name can change, you may also include the following param to specify the id to use if the name cannot be resolved:

  • ttid - Optional transaction template id; if present, this is the transaction template ID to use to find the transaction type if the specified transaction template name in the 'Start URL' could not be found.

Initial data

When integrating, you may pass name-value params, typically via an HTTPS POST, that will automatically pre-fill fields of the same name as the param names in your documents. If the names do not match, you will need to set up custom logic to map the document fields from the transaction data values that hold all of the initial data submitted. Each HTTPS POST name-value is stored in the transaction data regardless. See the document page editor cheatsheet for details on the syntax for referencing transaction data fields.

You may also pre-populate file upload fields by sending the file contents, Base64-encoded (and then URL encoded). Assuming the file upload field in your document is named MyFile, you can submit a param named MyFile with the file's base-64 encoded data as the value. You may also provide the file name to use via the suffix __fileName and the file's MIME/content type via the suffix __fileMimeType. So, in this example, you could also send the param MyFile__fileName=ExampleFile.pdf and param MyFile__fileMimeType=application/pdf to indicate it is a PDF file. If no file name is provided, the param name of the file will be used, and if no mime type is provided, it will be assumed to be application/octet-stream.

Note: The name and value of all params must be URLEncodingNameValueParams URL encoded as per the standard for HTTP.

From an email you send out, inline process

If you already have an email generating system, or you manually send them out, you can start a new transaction by embedding the transaction template's "Start URL" in the email you send out. When external users click on your link, it will take them to your Open eSignForms site where they can complete and sign as necessary.

The external user will start the transaction and act as the first party defined for the package of document(s).

Note that the transaction template must allow for "External users" to have "Start" permission on the transaction.

We call this "inline process" because the external user works on the document directly after clicking on the link.

From your web site, inline process

If you already have a web site, you can start a new transaction by embedding the transaction template's "Start URL" in your web site. When external users click on your link, it will take them to your Open eSignForms site where they can complete and sign as necessary. The link may also be embedded in an IFRAME or FORM, with the FORM allowing you to post some initial data collected from your form or provided by your web site.

The external user will start the transaction and act as the first party defined for the package of document(s).

Note that the transaction template must allow for "External users" to have "Start" permission on the transaction.

We call this "inline process" because the external user works on the document directly after clicking on the link.

## From another web site or web-accessible application, inline process

Like above, this processing allows you to start the transaction as a specific user of Open eSignForms rather than an external user. This is often done from other web portals and applications where the user is authenticated in that system, and now you want to tie that user together with the Open eSignForms user. The link may also be embedded in an IFRAME or FORM, with the FORM allowing you to post some initial data collected from your form or provided by your web site.

To do this, you must include the following two additional HTTPS POST params (we do not recommend you ever including username and passwords in the URL as those values will be recorded in web server logs as well as the user's browser cache):

  • [email protected] specifies the user's login email address to authenticate the user who will start the transaction.
  • ESFLOGINPASSWORD=user+password specifies the user's login password to authenticate the user who will start the transaction.

You must include both params as the system will not attempt authentication without both. That is, it will be treated just the same as an "external user" starting the transaction.

Note that the transaction template must allow for a group that the user belongs to to have "Start" permission on the transaction. You generally would not allow "external users" to start this type of transaction as the purpose is to run only user-authenticated transactions that are tied to the specified user.

We call this "inline process" because the user works on the document directly after clicking on the link.

From another web site or web-accessible application, email process (API)

Unlike the process above, this is suitable for full-API integration where your other application will start a new transaction without any user interactions. This API uses web-standard HTTPS POST of name-value pairs and will receive a simple text response for easy parsing of success or failure. Generally, the first party is fully processed and then the second party is notified by email for external users (or perhaps via the To Do queue for an internal user) to process the transaction.

Unlike the previous "inline process" versions, no web page is returned because it is assumed that the user is not present to handle the documents immediately.

Add the following additional HTTPS POST params for API-processing:

  • [email protected] specifies the user's login email address to authenticate the user who will start the transaction in API mode.
  • ESFLOGINPASSWORD=user+password specifies the user's login password to authenticate the user who will start the transaction in API mode.
  • ESFAUTOCOMPLETEFIRSTPARTY=Yes means that the first party, as defined by the required ESFLOGINUSER and ESFLOGINPASSWORD params, will be completed as a result of this API request, with any second party then notified.

Since no user is actually present, a standard web page response is not returned. Instead of a text/html (content/mime type) response, a text/plain response is sent as follows:

  • If the request is not even processed due to an error, an HTTP 404 response code is sent to indicate the error.
  • OK:transaction-id is returned if the transaction was successfully started and includes the transaction id after the colon.
  • ERROR:error-mesage is returned if there was an error in user authentication or other transaction processing error, such as data validation errors. The error message may span more than one line with embedded newlines if more than one error was detected.

We call this "email process" because the next user will only gain access to the transaction after receiving an email containing their unique link. The link the user receives will not be the "Start URL" at all, but will be a pickup-link to retrieve an existing transaction. Of course, if there is no second party, the transaction will complete as expected.

Note that no document snapshots will exist for the first party since the documents were not, in fact, presented in Review mode. Data snapshots still are done.

Update API

You can use the Update API to update an existing transaction by doing an HTTPS POST to the Update API URL (via the /U/ path, i.e. https://example.com/WEBAPP/U/). The identified user must be given "Use Update API" permission on the transaction template that matches the specified transaction id to update.

Unauthorized or invalid requests are rejected with HTTP status codes other than 200 and do not have a text response. For example, http status 403 (FORBIDDEN) is returned if not authenticated or does not have permission; http status 404 (NOT FOUND) if the ESFTID or specified documents/parties are not in legal values or the transaction cannot be found; and http status 503 (SERVICE UNAVAILABLE) for system errors.

The following params should be sent along to the Update API URL, along with the name-values of the fields to update to the new values:

  • ESFTID is used to specify the transaction id to update. It is required.
  • ESFLOGINUSER is used to specify the user account that has been authorized to update this type of transaction.
  • ESFLOGINPASSWORD is the corresponding password for ESFLOGINUSER. It is required.
  • ESFDOCUMENT can be used to specify the name of a particular document in the transaction to be updated. If it's omitted, all documents will be update if they have matching field names.
  • ESFPARTY is the name of the party the update will work with. This is normally not required, but it is required when sending over a "File Upload" type field as the file upload is not only data, but it's associated with a given party. When sending over a file, it must be Base64-encoded (and then URL encoded). Assuming the file upload field in your document is named MyFile, you can submit a param named MyFile with the file's base-64 encoded data as the value. You may also provide the file name to use via the suffix __fileName and the file's MIME/content type via the suffix __fileMimeType. So, in this example, you could also send the param MyFile__fileName=ExampleFile.pdf and param MyFile__fileMimeType=application/pdf to indicate it is a PDF file. If no file name is provided, the param name of the file will be used, and if no mime type is provided, it will be assumed to be application/octet-stream.
  • ESFEVENTNAME is used to identify this particular Update API call. If not present, "UpdateAPI" is assumed. It is mostly used for custom logic rules that operate whenever the Update API is called, using a condition to test the event name. Of course, if you only have one system using the Update API in your transaction, there is no need to differentiate update API callers. For ease of updating later, we recommend using a name to identify the purpose for the Update API taking place so if others are added later, they can be differentiated using custom logic conditions.

Sending data back to your system

Please view the custom logic setup for the HTTP Send Data Action for details on sending back data to your system. This allows you to do an HTTP(S) GET/POST of name-value pairs including fields defined in your documents.

Retrieve CSV data back to your system

Assuming you have built a Report to list the fields you want to retrieve, you can run a CSV Report by using a special link/URL (HTTPS POST of name-value pairs is best) that will run that report and return the data in CSV format.

The CSV data fields will be separated by a comma. When necessary, data values will be quoted (such as if the data value contains quotes or commas). Each line ends with a CR+LF. On successful retrieval, the content-type returned will be text/csv; charset=UTF-8

The base URL to retrieve CSV data is:

https://esign.example.com/WEBAPP/csv/YourReportPathNameHere

YourReportPathNameHere must be the EsfPathName of the report you created and have permission to run, as well as permission to export CSV data.

WEBAPP is the name of your deployment. For those who run their own systems, this may not be present if you are using the ROOT webapp. For most hosted customers, this will be the same name you use when you login.

Next, you can add various named-value parameters to control the CSV export process:

  • rtid - Optional report template id; if present, this is the report template ID to use to find the report if YourReportPathNameHere could not be found.
  • ESFLOGINUSER - Required user name; the email address of the user account used to authenticate the request to run the report.
  • ESFLOGINPASSWORD - Required user password; the password to authenticate the request.
  • ESFTEST - Optional type of transactions to retrieve; if not present, assumes Production transactions should be retrieved. If present, assumes Test transactions unless the value is set to N or F or 0 to turn it off.
  • dateType - Optional meaning of the startDate/endDate; assumes started unless set to lastUpdated.
  • startDate - Optional start date (oldest to retrieve); assumes now (today at 00:00:00 in the user's default time zone). Use -1 for yesterday or -N for N days ago. Use YYYY-MM-DD format to specify a particular date.
  • endDate - Optional end date (most recent to retrieve); assumes now (today at 23:59:59 in the user's default time zone). Use -1 for yesterday or -N for N days ago. Use YYYY-MM-DD format to specify a particular date.
  • startedByMe - Optional; assumes Y. If N, you must allow one of the two other 'started by' options or this will still assume Y.
  • startedByAnyUser - Optional; assumes Y if the user has such permissions specified in the report, otherwise N.
  • startedByExternalParties - Optional; assumes Y if the user has such permissions specified in the report, otherwise N.
  • showInProgress - Optional; assumes N to not include in progress transactions. If Y transactions that are still in progress will be included.
  • showCompleted - Optional; assumes Y to include completed transactions. If N transactions that are completed will not be included.
  • showCanceled - Optional; assumes N to not include canceled transactions. If Y transactions that are canceled will be included.
  • showSuspended - Optional; assumes N to not include suspended transactions. If Y transactions that are suspended will be included.
  • includeHeaderLine - Optional; assumes Y to include the first line in the CSV data that lists the field names; If N then that line will not be included and you will just get CSV data records.

For example, assuming a report named API/ContactReport in a customer webapp named demo, to retrieve production transactions completed yesterday, the URL would be:

https://esign.example.com/demo/csv/API/[email protected]&ESFLOGINPASSWORD=demopass&dateType=lastUpdated&startDate=-1&endDate=-1

When possible, we recommend using an HTTPS POST instead of a simple URL/link like above to ensure none of the parameters are recorded in server logs. With an HTTPS POST, you use the same name-value pairs, just sent as the body of the request instead of on the URL/link.

Note: The name and value of all params must be URL encoded as per the standard for HTTP.

Transaction Administration API (Coming Soon)

This API is currently under development. It will be included in the 15.8.23 release.

The following API is used to interact with existing transactions. You can use the Transaction Administration API to get status information about a transaction by doing an HTTPS POST to the Tran Admin API URL (via the /tranadmin/ path). The identified user must belong to a group specified in the "Use Tran Admin API" permission on the transaction template that matches the specified transaction id.

At a high level, the external app does an HTTPS POST request to an URL like https://esign.example.com/WEBAPP/tranadmin/REQUEST-NAME and the response will be XML with the answer or an error. The first three (3) params must always be present as they identify the requester and the transaction.

Unauthorized or invalid requests are rejected with HTTP status codes other than 200 and do not have an XML response. For example, http status 403 (FORBIDDEN) is returned if not authenticated or does not have permission; http status 404 (NOT FOUND) if the ESFTID or specified documents/parties are not in legal values or the transaction cannot be found; and http status 503 (SERVICE UNAVAILABLE) for system errors.

XML error responses are returned if the ESFLOGINUSER is authenticated with permission to make the call and the ESFTID points to a valid transaction.

GetStatus

The GetStatus request-name is used to retrieve status information about the transaction, it's parties and where those parties are with respect to each document in the package.

Request URL: https://esign.example.com/WEBAPP/tranadmin/GetStatus

Params:

  • ESFLOGINUSER - Required user name; the email address of the user account used to authenticate the request to use the API.
  • ESFLOGINPASSWORD - Required user password; the password to authenticate the request.
  • ESFTID - Required transaction id
  • ESFDOCUMENT - Optional document name, if missing or has no value, assumes all documents. You may specify this parameter multiple times to select more than one document, but not all. Document status is returned on a per-party basis.
  • ESFPARTY - Optional party name, if missing or no value, assumes all parties. You may specify this parameter multiple times to select more than one party, but not all.

GetStatusResponse XML:

The response includes the overall transaction status information, followed by each party and the documents that party has access to.

<GetStatusResponse xmlns="http://open.esignforms.com/XMLSchema/TranAdminApi/2015">
  <Transaction>
    <id>6b846d0e-1ab5-4601-9b7e-4da9ba28d75c</id>
    <status>Completed</status>
    <statusCode>C</statusCode>
    <statusText>Completed</statusText>
    <lastUpdatedTimestamp>2015-08-07T22:40:03Z</lastUpdatedTimestamp>
    <cancelTimestamp/>
    <expireTimestamp>2015-11-07T22:34:16Z</expireTimestamp>
    <Party>
      <id>022ecd56-80ab-4a27-a7d4-ebbe1e409427</id>
      <esfname>FirstParty</esfname>
      <status>Completed</status>
      <statusCode>C</statusCode>
      <emailAddress>[email protected]</emailAddress>
      <pickupCode>nOJuMVVgqpqoRVzfwLol</pickupCode>
      <pickupUrl>https://esign.example.com/WEBAPP/P/nOJuMVVgqpqoRVzfwLol</pickupUrl>
      <lastAccessedTimestamp>2015-08-07T22:40:03Z</lastAccessedTimestamp>
      <PartyDocument>
        <esfname>Contract</esfname>
        <documentNumber>1</documentNumber>
        <status>Completed</status>
        <statusCode>C</statusCode>
        <lastUpdatedTimestamp>2015-08-07T22:40:03Z</lastUpdatedTimestamp>
        <esignIpHostAddr>cloud.example.com (198.1.2.3)</esignIpHostAddr>
        <esignTimestamp>2015-08-07T22:40:01Z</esignTimestamp>
      </PartyDocument>
    </Party>
  </Transaction>
</GetStatusResponse>

Empty elements indicate no value. For example, an empty 'cancelTimestamp' means it's not set to auto-cancel. An empty 'expireTimestamp' means it's not set to be deleted (retention is forever). Missing 'esignTimestamp' means the document has not been signed by this party.

Transaction status (code) values:

  • In progress (I)
  • Completed (C)
  • Canceled (X)
  • Suspended (S)

Party status (code) values:

  • Not yet activated (U)
  • Activated (A)
  • Retrieved (R)
  • Rejected (X)
  • Completed (C)
  • Transferred (T)
  • Skipped (S)

PartyDocument status (code) values:

  • Not yet retrieved (U)
  • View optional (V)
  • View optional viewed (v)
  • Retrieved (R)
  • Completed (C)
  • Rejected (X)
  • Skipped (S)

Error XML is returned for no such document or no such party when specified. For example, this indicates a requested document name is not part of the requested transaction. The <reason> element describes the error.

<Error xmlns="http://open.esignforms.com/XMLSchema/TranAdminApi/2015">
  <transactionId>ac804546-704c-4fb7-9f4d-54dd50b4ef01</transactionId>
  <requestName>GetStatus</requestName>
  <reason>Document name not found: BadDocName</reason>
</Error>

GetDocumentSnapshot

The GetDocumentSnapshot request-name is used to get a completed document snapshot in various formats.

Request URL: https://esign.example.com/WEBAPP/tranadmin/GetDocumentSnapshot

Params:

  • ESFLOGINUSER - Required user name; the email address of the user account used to authenticate the request to use the API.
  • ESFLOGINPASSWORD - Required user password; the password to authenticate the request.
  • ESFTID - Required transaction id
  • ESFDOCUMENT - Optional document name, if missing or has no value, assumes all completed documents. You may specify this parameter multiple times to select more than one document, but not all.
  • ESFPARTY - Optional party name, if missing or no value, assumes latest party to have completed the associated document(s).
  • FORMAT - Optional value of HTML|PDF|XMLDSIG|PDFMERGE, if missing or has no value, assumes XMLDSIG.
    • HTML is the native document format;
    • PDF is the HTML document converted to PDF;
    • XMLDSIG is the XML digitally signed HTML;
    • PDFMERGE is all documents merged into a single PDF
  • INCLUDEDATA Optional value of XMLDSIG|XML|NONE, if missing or no value, assumes NONE.
    • XMLDSIG returns the XML digitally signed data;
    • XML returns the data in XML format.
    • NONE means do not return the data

Response XML:

The response includes the basic transaction status information, followed by each document (latest or for one party) requested in the <PartyDocument> element. Documents that have no snapshot are not included in the response. If the FORMAT=PDFMERGE option is used, no <snapshotDocument> element will be present in the <PartyDocument> element; instead there will be a single <PDFMerge> element. The <snapshotData> element is only present if the INCLUDEDATA param requests it.

<GetDocumentSnapshotResponse xmlns="http://open.esignforms.com/XMLSchema/TranAdminApi/2015">
 <Transaction>
  <id>6b846d0e-1ab5-4601-9b7e-4da9ba28d75c</id>
  <status>Completed</status>
  <statusCode>C</statusCode>
  <statusText>Completed</statusText>
  <lastUpdatedTimestamp>2015-08-07T22:40:03Z</lastUpdatedTimestamp>
  <PartyDocument>
   <esfname>Contract</esfname>
   <documentNumber>1</documentNumber>
   <status>Completed</status>
   <statusCode>C</statusCode>
   <lastUpdatedTimestamp>2015-08-07T22:40:03Z</lastUpdatedTimestamp>
   <esignIpHostAddr>cloud.example.com (198.1.2.3)</esignIpHostAddr>
   <esignTimestamp>2015-08-07T22:40:01Z</esignTimestamp>
   <snapshotDocument>(this element is present unless FORMAT=PDFMERGE is used -- if FORMAT=PDF is used, it will be a PDF file Base-64 encoded.)</snapshotDocument>
   <snapshotData><esfRecord xmlns="http://open.esignforms.com/XMLSchema/2009">
 <id>305dfb3f-9ba1-46f4-b895-53701bee563b</id>
 <esfname>TestDDEmail</esfname>
 <encrypt>true</encrypt>
 <compress>true</compress>
<nameValues count="8">
 <nameValue clone="false">
  <name>signature_IPOnly</name>
  <value>198.1.2.3</value>
 </nameValue>
 <nameValue clone="false">
  <name>signature</name>
  <value>John Smith</value>
 </nameValue>
 <nameValue clone="false" type="datetime">
  <name>signature_Timestamp</name>
  <value>2015-08-07T22:40:03Z</value>
 </nameValue>
 <nameValue>
  <name>location</name>
  <value />
 </nameValue>
 <nameValue type="datetime">
  <name>finalNoticeDateTime</name>
  <value null="true" />
 </nameValue>
 <nameValue>
  <name>firstName</name>
  <value>John</value>
 </nameValue>
 <nameValue clone="false">
  <name>signature_IP</name>
  <value>cloud.example.com (198.1.2.3)</value>
 </nameValue>
 <nameValue>
  <name>lastName</name>
  <value>Smith</value>
 </nameValue>
</nameValues>
</esfRecord></snapshotData>
  </PartyDocument>
 <PDFMerge>(this element is present only if FORMAT=PDFMERGE is used -- it will be the merged PDF file Base-64 encoded.)</PDFMerge>
 </Transaction>
</GetDocumentSnapshotResponse>

Error XML is returned for no such document, no such party, unexpected format or unexpected include-data format. An error is also returned if no document snapshots can be found. The <reason> element describes the error.

<Error xmlns="http://open.esignforms.com/XMLSchema/TranAdminApi/2015">
  <transactionId>6b846d0e-1ab5-4601-9b7e-4da9ba28d75c</transactionId>
  <requestName>GetDocumentSnapshot</requestName>
  <reason>Document name not found: BadDocName</reason>
</Error>

XML Digitally Signed Document and Data

This shows how XML digitally signed versions of the HTML document and the XML data will appear in their respective elements <snapshotDocument> and <snapshotData>:

<snapshotDocument>
<snapshot xmlns="http://open.esignforms.com/XMLSchema/2011" timestamp="2015-08-07T15:40:03-07:00" type="document"><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
   (the rest of the HTML document CDATA contents are here)
</html>
]]>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#" Id="OpenESignForms_Seal">
<SignedInfo>
  <CanonicalizationMethod Algorithm="http://www.w3.org/2006/12/xml-c14n11#WithComments" />
  <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha512" />
  <Reference Id="Payload_Reference_ID" URI="">
    <Transforms>
      <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
    </Transforms>
    <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512" />
    <DigestValue>oqoRRb8Bfvl4Qehx5BPlpqBTSaFNqfls7vf/7TnM2QFyTQN5scWF9fgGPat8d6G+C6RbGl6SoX1v
/lDq5IvkPQ==</DigestValue>
  </Reference>
  <Reference URI="#KeyInfo_ID">
    <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512" />  
    <DigestValue>TDo5qpXuWAaWu+PbdIYAppHFZcekUwQ4m9ZU7GTU6cyA//u2ybmUPTMzeW1FdUnAC7x0uKIuqCr7
ijVfKzAfog==</DigestValue>
  </Reference>
  <Reference URI="#QualifyingProperties_ID">
    <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512" />
    <DigestValue>jcrmfYIoAVBhNmR+7N6vysXqwC7m6EI9z+muI63vFKBngJG1Mxx/mdNQIHxRl79VfPxf91VyN8Vz
11jRVnSEZg==</DigestValue>
  </Reference>
  <Reference URI="#OpenESignForms_Seal_ID">
    <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512" />
    <DigestValue>E/0d7RqwMoPR9XH5L9AE8/YESzeyKqYBaMYOwkp+2DN65IbzZAkAXEo6+/iz3zY0qItfZfgFGf/f
dhWHm4F60A==</DigestValue>
   </Reference>
</SignedInfo>
<SignatureValue>GAsYF7/Wz+63mSFwfpxOC4wTXM/CNnFdBx906M/sGG8L8FHvKAZRUk8QK53TfLgQSb5E9GjzSnNg
5R4dqMeGmFD5dVgmh3xqHPYg3QDEJxRJaV3wG5f8eUp01h25VldONnjoRBXVyZeGcPKaKdk2mcNR
mJUBN81DFDCNRPGPLf3VTu2tUnYQ3OVQ17WoA89MsPXuo1VB3pB0NKt9o0pQ9PQBFX1a+xkiAvZZ
QeBg9fKroqtgTSxK8da7mf3U4vq7Pc7qa58jS+OjT4AKoB+Afa8TvgXczC8fZzSEVlIkyxSm79VK
qP7LhNH+irWlAuo0UvjB5Sib37g67dANyOhpsP5kcIgC5tSolDQg/KqNHtUsd5yY8PbkasHC2TC6
mxyJW3BBpzt5f11kwTwfbgY4aqY6erXuxM1oE3wlyPrtv5eZfRRnM+RtOtW2LrawCOOHTmhyJdMH
MnKb/xbN3CXr9xL83410vrBA1A4QRlBoKbm7kUSlZpf4CX+YuAho/q/Fva/ILBrKsRDMRXeimBgr
CO0GWbnnqy1FeV14tR0lmjEQmEqCurRb60IyLO20lF1gAZoETX4YDyNBHUkqfmxPb7YSlEQMZA0M
Bsf0tRB2naVej77k5toRGFf7R9b4gXSWIDLYyfle0pI4RUfvnjHtKYGC7LnEGK6ubGbJ1WY0VtU=</SignatureValue>
<KeyInfo Id="KeyInfo_ID">
  <KeyName>02dbc009-102b-4ea7-9ac8-760e8b36859f</KeyName>
  <KeyValue>
    <RSAKeyValue>
      <Modulus>kPCr+Fy0NInaICpnzDpGLkNQ93kd0NzZfTBfQOb3PUH1Bt4OrBWcvYoch7wUm6k1Il3apsi7s2B9
Geqbh7tzF41MwvTWBNCQg3Kw3FKcF0jzKZ7D+na8Ndc52YPmsjU9zjpf+SDfKqb0NIDe3Bo3csWW
I42CkF3sI9AFknogovrfRM7ITJatA6WRHU8Kv6Qee8VfXZ1XAdKzWcc9EWbj74Kagiz8bMeATujU
MCI/XQb1luwvlrVxZUtnfLL9WD6Nvmj3uDYK52z5E80vqTKIq7EJvmlR7kcEdH1NuxDQSWCJQgQX
oU2TzuB0Nmov7P/pZ40JPF72Knb18Rgu4aRSMiaKKw+jzFHpw75VlQn2YkdfjNMwfUaEaZ4wuHoJ
Qjud79jilbam++eUQFRxjcXK9Nl/z01KtmuV1mPhm97LRaKQlsbBxa56pncrkAmF0cuIipPzo9aB
snJZkUQuwQtD/moDkUm84v5SOU1hn4RpWdGAkaJ1ubIrnKfF0qKmbCOcO69SEL5zP0JXEgSZ+D6z
Vv7VkAJizdJ91KKs4y/ypel4lurNcyBd3hzw8xpz9joMl8DOTLCcLhGp350Vrccbh9vauAcRcK/n
C+yaPI/mghmN2D2yZ3LZ3Z6k78Jl9BUV7PL5YyuxQmZjVP07lJvi6glLUm23o+c3c4D7rgHL4gM=</Modulus>
      <Exponent>AQAB</Exponent>
    </RSAKeyValue></KeyValue><X509Data>   
    <X509Certificate>MIIKvTCCCKWgAwIBAgIJAPaU10x5GhRQMA0GCSqGSIb3DQEBDQUAMIHYMU0wSwYDVQQDDERPcGVu
X2VTaWduRm9ybXNfaHR0cHM6Ly9sb2NhbGhvc3QubG9jYWxkb21haW4vb3Blbi1lU2lnbkZvcm1z
(snipped for brevity)
3xaXcwd32t1+/aOa7jgJRTgSklxhhcRCMHI9HWNlLgUWmvZ2O5G70reY4Kyg1NAS56qX48Xbckvy
VMfem/JPPYT/veThnefIgQk=</X509Certificate>
   </X509Data>
  </KeyInfo>
  <Object>
    <QualifyingProperties Id="QualifyingProperties_ID">
      <SignedProperties>
        <SignedSignatureProperties>
          <SigningTime>2015-08-07T15:40:03-07:00</SigningTime>
        </SignedSignatureProperties>
        <SignedDataObjectProperties>
          <DataObjectFormat ObjectReference="#Payload_Reference_ID">
            <Description>Contract.html</Description>
            <MimeType>text/html</MimeType>
          </DataObjectFormat>
        </SignedDataObjectProperties>
      </SignedProperties>
    </QualifyingProperties>
  </Object>
  <Object>     
    <SignatureProperties>
      <SignatureProperty Id="OpenESignForms_Seal_ID" Target="#OpenESignForms_Seal">
        <OpenESignForms_XmlDigitalSignatureSeal DeploymentHostAddress="198.1.2.3" DeploymentHostName="esign.example.com" DeploymentId="aa0e2b9e-c9d2-4945-8eef-b648bd63aac4" SignerAddress="esign.example.com (198.1.2.3)" SignerAgent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:39.0) Gecko/20100101 Firefox/39.0" Timestamp="2015-08-07T15:40:03-07:00" Version="15.8.23" />
      </SignatureProperty>
    </SignatureProperties>
  </Object>
</Signature>
</snapshot>
</snapshotDocument>

<snapshotData>
<snapshot xmlns="http://open.esignforms.com/XMLSchema/2011" timestamp="2015-08-07T15:40:03-07:00" type="data"><esfRecord xmlns="http://open.esignforms.com/XMLSchema/2009">
   (name value data is here)
</esfRecord>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#" Id="OpenESignForms_Seal">
 (rest of XML digital signature like above)
</Signature>
</snapshot>
</snapshotData>

RenotifyParty

Conceptually, this API request is not really needed as you can do a standard Update API call for the transaction id with an event name that triggers any Actions you want, including sending an email to any party or canceling the transaction, etc. as defined in the package's custom logic.

Request URL: https://esign.example.com/WEBAPP/tranadmin/RenotifyParty

Params:

  • ESFLOGINUSER - Required user name; the email address of the user account used to authenticate the request to use the API.
  • ESFLOGINPASSWORD - Required user password; the password to authenticate the request.
  • ESFTID - Required transaction id
  • ESFPARTY - Optional party name or email address; if this value includes an '@' symbol it is assumed to be an email address, but it is more typical to be a party EsfName. If omitted, this will renotify all currently active parties (normally this is only a single party).
  • TRANSFERTOEMAIL - Optional email address to transfer the specified ESFPARTY to. If present with a value, will attempt to do a "transfer party" using the new email address before sending out the email renotification.

Response XML:

The response includes the basic transaction status information, followed by each party that matches the ESFPARTY param value. The <renotifyPartyStatus> and optional <transferPartyStatus> indicate the outcome for the party.

<RenotifyPartyResponse xmlns="http://open.esignforms.com/XMLSchema/TranAdminApi/2015">
 <Transaction>
  <id>0cc6f3c0-ce63-41ac-ac68-40aaa229fde6</id>
  <status>Completed</status>
  <statusCode>C</statusCode>
  <statusText>Completed</statusText>
  <lastUpdatedTimestamp>2015-07-09T00:06:43Z</lastUpdatedTimestamp>
  <Party>
   <id>30c951db-79e6-4659-aae9-6b5ae85ef73f</id>
   <esfname>Client</esfname>
   <renotifyPartyStatus>Completed</renotifyPartyStatus>
   <status>Completed</status>
   <statusCode>C</statusCode>
   <emailAddress>[email protected]</emailAddress>
   <pickupCode>jinxFoPhjhHlQscksWEs</pickupCode>
   <pickupUrl>https://esign.example.com/WEBAPP/P/jinxFoPhjhHlQscksWEs</pickupUrl>
   <lastAccessedTimestamp>2015-07-09T00:06:21Z</lastAccessedTimestamp>
  </Party>
 </Transaction>
</RenotifyPartyResponse>

The element <transferPartyStatus> is included when the TRANSFERTOEMAIL parameter is specified. On success, it has a value like 'Completed: [email protected]'; on error it has a value like 'Failed: [email protected]'. If the party is not active (or retrieved), the value is 'Skipped: status not Activated or Retrieved'. If the new email address matches the current email address, the value is 'Skipped: email address unchanged'.

The element <renotifyPartyStatus> specifies the results of the renotification. On success, it has the value 'Completed'; on error it has the value 'Failed'; if TRANSFERTOEMAIL was also specified and the transfer succeeded, it has the value 'Completed: transferred'; if the party has no To DO group or email address, the value is 'Skipped: no To Do group or email address assigned'; if the party is not activated, retrieved or completed, the value is 'Skipped: status not Activated, Retrieved or Completed';

Error XML is returned if the transaction is canceled or suspended, there is no such party, or the TRANSFERTOEMAIL address is not valid. The <reason> element describes the error.

<Error xmlns="http://open.esignforms.com/XMLSchema/TranAdminApi/2015">
  <transactionId>6b846d0e-1ab5-4601-9b7e-4da9ba28d75c</transactionId>
  <requestName>GetDocumentSnapshot</requestName>
  <reason>No valid parties found with party name (BadPartyName) specified for the ESFPARTY param.</reason>
</Error>

Note: The name and value of all params must be URL encoded as per the standard for HTTP.

Documentation for eSignForms by Yozons Inc.

Clone this wiki locally