← FlexAPI Documentation / Reference / PDF Fields

PDF Fields

PDF fields let signers complete text boxes, check boxes and radio buttons that already exist in your PDF while they sign. In the SubmitDocument request you list the fields in a FormStructure element, group them into sections, and tie each section to the signature that covers it. SIGNiX freezes a section's values when that signature is applied. This page was previously titled Additional Editable Fields.

FormStructure is required only when the document has fields other than signatures, initials, notary seals and date fields. If those are the only fields you use, you do not need it.

Unlike text tagging and coordinate-based tagging, which place signatures and fields on a page, PDF fields are fields you have already built into the PDF. FormStructure says who can edit them and which signature locks them. The signature lines on this page use the AcroForm approach, with named signature fields in the PDF. To compare the approaches, see Choosing a tagging approach on the SubmitDocument page.

On this page

Before you build

  • You may not need FormStructure. It is required only when the document has fields other than signatures, initials, notary seals and date fields.
  • Match names exactly. Every field in the XML needs a PDF field with the same name. Names must be unique across all field types in the document, including SignField, InitialField and DateSignedField. The one exception is radio buttons in the same group, which share a name. Some PDF libraries show a synthetic FieldName.1 for a field's widget. It is the same field, so always use the real field name.
  • Keep names simple. Use A-Z, a-z, 0-9, underscore, dash and period. Avoid quotes, ampersands and other symbols, and stay under 1024 characters. Do not use a sentence from the form as the name.
  • Make editable fields editable. Fields that signers edit or sign must not be read-only or invisible in the PDF. Fields no signer edits should be read-only.
  • One signature per section. A section can be covered by one signature or initial, for one signer. Put Covers on a signer's last signature or initial.
  • List fields in page order. Fields in FormStructure must appear in the order they sit on the form.
  • A validation makes a field mandatory. The signer must enter a matching value before signing.
  • Values are limited to 32767 characters. A longer Value returns Error 104 - Invalid value for parameter 'Value' (too long).

How it works

Why signatures must cover fields. The part of a document a signature covers must not change after the signature is created. Coverage is legally judged by what a reasonable person would expect from the visual appearance of the document, and software cannot reliably judge that. So each signable read/write field must be listed in the transaction metadata, together with the signature lines that cover it. That lets SIGNiX freeze the values when the signature is created.

Workflow. You submit the documents and the transaction metadata in a SubmitDocument request. When a signature line becomes active, the fields in the section it covers open for editing in the document. Validations run when the signer selects Sign. If any fail, signing does not happen until the signer corrects them and selects Sign again. After signing, the covered fields are read-only, so later signers cannot change them. When all signatures are complete, DownloadDocument returns the signed documents with the updated field values, and optionally a Field Data Report.

Preparing the PDF. The PDF must contain a field for every field you list in FormStructure. Fields that some participant will edit must be editable, not read-only. Fields that only carry data should be marked read-only. The document must also meet the field and section rules. An annotated FormStructure follows.

FormStructure - annotated 
<FormStructure> <!-- Optional. Needed only for fields other than signature, initials, notary seal and date. -->
                  <!-- Goes inside Form, after MimeType (and FormPassword), before the SignatureLine elements. -->

  <!-- Optional. Fields outside any Section are in the anonymous section. Use it for fields no
       signer edits, whose values you still want in the Field Data Report. hidden="true" hides
       the field. Attributes are applied after the form is received and before anyone views it. -->
  <FormField name="YOUR_HIDDEN_FIELD" hidden="true" />

  <!-- Every field listed anywhere in FormStructure is included in the field data DownloadDocument
       can return. To include a field without setting anything else, give just its name. -->
  <FormField name="YOUR_FIELD_ID" />

  <!-- A Section groups the fields that one signature covers. The name must be unique among all
       Sections in the Form. -->
  <Section name="YOUR_SECTION_NAME">

    <!-- Mandatory name attribute: the field's name in the PDF. List a field in only one Section. -->
    <FormField name="YOUR_TEXT_FIELD">

      <!-- Optional. Initial value shown in the field. -->
      <Value>YOUR_INITIAL_VALUE</Value>

      <!-- Optional. true makes the field mandatory. -->
      <Required>true</Required>

      <!-- Optional. A Validation also makes the field mandatory, because the signer must enter a
           matching value to proceed. -->
      <Validation>
        <!-- Mandatory. JavaScript (ECMA-262) regular expression the value must match. -->
        <Match>^[^@]+@[^@.]+\.[^@]+$</Match>
        <!-- Mandatory. Message shown if the validation fails. -->
        <ErrorMessage>Please enter a valid email address.</ErrorMessage>
      </Validation>

    </FormField>

  </Section>

  <!-- A Form can contain more Section elements. -->

