Skip to content

ProgrammingGuide_Integration_API

Jump to bottom
Yozons Open eSignForms edited this page Aug 20, 2020 · 43 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 Yozons 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 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 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.

When embedding the Start URL in a web page, add the HTML attribute rel="nofollow" to keep search engines that will discover your web page from starting transactions. You will also likely want such a transaction (via the package's custom logic) to auto-cancel and delete itself if the first party does not complete at least the first document within a reasonable amount of time. This will get rid of transactions accidentally started, or started before they were truly ready, or those started by things like search engines.

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.

Note: For embedding the Start URL via an IFRAME, if your process may require a login page (authenticated parties), you'll need to update the ESF/Library/Template's property ESF.LoginPageAllowEmbedded to be set to true. Otherwise, the login pages will include HTTP Headers X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' to tell browsers not to do it.

Note 2: For those who need embedded content and are using Tomcat's org.apache.catalina.filters.HttpHeaderSecurityFilter filter, you will also need to set the init param antiClickJackingEnabled to false.

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 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 eSignForms user. The link may also be embedded in an IFRAME (see Note above) 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=userPassword 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=userPassword 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 recommended ESFLOGINUSER and ESFLOGINPASSWORD params, will be completed as a result of this API request, with any second party then notified. It is possible to allow non-authenticated transactions to be started, but this would mean anybody could start such transactions by posting data to its Start URL.

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/). 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.

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. NOTE: If the Update API is called when the transaction is canceled, the event name is renamed with "-Canceled" appended; and if the transaction is suspended, the event name is renamed with "-Suspended" appended.
  • name=value pairs are used to send over field names and their new values. You may include as many as you'd like to update. The names should be field names, and the values must URL Encoded.

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.

Contact tech support for details on using HTTP Send Action to transfer files into the Harris School Solutions JDox service, or the Digitech PaperVision and ImageSilo services.

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.

Optional extra params for non-date search field filtering (if used, both are required and must have the same number of params each)

Optional extra params for date search field filtering (if used, all three are required and must have the same number of params each)

  • searchDateFieldName - Specify the (date) searchable report field template name to search against
  • searchDateFieldFrom - Specify the search date field FROM date. Assumes 'now' if blank. Use -1 for yesterday or number of days previously or YYYY-MM-DD format.
  • searchDateFieldTo - Specify the search date field TO date. Assumes 'now' if blank. Use -1 for yesterday or number of days previously or YYYY-MM-DD format.

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.

Download Transaction Archive ZIP file back to your system

Assuming you have built a Report to list the transactions and fields you want to export, you can run a Download Archive Report by using a special link/URL (HTTPS POST of name-value pairs is best) that will run that report and return the transaction archive data as a ZIP file.

The base URL to download the transaction archive is:

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

YourReportPathNameHere must be the EsfPathName of the report you created and have permission to run, as well as permission to 'download complete transaction archives'.

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 archive 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.
  • includeInProgress - Optional; assumes N to not include in progress transactions. If Y transactions that are still in progress will be included.
  • includeCompleted - Optional; assumes Y to include completed transactions. If N transactions that are completed will not be included.
  • includeCanceled - Optional; assumes N to not include canceled transactions. If Y transactions that are canceled will be included.
  • includeSuspended - Optional; assumes N to not include suspended transactions. If Y transactions that are suspended will be included.

Optional extra params for non-date search field filtering (if used, both are required and must have the same number of params each)

Optional extra params for date search field filtering (if used, all three are required and must have the same number of params each)

  • searchDateFieldName - Specify the (date) searchable report field template name to search against
  • searchDateFieldFrom - Specify the search date field FROM date. Assumes 'now' if blank. Use -1 for yesterday or number of days previously or YYYY-MM-DD format.
  • searchDateFieldTo - Specify the search date field TO date. Assumes 'now' if blank. Use -1 for yesterday or number of days previously or YYYY-MM-DD format.

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

https://esign.example.com/demo/archive/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.

Download Transaction PDFs ZIP file back to your system

Assuming you have built a Report to list the transactions you want to export as PDFs, you can run a Download PDF Report by using a special link/URL (HTTPS POST of name-value pairs is best) that will run that report and return the transaction PDFs as a ZIP file.

Since all listed transactions will be converted to a PDF (combining all of the latest documents), along with any uploaded files (attachments) to the transaction, unique PDF names are important so your download makes sense. Use the package's PDF download file name spec so ensure meaningful names, such as using ${document.fieldName} specs along with the package name. For simple unique names, you can use the field spec ${transaction:id} but that likely will not carry much meaning when looking at the listing of download PDFs.

Note that this request can take significant time to generate the PDFs across a large number of transactions.

The base URL to download the transaction PDFs is:

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

YourReportPathNameHere must be the EsfPathName of the report you created and have permission to run, as well as permission to 'download transaction PDFs with uploaded files'.

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 archive 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.
  • includeInProgress - Optional; assumes N to not include in progress transactions. If Y transactions that are still in progress will be included.
  • includeCompleted - Optional; assumes Y to include completed transactions. If N transactions that are completed will not be included.
  • includeCanceled - Optional; assumes N to not include canceled transactions. If Y transactions that are canceled will be included.
  • includeSuspended - Optional; assumes N to not include suspended transactions. If Y transactions that are suspended will be included.

Optional extra params for non-date search field filtering (if used, both are required and must have the same number of params each)

