← FlexAPI Documentation / API Calls / DownloadDocument

DownloadDocument

The DownloadDocument method picks up all the completed documents for a transaction, along with its accompanying evidence in the form of a longer Audit Trail and a shorter Certificate of Completion. It moves the completed documents from the SIGNiX system back to your integrated (OEM / Client) application. This call is REQUIRED for all transactions.

Once your application has received and stored the results, it confirms receipt with ConfirmDownload, which is a separate call described on its own page.

On this page

Before you call

  • Do not send Demo. It belongs only on SubmitDocument. Sending it here is a schema error ("Invalid content was found starting with element 'Demo'").
  • Mind the element order. Inside Data the order is: DocumentSetID, IncludeFieldData, IncludeAttachmentData (if used), IncludeAuditData, AuditDataFormat, UseConfirmDownload, then IncludeCertificateOfCompletion. The element is AuditDataFormat, not AuditTrailFormat. Putting AuditDataFormat after UseConfirmDownload has caused schema errors on live tenants.
  • Wait for completion. Download only when the transaction is complete. See Download, store, confirm below.

DownloadDocument - Request XML

An annotated example of the request XML follows.

Audit trail. The IncludeAuditData parameter is REQUIRED and must be set to 'true', so that a copy of the transaction Audit Trail is included in the response. The Audit Trail may be received as:

  • a digitally-signed PDF (most common, for easy storage and retrieval by clients who need a copy for legal purposes),
  • a digitally-signed XML file (useful for applications that need values from the XML response for back-office actions), or
  • both PDF and XML (for applications that need a human-readable copy for clients, while servers also read the response data).

SIGNiX does archive, and may delete, transaction data, because OEM applications are expected to retrieve and store all transaction data. If an Audit Trail is needed after it has been archived, a Professional Services fee may apply for its retrieval. If data has been deleted (per contract or other record retention rules), it is no longer retrievable.

DownloadDocument - annotated request 
<?xml version="1.0" ?>
<DownloadDocumentRq xmlns="urn:com:signix:schema:sdddc-1-1">

  <CustInfo> <!-- Occurs once only -->

    <!-- Assigned by SIGNiX when the Client is set up. All case sensitive. -->
    <Sponsor>YOUR_SPONSOR</Sponsor>
    <Client>YOUR_CLIENT</Client>
    <UserId>YOUR_USER</UserId>
    <Pswd>YOUR_PASSWORD</Pswd>

    <!-- Identifies the billing party for this transaction. Primarily used by Clients that need to
         differentiate between divisions, end users and so on, to bill them in return or allocate
         cost for reporting. Appears on SIGNiX billing reports. Optional. Can be left blank.
         Max length 50. -->
    <BillingRef>SmithRealty</BillingRef>

  </CustInfo>

  <Data> <!-- Occurs once only -->

    <!-- Identifies the document set with an opaque identifier: the DocumentSetID returned in the
         SubmitDocument response. -->
    <DocumentSetID>YOUR_DOCUMENT_SET_ID</DocumentSetID>

    <!-- Optional. Whether data entered into fields during signing is returned as discrete data in
         the response. Can help populate your integrated application with data entered on the
         PDF. -->
    <IncludeFieldData>true</IncludeFieldData>

    <!-- If you use signer attachments, add IncludeAttachmentData here, ABOVE IncludeAuditData.
         See Signer attachments below. -->

    <!-- Whether the audit data (audit trail) is included in the response. Both the element and the
         value (true) are required. -->
    <IncludeAuditData>true</IncludeAuditData>

    <!-- Required. The format of the audit trail: pdf (most common), xml, or both. IMPORTANT:
         whatever the format, your receiving platform must store the resulting file or files. -->
    <AuditDataFormat>pdf</AuditDataFormat>

    <!-- Whether you must use ConfirmDownload to acknowledge receipt. Mandatory, and required to
         implement a retention policy. -->
    <UseConfirmDownload>true</UseConfirmDownload>

    <!-- Optional. Also downloads a summary certificate of completion that includes a subset of
         the larger audit trail's data. Not a substitute for the full audit trail (see
         IncludeAuditData), but may be added as additional evidence in certain use cases. -->
    <IncludeCertificateOfCompletion>true</IncludeCertificateOfCompletion>

  </Data>

</DownloadDocumentRq>

Downloading only the audit trail

If you want to download the audit trail and NO other transaction documents, add ExcludeDocuments to the call, together with IncludeAuditData. The UseConfirmDownload parameter MUST be omitted when you use this option.

DownloadDocument - audit trail only 
<Data>

  <DocumentSetID>YOUR_DOCUMENT_SET_ID</DocumentSetID>

  <IncludeAuditData>true</IncludeAuditData>
  <AuditDataFormat>pdf</AuditDataFormat>

  <!-- Optional. Excludes the documents from the download so that, together with IncludeAuditData,
       only the audit trail is downloaded. UseConfirmDownload MUST be omitted when this option is
       used. -->
  <ExcludeDocuments>true</ExcludeDocuments>

</Data>

Downloading signer attachments

If your transaction uses signer attachments (see Signer Attachments in the SubmitDocument additional options), the attached documents are returned with the DownloadDocument response, but only if you add the IncludeAttachmentData parameter to the call. Attachments are also noted as an event in the audit trail.

IncludeAttachmentData is mandatory if attachments are used. It must be placed ABOVE the IncludeAuditData element, otherwise an error is thrown.