</FormStructure>

Assigning editing rights

Editing rights are assigned in the SubmitDocument request with two pieces. FormStructure, inside Form, groups the fields into sections. Covers, inside SignatureLine or InitialLine, names the section that signature covers. When the signature is applied, the values of all fields in the covered section are frozen.

Set editInDocument to true to let the signer edit the section in the document first. It defaults to false, which allows no editing but still freezes the covered fields. Covers can be repeated when a signature covers several sections, some of which the signer edits and some of which they cannot. Only one signature can cover a given section. If one party has several signatures on a document, put Covers only on the last signature or initial.

SignatureLine with Covers - annotated 
<SignatureLine> <!-- The usual SignatureLine. Covers is the addition for PDF fields. -->

  <MemberInfoNumber>1</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD</SignField>
  <DateSignedField>YOUR_DATE_FIELD</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>

  <!-- Optional. The Section this signature covers. When the workflow passes this signature, the
       values of all fields in the Section are frozen. editInDocument="true" also lets the signer
       edit the Section in the document. The default is false: no editing, but still frozen.
       A Section can have only ONE signature. For several signatures by one party, put Covers on
       the last signature or initial only. -->
  <Covers section="YOUR_SECTION_NAME" editInDocument="true" />

  <!-- Repeat Covers if the signature also covers other Sections that the signer cannot edit. -->
  <Covers section="YOUR_OTHER_SECTION" />

</SignatureLine>

Field and section rules

A transaction can have one or more Forms. Each Form must follow these rules.

  1. Each FormField must have a name attribute with a unique value.
  2. Each FormField name must be unique across all field types in the Form: editable fields (text, check box, radio button), SignField, InitialField and DateSignedField.
  3. Each FormField, SignField, InitialField and DateSignedField listed in the XML must have a PDF field with a matching name.
  4. Use standard characters in field names: A-Z, a-z, 0-9, underscore (_), dash (-) and period (.). Do not use quotes, ampersands or other symbols. Non-standard characters can cause parsing errors and display or signing problems, and can be caught by SIGNiX security mechanisms. A field name with double quotes can be sent in a PDF, but only as an unattributed field, and it cannot be viewed or uploaded in the Wizard or Editor.
  5. Keep names short and simple, and where possible identify the role or signer, such as Email_Address_Signer1. A name may not exceed 1024 characters. Do not turn the sentence before or after a field into its name. If the form says, “Please provide your email if you would like to open an account,” do not use that sentence as the field name.
  6. PDF fields that will be edited or signed, meaning those named in a FormField, SignField, InitialField or DateSignedField element, must be visible and modifiable. They must not have the read-only or invisible attributes in the PDF.
  7. Fields that belong in the Field Data Report but that no signer edits go in the anonymous section of FormStructure, above the first Section.
  8. Each Section must have a name that is unique among all the Section elements.
  9. Only one signature or initial can cover a section. That means only one Covers element, in one SignatureLine or InitialLine, can name a given section. Best practice: attach the section to the signer's last signature or initial, which also lets you use feature sets.
  10. A section cannot be covered by more than one signer. Best practice: attach it to the first signer, who is usually the main client signer.
  11. Different sections can be covered by different signers. Each signer is prompted for the data in their section, and only that section, when it is their turn. Best practice: put fields for signer 1 in a section covered only by signer 1, and fields for signer 2 in a section covered only by signer 2.
  12. List the elements under FormStructure, whether text fields, check boxes or radio buttons, in the order they appear on the form. For example, listing a radio button group last when it sits at the top of page 1 can cause viewing and display problems during signing, and in some cases may not work at all. Set the PDF tab order to follow left-to-right, top-to-bottom reading order as well.
  13. A Value in a text field may be no longer than 32767 characters, or SubmitDocument returns Error 104 - Invalid value for parameter 'Value' (too long).

