Attachments & External Documents

Quik! lets end users attach files to a form package and lets you programmatically add external documents (such as a scanned driver's license or a system-generated PDF) to the package for printing and e-signature. This guide covers enabling or disabling the attachment feature, adding external documents to a form package, and the special handling required to include external documents in an e-signature envelope.

What it is

Two related but distinct capabilities sit under "attachments":

• The attachment panel in the Quik! Form Viewer, where end users can add their own files to the package. You control whether this panel appears with a single property.
• External documents that you add to a package programmatically through the API (for example, a driver's license photocopy or a contract generated by another system). These are uploaded against the form package's transaction ID and merged into the package for print or e-signature.

Quik! supports image files and PDFs as attachments. Each uploaded document is encrypted in transit and at rest with a unique per-document key using standard 128-bit (or stronger) encryption, is never accessible to Quik! employees or other customers, and is deleted from the server within 10 days (per the form package's expiration date). Individual attachments must not exceed 20 MB.

Enabling or disabling the attachment panel

The Quik! Forms Engine exposes a DisableAttachments property (type bool, default false). When false, the attachment panel and the attachment icons near fields are shown. Set it to true to hide the attachment panel in the Quik! Form Viewer and the attachment icons near fields on the form — disabling the feature entirely.

Set it the same way you set any other Forms Engine property. Over REST, add it to the HTMLSettings object in your execute/html request body, using the property name verbatim as the JSON key:

{
  "DisableAttachments": true,
  "QuikFormID": "12"
}

If you integrate through the .NET object, set the property directly:

' VB.NET
objQFE.DisableAttachments = True

// C#
objQFE.DisableAttachments = true;

Adding external documents to a form package

To include an external PDF with a form package, upload it against the package's transaction ID (UNID) using the REST attachment endpoints.

Prerequisites

• You must run the Quik! Forms Engine Execute method before uploading, in order to obtain the UNID value that the attachment is associated with.
• Each attachment must not exceed 20 MB.

Attachment endpoints

The attachment endpoints are part of the Quik! Forms Engine REST service. The base URL is:

• Production: https://websvcs.quikforms.com/rest/quikformsengine
• UAT: https://uatwebsvcs.quikforms.com/rest/quikformsengine

Append the paths below to that base. For example, the production Get Attachments call is https://websvcs.quikforms.com/rest/quikformsengine/attachments?unid=<unid>.

For the full, always-current request and response schemas, see the Forms Engine API reference (the Swagger UI for production, or https://uatwebsvcs.quikforms.com/rest/quikformsengine/swagger/index.html for UAT).

Encoding UNID values in the query string. The UNID Quik! shows you is already URL-encoded (you will see %2b or %2f in it). When you place an encoded UNID directly in a query string — as with Get Attachments — the .NET framework decodes it once and Quik! decodes it again, which produces an error. To avoid this, encode the value once more before building the URL (in .NET, HttpUtility.UrlEncode(unid)), so that, for example, % becomes %25 and arrives as % again at the API.

Upload parameters

Ordering behavior. Each form in a package has a position based on the order it was generated. When BeforeForm is false, an attachment is placed after the form whose position matches its DocSortOrder. For example, if Forms 1 and 2 are generated together (positions 1 and 2) and Attachment A is uploaded with BeforeForm = false and DocSortOrder = 1, the attachment is placed after Form 1 and before Form 2. To show it after Form 2, set DocSortOrder to 2 or greater. To place multiple attachments at the same position, upload them all with the same DocSortOrder value — they are then ordered in ascending order by upload order.

Example: upload an attachment

{
  "Unid": "WRpsWX3PnO5VgWxUTUTKIN%2fKxE%2bA09amHDBBi%2fwe3vLWSZwHUY7HOgyFmrKm6BAy",
  "Attachments": [
    {
      "Name": "testattach3.pdf",
      "Path": "",
      "Content": "<really long base64 string>",
      "DocSortOrder": 1,
      "BeforeForm": false
    }
  ]
}

Legacy: the AddDocToForms method (.NET SDK)

If you integrate through the Quik! Forms Engine .NET object rather than the REST attachment endpoints, use the AddDocToForms method to build a list of documents, then call Upload to send them to Quik!. Each call to AddDocToForms adds one more document to the list.

AddDocToForms operates independently of the engine's other features: data loaded through it is ignored when Execute runs, and is only sent to Quik! when Upload runs. This lets you run document upload separately from form generation. As with the REST flow, you must run Execute first to obtain a FormViewRequestUNID, and attachments must not exceed 20 MB.

' VB.NET
objQFE.AddDocToForms(objQFE.FormViewRequestUNID, "driverslicense.pdf", "c:\temp\", 2, False)
objQFE.Upload()

Including external documents in the e-signature envelope

Adding an external document to an e-signature envelope is harder than adding it to a print package, because of how Quik! tells the e-sign vendor where to sign and who signs. For forms in the Quik! library, the Quik! Field Definition supplies all of this information automatically. An external document — one that is not in the Quik! library — carries no field definition, so Quik! cannot tell the e-sign vendor where the signing fields are or which recipient owns them.

There are three approaches.

Add your documents to the Quik! library

Every form added to the Quik! library is built to be e-signed with all supported e-sign vendors with no additional effort, which makes this the ideal solution. It does not work for documents generated in real time by another system — contracts, illustrations, hypotheticals, proposals, and similar generated documents.

DocuSign: Draft Mode plus anchor tags

For DocuSign, combine DocuSign Draft Mode with anchor tags. This requires some intervention by your system and/or your user.

1. Make sure your document has anchor tags on it — text placed where a field should go that DocuSign recognizes and converts into a signing field. See DocuSign's anchor tag documentation. (If you cannot use anchor tags, use the Self Service Model below.)
2. Configure the Quik! Forms Engine execute/html call to use DocuSign Draft Mode by setting the CreateEnvelopeAsDraft property to true.
3. Add your document (with anchor tags) to the Quik! package using the attachment upload flow described above (the REST /attachments/upload endpoint, or the legacy AddDocToForms method).
4. Generate the Quik! form package and have the user complete the form.
5. When the user submits the form to be signed (clicks Sign, then Send in the Quik! Form Viewer), the attachment is sent along with the forms. In DocuSign the envelope lands in Draft status; the user must log in, open the draft envelope, and assign recipients to the anchor tags on the external document. Anchor tags let DocuSign place the signing fields automatically, but DocuSign still does not know who signs which fields — so the envelope must be edited to assign signers.

It may be possible to assign signers to anchor tags programmatically through the DocuSign API, but there are no documented Quik! steps for doing so. Consult the DocuSign APIs if you want to automate this step.

DocuSign: Self Service Model

The Self Service Model gives you full control over the process at the cost of more programmatic work. It is intended to let you do anything you need with DocuSign and Quik!. Its core components are:

1. Quik! creates the PDF and the metadata DocuSign needs — you call the Quik! APIs to retrieve both.
2. You build the DocuSign API call and pass the documents and metadata to DocuSign to generate a new envelope. This is where you add your own external documents alongside the Quik! PDFs, and where you create your own signer metadata (or augment Quik!'s metadata) describing how signers sign your external documents.

This approach gives you the most control but requires the most effort, because you are combining two sets of documents that each have their own field/tag naming conventions.

A note on SIGNiX

The Draft Mode, anchor tag, and Self Service approaches above apply to DocuSign. There is currently no equivalent mechanism for adding external documents to a SIGNiX e-signature package.

Related articles

• Grouping and Bundling
• Send Direct to DocuSign
• Configuring the Submit Button
• Testing a Form in Final Mode