Optional extra params for date search field filtering (if used, all three are required and must have the same number of params each)

  • searchDateFieldName - Specify the (date) searchable report field template name to search against
  • searchDateFieldFrom - Specify the search date field FROM date. Assumes 'now' if blank. Use -1 for yesterday or number of days previously or YYYY-MM-DD format.
  • searchDateFieldTo - Specify the search date field TO date. Assumes 'now' if blank. Use -1 for yesterday or number of days previously or YYYY-MM-DD format.

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

https://esign.example.com/demo/pdfarchive/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

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. All responses use the XML namespace "http://open.esignforms.com/XMLSchema/TranAdminApi/2015" to uniquely identify it's XML. Other embedded XML will likely use their own namespaces to ensure element names do not clash.

WEBAPP above 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.

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

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.

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>

On success, a GetStatusResponse is returned with the primary Transaction element. Inside its Transaction element are the following details:

  • id is transaction id
  • status is the transaction status (more below)
  • statusCode is the transaction status code (more below)
  • statusText is the status text field that generally includes the party and optional document the party is on as the transaction progresses
  • lastUpdatedTimestamp is the date-time when the transaction was last updated
  • cancelTimestamp is when the transaction is set to auto-cancel. If empty, then it has no auto-cancel time set.
  • `expireTimestamp' is when the transaction is set to be deleted based on its retention value. If empty, then it is set to be kept "forever."
  • Party is a container element for each party to the transaction (may have multiple such elements)
    • id the party id
    • esfname is the party name
    • status is the party status (more below)
    • statusCode is the party status code (more below)
    • emailAddress is the email address, if any, set for the party
    • pickupCode is the unique pickup code for this party
    • pickupUrl is the ${LINK} value for this party to retrieve/process the transaction
    • lastAccessedTimestamp is the date+time the party last accessed the transaction
    • PartyDocument is a container element for each document the party has access to (may have multiple such elements)
      • esfname is the document name
      • documentNumber is the document number order for this party
      • status is the party document status (more below)
      • statusCode is the party document status code (more below)
      • lastUpdatedTimestamp is the date-time the party last updated this document
      • esignIpHostAddr is the IP address (with optional host name in parens) of the party at the time it was electronically signed; blank if not e-signed.
      • esignTimestamp is the date-time when the party electronically signed; blank if not e-signed.

Status and Codes

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)
  • Completed (C)
  • Completed; transferred for redo (t)
  • Transferred (T)
  • Skipped (S)

PartyDocument status (code) values:

  • Not yet retrieved (U)
  • View optional (V)
  • View optional viewed (v)
  • Retrieved (R)
  • Redo/fix requested (F)
  • Completed (C)
  • 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

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.

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>

On success, a GetDocumentSnapshotResponse is returned with the primary Transaction element. Inside its Transaction element are the following details:

  • id is transaction id
  • status is the transaction status (see above)
  • statusCode is the transaction status code (see above)
  • statusText is the status text field that generally includes the party and optional document the party is on as the transaction progresses
  • lastUpdatedTimestamp is the date-time when the transaction was last updated
  • PartyDocument is a container element for each document the party has access to (may have multiple such elements)
    • esfname is the document name
    • documentNumber is the document number order for this party
    • status is the party document status (see above)
    • statusCode is the party document status code (see above)
    • lastUpdatedTimestamp is the date-time the party last updated this document
    • esignIpHostAddr is the IP address (with optional host name in parens) of the party at the time it was electronically signed; blank if not e-signed.
    • esignTimestamp is the date-time when the party electronically signed; blank if not e-signed.
    • snapshotDocument is a container that holds the HTML, PDF or Digitally Signed XML document contents when this party completed it.
    • snapshotData is a container that holds the XML or Digitally Signed XML data structure of name-value pairs for each field in the document at the time when this party completed it.
  • PDFMerge this element is included when the FORMAT requested is PDFMERGE (and the PartyDocument elements will not have its corresponding snapshotDocument element as each document is not returned, but the merged documents is returned)

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

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.

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.
  • TRANSFERTOSMSPHONE - Optional mobile phone number to transfer the specified ESFPARTY to. If present with a value, will attempt to do a "transfer party" using the new phone before sending out the SMS 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.

On success, a RenotifyPartyResponse is returned with the primary Transaction element. Inside its Transaction element are the following details:

  • id is transaction id
  • status is the transaction status (see above)
  • statusCode is the transaction status code (see above)
  • statusText is the status text field that generally includes the party and optional document the party is on as the transaction progresses
  • lastUpdatedTimestamp is the date-time when the transaction was last updated
  • Party is a container element for each party requested to be renotified (may have multiple such elements)
    • id the party id
    • esfname is the party name
    • status is the party status (more below)
    • statusCode is the party status code (more below)
    • transferPartyStatus is present only if a TRANSFERTOEMAIL param was specified; on successful transfer, 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'.
    • renotifyPartyStatus specifies the results of the renotification. On successful renotification, 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'. Note that if the party has no email associated, this can succeed even though no email is actually sent. Naturally, sending a renotification to a party who does not have an email associated with it in the package is a configuration issue.
    • emailAddress is the email address, if any, set for the party
    • pickupCode is the unique pickup code for this party
    • pickupUrl is the ${LINK} value for this party to retrieve/process the transaction
    • lastAccessedTimestamp is the date+time the party last accessed the transaction
<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>

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