The example below shows rules 9 to 11 with two signers, each covering their own section.

Two signers, one section each 
<!-- Two signers. Each signer edits only the Section they cover. -->
<FormStructure>
  <Section name="YOUR_SECTION_SIGNER1">
    <FormField name="YOUR_FIELD_SIGNER1">
      <Value></Value>
      <Required>true</Required>
    </FormField>
  </Section>
  <Section name="YOUR_SECTION_SIGNER2">
    <FormField name="YOUR_FIELD_SIGNER2">
      <Value></Value>
      <Required>true</Required>
    </FormField>
  </Section>
</FormStructure>

<SignatureLine>
  <MemberInfoNumber>1</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD_1</SignField>
  <DateSignedField>YOUR_DATE_FIELD_1</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>
  <Covers section="YOUR_SECTION_SIGNER1" editInDocument="true" />
</SignatureLine>

<SignatureLine>
  <MemberInfoNumber>2</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD_2</SignField>
  <DateSignedField>YOUR_DATE_FIELD_2</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>
  <Covers section="YOUR_SECTION_SIGNER2" editInDocument="true" />
</SignatureLine>

Examples

Each example shows the FormStructure and the SignatureLine that covers it. Replace the YOUR_* placeholders with names from your own PDF.

Editable fields without values (optional)

Use this when you do not send field data with the Form but want to let the signer fill in fields during signing. The signer can leave them blank. If the signer must complete them, use mandatory fields, below.

Optional fields, no initial values 
<FormStructure>
  <Section name="YOUR_SECTION_NAME">
    <FormField name="YOUR_FIELD_1">
      <Value></Value>
    </FormField>
    <FormField name="YOUR_FIELD_2">
      <Value></Value>
    </FormField>
  </Section>
</FormStructure>

<SignatureLine>
  <MemberInfoNumber>1</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD</SignField>
  <DateSignedField>YOUR_DATE_FIELD</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>
  <Covers section="YOUR_SECTION_NAME" editInDocument="true" />
</SignatureLine>

Editable fields with initial values (signer can overwrite)

Use this only if the data the signer might overwrite is not integral to processing the form. If the signer removes a value and does not replace it, the field stays empty. If that is not acceptable, make the field mandatory.

Optional fields with initial values 
<FormStructure>
  <Section name="YOUR_SECTION_NAME">
    <FormField name="YOUR_FIELD_1">
      <Value>YOUR_INITIAL_VALUE_1</Value>
    </FormField>
    <FormField name="YOUR_FIELD_2">
      <Value>YOUR_INITIAL_VALUE_2</Value>
    </FormField>
  </Section>
</FormStructure>

<SignatureLine>
  <MemberInfoNumber>1</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD</SignField>
  <DateSignedField>YOUR_DATE_FIELD</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>
  <Covers section="YOUR_SECTION_NAME" editInDocument="true" />
</SignatureLine>

Mandatory fields

Add Required set to true. The signer cannot sign until the field is completed. Use this when the signer's input is integral to processing the form and it is acceptable to block signing until it is provided. A field can have an initial value and still be required.

Mandatory fields 
<FormStructure>
  <Section name="YOUR_SECTION_NAME">
    <FormField name="YOUR_FIELD_1">
      <Value></Value>
      <Required>true</Required>
    </FormField>
    <FormField name="YOUR_FIELD_2">
      <Value>YOUR_INITIAL_VALUE</Value>
      <Required>true</Required>
    </FormField>
  </Section>
</FormStructure>

<SignatureLine>
  <MemberInfoNumber>1</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD</SignField>
  <DateSignedField>YOUR_DATE_FIELD</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>
  <Covers section="YOUR_SECTION_NAME" editInDocument="true" />