IncludeAttachmentData (fragment) 
<DownloadDocumentRq xmlns="urn:com:signix:schema:sdddc-1-1">

  <!-- ... CustInfo ... -->

  <Data>

    <DocumentSetID>YOUR_DOCUMENT_SET_ID</DocumentSetID>

    <!-- ... -->

    <!-- Mandatory if attachments are used. Returns the signers' attached documents with the
         response. MUST be placed ABOVE IncludeAuditData, otherwise an error is thrown. -->
    <IncludeAttachmentData>true</IncludeAttachmentData>

    <IncludeAuditData>true</IncludeAuditData>

    <!-- ... -->

  </Data>

</DownloadDocumentRq>

DownloadDocument - Response XML

An annotated example of the response XML follows. See Status Codes on the main API page for the possible values and meanings of the StatusCode and StatusDesc elements.

For more information on the content and format of the audit trail, see the Audit Trail schema (AuditTrailXMLSchema) and/or the Understanding SIGNiX Signatures and Audit Trails document, available from SIGNiX.

Handle the response in this order:

  • An HTTP 200 does not mean success. Parse the XML and check that StatusCode is 0 before reading anything else.
  • Map the returned documents back to the Forms you submitted by their order and/or RefID. Keep your download bookkeeping per DocumentSetID, because the same logical document can appear in more than one transaction.
  • Decode each Base64 Data block and check that the number of decoded bytes matches Length before you store it.
DownloadDocument - annotated response 
<?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 is the same unique
         TransactionID value included in the original SubmitDocument request. The DocumentSetID
         can also be used. -->
    <TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID>

    <!-- Optional, max length 255. If the Data-level FileName was present in the SubmitDocument
         request, it is returned here with the same value. -->
    <FileName>J-Smith_02242005_032557.zip</FileName>

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

      <!-- Document title. Appears when the document is listed in the transaction. -->
      <Desc>Express Application #1</Desc>

      <!-- Optional, max length 255. If the Form-level FileName was present in the SubmitDocument
           request, it is returned here with the same value. -->
      <FileName>J-Smith_Express_Application.pdf</FileName>

      <!-- The next three elements provide the document itself. Presently, PDF is the only
           document format supported. -->
      <MimeType>application/pdf</MimeType>
      <Length>PDF_BYTE_LENGTH</Length> <!-- Length of the document, when decoded, in bytes -->
      <Data>BASE64_PDF</Data> <!-- The bytes of the entire document, encoded in Base64 -->

    </Form>

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

    <!-- Long-form transactional audit trail as a PDF. Occurs only if IncludeAuditData is true
         in the request and the format is pdf. -->
    <AuditReport>
      <FileName>J-Smith_Express_Application_audit_trail.pdf</FileName> <!-- File name for the audit trail itself -->
      <MimeType>application/pdf</MimeType>
      <Length>PDF_BYTE_LENGTH</Length> <!-- Length of the document, when decoded, in bytes -->
      <Data>BASE64_PDF</Data> <!-- The bytes of the entire document, encoded in Base64 -->
    </AuditReport>

    <!-- Transaction audit log as XML. Occurs only if IncludeAuditData is true in the request and
         the format is 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>

    <!-- Summary certificate of completion, with a subset of the audit trail's data. Occurs only if
         IncludeCertificateOfCompletion is true in the request. It is not a substitute for the
         full audit trail. Always delivered as a PDF. -->
    <CertificateOfCompletion>
      <FileName>J-Smith_Express_Application_CertificateOfCompletion.pdf</FileName> <!-- File name for the certificate itself -->
      <MimeType>application/pdf</MimeType>
      <Length>PDF_BYTE_LENGTH</Length> <!-- Length of the document, when decoded, in bytes -->
      <Data>BASE64_PDF</Data> <!-- The bytes of the entire document, encoded in Base64 -->
    </CertificateOfCompletion>

  </Data>

</DownloadDocumentRs>

Download, store, confirm

When to call. Call DownloadDocument when the transaction is complete. The most reliable trigger is the complete event in a push notification, rather than a polling loop. Your push handler should reply OK immediately and queue the download, instead of running it during the HTTP request. If a push is missed, you can reconcile with a SubmitAjax QueryTransactionStatus request (it is not a standalone method), no more often than every 10 minutes.

The sequence.

  1. Call DownloadDocument and check that StatusCode is 0.
  2. Store every returned file durably (the documents, the audit trail, the certificate of completion and any signer attachments you requested), and verify that the writes succeeded.
  3. Only then call ConfirmDownload, once.

If the download or the storage fails, retry the download and do not call ConfirmDownload. Make the pipeline idempotent, so that a duplicate complete notification cannot trigger a second confirmation.

Retention and deletion

To implement a retention policy (document deletion / purge schedules), set the DelDocsAfter element in the CustInfo of the SubmitDocument request. It is a number of days, counted from the ConfirmDownload call for a completed transaction. BOTH of the following are then required:

  • the UseConfirmDownload parameter must be set to 'true' in the DownloadDocument call, AND
  • the ConfirmDownload call must be made after the download, to confirm that your application successfully received all the documents.

If either is missing, retention policies 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 your account is not enabled, DelDocsAfter is ignored.

Warning: the deletion countdown starts at ConfirmDownload. Call ConfirmDownload only after your application has stored the downloaded documents, not immediately after the download call. If you confirm too early, the documents can be deleted while your system still has no durable copy.

If a document set is complete, your application has received the downloaded documents, and the ConfirmDownload has been received and responded to, 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, its status becomes "PendingDeletion".
  • If the document set's post-completion availability period has expired, 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 has 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 "PendingDeletion" 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.

Back to top

SIGNiX Products

Industries We Serve

Support

©2016 SIGNiX. All Rights Reserved.