</SignatureLine>

Validation

A Validation element requires the entered value to match a JavaScript (ECMA-262) regular expression, and shows your ErrorMessage if it does not. Adding a validation effectively makes the field mandatory, because the signer must enter a matching value to proceed. Validations run when the signer selects Sign. The field can come in with a value or without one.

Fields with validation 
<FormStructure>
  <Section name="YOUR_SECTION_NAME">

    <!-- Comes in with a value, and must match a date format. -->
    <FormField name="YOUR_DATE_FIELD_1">
      <Value>02/04/1996</Value>
      <Validation>
        <Match>^(0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])[- /.](19|20)\d\d$</Match>
        <ErrorMessage>Please enter a valid date in mm/dd/yyyy format.</ErrorMessage>
      </Validation>
    </FormField>

    <!-- Comes in empty, and must match a date format. -->
    <FormField name="YOUR_DATE_FIELD_2">
      <Value></Value>
      <Validation>
        <Match>^(0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])[- /.](19|20)\d\d$</Match>
        <ErrorMessage>Please enter a valid date in mm/dd/yyyy format.</ErrorMessage>
      </Validation>
    </FormField>

  </Section>
</FormStructure>

<SignatureLine>
  <MemberInfoNumber>1</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD</SignField>
  <DateSignedField>YOUR_DATE_FIELD</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>
  <Covers section="YOUR_SECTION_NAME" editInDocument="true" />
</SignatureLine>

Editable and non-editable fields together

Use this when some fields need the signer's input and others should be initialized with data the signer cannot change, but you want the values of all of them back from DownloadDocument. Put the non-editable fields in the anonymous section, above the first Section, and mark them read-only in the PDF.

Editable and non-editable fields 
<FormStructure>

  <!-- Anonymous section: values returned in the Field Data Report, not editable by the signer. -->
  <FormField name="YOUR_READ_ONLY_FIELD_1">
    <Value>YOUR_VALUE_1</Value>
  </FormField>
  <FormField name="YOUR_READ_ONLY_FIELD_2">
    <Value>YOUR_VALUE_2</Value>
  </FormField>

  <!-- Editable section. -->
  <Section name="YOUR_SECTION_NAME">
    <FormField name="YOUR_EDITABLE_FIELD">
      <Value>YOUR_INITIAL_VALUE</Value>
    </FormField>
  </Section>

</FormStructure>

<!-- Several signatures by one signer: Covers goes only on the last one. -->
<SignatureLine>
  <MemberInfoNumber>1</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD_1</SignField>
  <DateSignedField>YOUR_DATE_FIELD_1</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>
</SignatureLine>

<SignatureLine>
  <MemberInfoNumber>1</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD_2</SignField>
  <DateSignedField>YOUR_DATE_FIELD_2</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>
  <Covers section="YOUR_SECTION_NAME" editInDocument="true" />
</SignatureLine>

Anonymous fields only (no editable fields)

Use this when no field needs editing but you still want the field values in the DownloadDocument response. The empty Section is shown for completeness.

Anonymous fields only 
<FormStructure>
  <FormField name="YOUR_FIELD_1">
    <Value>YOUR_VALUE_1</Value>
  </FormField>
  <FormField name="YOUR_FIELD_2">
    <Value>YOUR_VALUE_2</Value>
  </FormField>
  <Section name="YOUR_SECTION_NAME">
  </Section>
</FormStructure>

<SignatureLine>
  <MemberInfoNumber>1</MemberInfoNumber>
  <SignField>YOUR_SIGNATURE_FIELD</SignField>
  <DateSignedField>YOUR_DATE_FIELD</DateSignedField>
  <DateSignedFormat>MM/dd/yy</DateSignedFormat>
</SignatureLine>

Complete SubmitDocument request

This request puts it all together for one PDF and two signers. An anonymous field comes first, then a section for each signer, and each signer's signature line covers that signer's section. Note where FormStructure sits in the Form: after MimeType and before the SignatureLine elements. For the other elements of the request, see the annotated sample on the SubmitDocument page.

Complete SubmitDocument request with FormStructure 
<?xml version="1.0" ?>
<SubmitDocumentRq xmlns="urn:com:signix:schema:sdddc-1-1">

  <CustInfo>
    <Sponsor>YOUR_SPONSOR</Sponsor>
    <Client>YOUR_CLIENT</Client>
    <UserId>YOUR_USER</UserId>
    <Pswd>YOUR_PASSWORD</Pswd>
    <Workgroup>YOUR_WORKGROUP</Workgroup> <!-- Optional. -->
    <Demo>yes</Demo> <!-- Required. yes for demo and test, no for a real transaction. -->
  </CustInfo>

  <Data>
    <TransactionID>YOUR_TRANSACTION_ID</TransactionID> <!-- Exactly 36 characters. -->
    <DocSetDescription>YOUR_TRANSACTION_TITLE</DocSetDescription>
    <SubmitterEmail>YOUR_SUBMITTER_EMAIL</SubmitterEmail>
    <SubmitterName>YOUR_SUBMITTER_NAME</SubmitterName>
    <ContactInfo></ContactInfo>
    <DeliveryType>SDDDC</DeliveryType>
    <SuspendOnStart>no</SuspendOnStart>

    <MemberInfo> <!-- Signer 1 -->
      <RefID>YOUR_SIGNER1_REF_ID</RefID>
      <SSN>910000000</SSN>
      <DOB>00/00/0000</DOB>
      <FirstName>YOUR_FIRST_NAME_1</FirstName>
      <MiddleName></MiddleName>
      <LastName>YOUR_LAST_NAME_1</LastName>
      <Email>YOUR_SIGNER1_EMAIL</Email>
      <Service>SelectOneClick</Service>
    </MemberInfo>

    <MemberInfo> <!-- Signer 2 -->
      <RefID>YOUR_SIGNER2_REF_ID</RefID>
      <SSN>910000000</SSN>
      <DOB>00/00/0000</DOB>
      <FirstName>YOUR_FIRST_NAME_2</FirstName>
      <MiddleName></MiddleName>
      <LastName>YOUR_LAST_NAME_2</LastName>
      <Email>YOUR_SIGNER2_EMAIL</Email>
      <Service>SelectOneClick</Service>
    </MemberInfo>

    <Form>
      <RefID>YOUR_FORM_REF_ID</RefID>
      <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
      <FileName>YOUR_FILE_NAME.pdf</FileName>
      <MimeType>application/pdf</MimeType>

      <!-- FormStructure goes here: after MimeType, before the SignatureLine elements. List the
           fields in the order they appear on the PDF. -->
      <FormStructure>

        <!-- Anonymous section: returned in the Field Data Report, not editable. -->
        <FormField name="YOUR_READ_ONLY_FIELD">
          <Value>YOUR_VALUE</Value>
        </FormField>

        <!-- Signer 1 completes this section. -->
        <Section name="YOUR_SECTION_SIGNER1">
          <FormField name="YOUR_EMAIL_FIELD_SIGNER1">
            <Value></Value>
            <Required>true</Required>
            <Validation>
              <Match>^[^@]+@[^@.]+\.[^@]+$</Match>
              <ErrorMessage>Please enter a valid email address.</ErrorMessage>
            </Validation>
          </FormField>
          <FormField name="YOUR_CHECKBOX_SIGNER1">
            <Value>Off</Value>
            <Validation>
              <Match>Yes</Match>
              <ErrorMessage>You must accept the terms to complete this transaction.</ErrorMessage>
            </Validation>
          </FormField>
        </Section>

        <!-- Signer 2 completes this section. -->
        <Section name="YOUR_SECTION_SIGNER2">
          <FormField name="YOUR_RADIO_GROUP_SIGNER2">
            <Value>OFF</Value>
            <Required>true</Required>
          </FormField>
        </Section>

      </FormStructure>

      <!-- Each signature covers its signer's section. -->
      <SignatureLine>
        <MemberInfoNumber>1</MemberInfoNumber>
        <SignField>YOUR_SIGNATURE_FIELD_1</SignField>
        <DateSignedField>YOUR_DATE_FIELD_1</DateSignedField>
        <DateSignedFormat>MM/dd/yy</DateSignedFormat>
        <Covers section="YOUR_SECTION_SIGNER1" editInDocument="true" />
      </SignatureLine>

      <SignatureLine>
        <MemberInfoNumber>2</MemberInfoNumber>
        <SignField>YOUR_SIGNATURE_FIELD_2</SignField>
        <DateSignedField>YOUR_DATE_FIELD_2</DateSignedField>
        <DateSignedFormat>MM/dd/yy</DateSignedFormat>
        <Covers section="YOUR_SECTION_SIGNER2" editInDocument="true" />
      </SignatureLine>

      <Length>PDF_BYTE_LENGTH</Length>
      <Data>BASE64_PDF</Data>
    </Form>

  </Data>
</SubmitDocumentRq>

Field types: text, check boxes and radio buttons

Text fields

Text fields work as shown in the examples above.

Check boxes

A check box field is a single box, or a group of related or unrelated boxes, that operate independently. The signer can toggle each one on or off and can select more than one in a group. For example, to the question “Which colors do you like?” a signer could check none, one, several or all of Blue, Yellow, Red and Green.

A check box has two states, on and off. SIGNiX marks a check box as checked if either of these is true:

  • The field is already checked in the PDF.
  • The field has an export value in the PDF that is not Off, and the request has a Value for the field that matches the export value, or equals On (any case), Yes (any case) or 1.

Add a Validation to require a particular state: Match of Yes requires the box to be checked, and Off requires it to be unchecked. Leave out the Validation to allow either state. The example below is a check box named YOUR_CHECKBOX that is off by default and that the signer must check.

If only one choice can be selected from a group, use radio buttons instead. SIGNiX will honor a check box as a radio button if the field has the elements that a radio button is read by, but PDF best practice is always to use real radio buttons.

Check box the signer must check 
<!-- Off by default. The signer must check it before signing. -->
<FormField name="YOUR_CHECKBOX">
  <Value>Off</Value>
  <Validation>
    <Match>Yes</Match>
    <ErrorMessage>You must accept the terms to complete this transaction.</ErrorMessage>
  </Validation>
</FormField>

Radio buttons

A radio button field is a group of related, mutually exclusive buttons. For example, to the question “Which is your one favorite color?” the signer must choose exactly one of Blue, Yellow, Red or None of the Above. If more than one choice can be selected, use check boxes instead.

Conventionally, once a radio button is set you can only set a different one, never clear them all. A PDF can be configured to allow toggling a set button off, which leaves none selected. In a PDF, several buttons can also represent the same choice. If the “radios in unison” option is on, selecting or clearing any one of them selects or clears them all. That is useful when the same choice should be available on several pages.

All the buttons in a group must have the same name. Each button has an on value and an off value, and the value of the field is the on value of the selected button. SIGNiX marks a button as chosen if either of these is true:

  • The request has a Value for the field that matches the button's export value.
  • The request has a Value that does not match any export value but matches the index of a button, starting at 0. For example, with three buttons whose export values are 5, 10 and 15, a Value of 0 selects the first button. A Value of 4 selects none, because it matches neither an export value nor an index.

The examples below show the common cases: a value is required and a choice is already selected; a value is required and nothing is selected yet; nothing is selected yet and the signer may choose not to answer; and a required choice with a field-specific error message. To make a radio group optional, leave out Required. Conditional validation is not currently supported.

Radio button groups 
<!-- 1. A choice is required, and one button is already selected (here the button with value 1). -->
<FormField name="YOUR_RADIO_GROUP_1">
  <Value>1</Value>
  <Required>true</Required>
</FormField>

<!-- 2. A choice is required, but nothing is selected yet. Value can also be left out. -->
<FormField name="YOUR_RADIO_GROUP_2">
  <Value>OFF</Value>
  <Required>true</Required>
</FormField>

<!-- 3. Optional: nothing is selected yet, and the signer may choose not to answer. -->
<FormField name="YOUR_RADIO_GROUP_3">
  <Value>OFF</Value>
</FormField>

<!-- 4. The signer must select a particular button, and gets a field-specific message if not. -->
<FormField name="YOUR_RADIO_GROUP_4">
  <Value>NotAccepted</Value>
  <Validation>
    <Match>Accepted</Match>
    <ErrorMessage>You must accept the terms to complete this transaction.</ErrorMessage>
  </Validation>
</FormField>

<!-- 5. The signer must select Yes or No from a group with nothing selected yet. The message
        shows in red in a dialog when no button is selected. -->
<FormField name="YOUR_RADIO_GROUP_5">
  <Value>OFF</Value>
  <Validation>
    <Match>^([yY]es|[nN]o)$</Match>
    <ErrorMessage>Please select a radio button.</ErrorMessage>
  </Validation>
</FormField>

Warning: some PDF form providers build fields that look like radio buttons but are really check boxes with nonstandard settings that make them behave like radio buttons. Depending on those settings they can conflict with how SIGNiX works, because SIGNiX follows the radio button specification on page 441 of the PDF 32000-1:2008 standard. Make sure the Radio flag and other settings on those fields are correct.

Optional features and the Field Data Report

Editable Fields Focus

Editable Fields Focus is turned on by SIGNiX on request. Each SubmitDocument call is reviewed as it is received to confirm it is compatible with the feature (see the requirements below).

Normally the signer is taken to every optional and mandatory field before reaching the signature. With this feature the signer goes directly to the first mandatory field, then to each next one in turn, until reaching the signature assigned to those fields. If all mandatory fields are complete, the signer can sign. If one was missed, a popup warns the signer that there is still action to take. This suits signers who have already read the document and only want to fill in the mandatory fields and sign.

Requirements.

  • If you use mandatory fields with this feature, the fields in each section must sit above the signature block that covers them in the document. If you cannot split the fields into sections that sit above each signature, assign the section to the very last SignatureLine or InitialLine. If you cannot do that either, your API cannot use the feature.
  • Mandatory radio buttons must be built as radio buttons in the PDF, not as check boxes that look like radio buttons. Otherwise the signer may be forced to check every box in a group before signing. For example, in a Male or Female group where both buttons are mandatory, the signer could be forced to check both.

Field Data Report

DownloadDocument can optionally include the document field data in its response. Set IncludeFieldData to true in the request. It is optional and defaults to false. When requested, the response contains the value of each field listed in the FormStructure section of the original SubmitDocument request. The returned data matches the content of the fields element of XFDF (see Adobe, XML Forms Data Format Specification, Version 2.0, September 2007). For the rest of the DownloadDocument request and response, see DownloadDocument.

DownloadDocument request with field data 
<!-- DownloadDocument request: only the part that matters here. CustInfo and the other elements are
     as on the DownloadDocument page. -->
<Data>
  <DocumentSetID>YOUR_DOCUMENT_SET_ID</DocumentSetID>

  <!-- Optional. Whether a field data report is included in the response. Defaults to false. -->
  <IncludeFieldData>true</IncludeFieldData>
</Data>

In the response, each Form carries a Fields element when IncludeFieldData was true. The Form elements come back in the same order as in the SubmitDocument request.

DownloadDocument response with field data 
<!-- DownloadDocument response: only the part that matters here. -->
<Form> <!-- Once for each document, in the order of the SubmitDocument request. -->
  <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
  <FileName>YOUR_FILE_NAME.pdf</FileName>
  <MimeType>application/pdf</MimeType>
  <Length>PDF_BYTE_LENGTH</Length>

  <!-- Present if IncludeFieldData was true in the request. One Field per field in FormStructure. -->
  <Fields>
    <Field name="YOUR_FIELD_1">
      <Value>YOUR_VALUE_1</Value>
    </Field>
    <!-- Other Field elements, if needed. -->
  </Fields>

  <Data>BASE64_PDF</Data>
</Form>

Back to top

SIGNiX Products

Industries We Serve

Support

©2016 SIGNiX. All Rights Reserved.