← FlexAPI Documentation / API Calls / AnalyzeDocument

AnalyzeDocument

The AnalyzeDocument method gives integrators access to document analysis and modification tools through the Flex API, including SIGNiX form field detection. It returns a Form structure that you can use when building a SubmitDocument request. It also has optional controls over how the detection model works that are not available to end users in the SIGNiX Wizard or Editor. Available in SIGNiX release 184.

Before you call

  • Discovering new fields needs account configuration. To have SIGNiX discover new fields, your account must be configured for the SIGNiX form field detection capability. Contact SIGNiX to set this up. A request to discover new fields fails until it is.
  • Only two options are required. KeepExistingFields and DiscoverNewFields are the only required elements in Options. Everything else is optional tuning.
  • The returned Form is formatted like the Form in SubmitDocument. Copy it into your SubmitDocument request. See PDF Fields for how FormStructure works.
  • Set the RefID. The returned Form has an empty RefID, so fill it in for SubmitDocument.
  • Fields are assigned to a single signer. Returned signature fields all use MemberInfoNumber 1. To use them with several signers, re-assign the fields to the right signers in your SubmitDocument request.
  • Use the same CustInfo credentials as your other requests (Sponsor, Client, UserId and Pswd).

Modes of operation

The two required options, KeepExistingFields and DiscoverNewFields, select one of four modes. KeepExistingFields controls whether form fields already in the PDF are maintained rather than deleted or overwritten. DiscoverNewFields controls whether SIGNiX tries to discover new fields with its detection model.

ModeKeepExistingFieldsDiscoverNewFieldsWhat you get back
Detect existing onlytruefalseA Form structure for the fields already in the PDF.
Discover new fields onlyfalsetrueA Form structure for the newly discovered fields, and the Base64 of the PDF with those fields added.
Detect existing and discover newtruetrueA Form structure for both the existing and the discovered fields, and the Base64 of the PDF with all of them.
Remove existing fieldsfalsefalseThe Base64 of the PDF with its existing form fields removed.

AnalyzeDocument - Request XML

An annotated example of the request XML follows. Only KeepExistingFields and DiscoverNewFields are required in Options. The other options customize how the detection model works.

Confidence levels. Each ConfidenceLevel option takes a value from 0 to 100. The higher the level, the more confident the model must be before it returns a field of that type. Setting a level to 100 filters that field type out. For example, to return only possible signature fields, set TextDataFieldConfidenceLevel and OptionDataFieldConfidenceLevel to 100 and leave EndorsementFieldConfidenceLevel at its default.

AnalyzeDocument - annotated request
<?xml version="1.0" ?>
<AnalyzeDocumentRq 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>

  </CustInfo>

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

    <Options>

      <!-- Required. true or false. Whether form fields already in the PDF are kept, and not deleted or overwritten. -->
      <KeepExistingFields>true</KeepExistingFields>

      <!-- Required. true or false. Whether SIGNiX tries to discover new fields. The account must be configured for form field detection. -->
      <DiscoverNewFields>false</DiscoverNewFields>

      <!-- Everything below is optional. -->

      <!-- DEFAULT is recommended. LOW, MEDIUM and HIGH are also accepted. -->
      <Resolution>DEFAULT</Resolution>

      <!-- Confidence levels, 0 to 100. The higher the level, the more confident the model must be to return a field.
           The values below are examples. -->
      <EndorsementFieldConfidenceLevel>30</EndorsementFieldConfidenceLevel> <!-- Signatures and initials -->
      <TextDataFieldConfidenceLevel>70</TextDataFieldConfidenceLevel> <!-- Text fields -->
      <OptionDataFieldConfidenceLevel>50</OptionDataFieldConfidenceLevel> <!-- Option fields, such as check boxes and radio buttons -->

      <!-- The percentage by which fields may overlap one another. -->
      <OverlappingPercentage>25</OverlappingPercentage>

      <!-- The specific pages of the document on which to run form field detection. -->
      <Pages>
        <Page>1</Page>
      </Pages>

    </Options>

    <Form> <!-- The document to analyze -->
      <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
      <MimeType>application/pdf</MimeType>
      <Length>YOUR_LENGTH</Length> <!-- Length of the encoded PDF -->
      <Data>BASE64_PDF</Data> <!-- The encoded PDF -->
    </Form>

  </Data>

</AnalyzeDocumentRq>

AnalyzeDocument - Response XML

Annotated examples of the response XML follow, one for each mode, plus the case where no fields are found. See Status Codes on the main API page for the possible values and meanings of the StatusCode and StatusDesc elements.

  • Check that StatusCode is 0 before reading anything else.
  • The count elements list how many fields of each type were found. ExistingFormFieldCounts covers fields already in the PDF, NewFormFieldCounts covers fields SIGNiX discovered, and TotalFormFieldCounts covers all of them.
  • Other field types come back in the Form as they do in a typical SubmitDocument Form.
  • The Data element of the returned Form holds the Base64 PDF, with new fields added when you asked to discover them.

Detect existing fields only

With KeepExistingFields true and DiscoverNewFields false, the response lists the existing fields found in the PDF in ExistingFormFieldCounts, along with a Form that you can copy into a SubmitDocument request.

AnalyzeDocument - annotated response (detect existing fields only)
<?xml version="1.0" ?>
<AnalyzeDocumentRs 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. -->

    <!-- The fields already in the PDF. -->
    <ExistingFormFieldCounts>
      <SignatureFieldsCount>1</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>18</TextFieldsCount>
      <CheckboxesCount>9</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </ExistingFormFieldCounts>

    <!-- All the fields, existing and new. The same as above in this mode. -->
    <TotalFormFieldCounts>
      <SignatureFieldsCount>1</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>18</TextFieldsCount>
      <CheckboxesCount>9</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </TotalFormFieldCounts>

    <!-- Ready to copy into a SubmitDocument request. Set the RefID first. -->
    <Form>
      <RefID/>
      <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
      <MimeType>application/pdf</MimeType>

      <FormStructure>
        <Section name="Section1">
          <FormField name="form1[0].#subform[0].S2C_Unit[0]">
            <Value>Off</Value>
            <Required>false</Required>
          </FormField>
          <!-- ... one FormField for each field ... -->
        </Section>
      </FormStructure>

      <!-- Assigned to MemberInfoNumber 1. Re-assign to your signers in SubmitDocument. -->
      <SignatureLine>
        <MemberInfoNumber>1</MemberInfoNumber>
        <SignField>Signature_1767890238267</SignField>
        <Covers section="Section1" editInDocument="false"/>
      </SignatureLine>

      <Length>YOUR_LENGTH</Length>
      <Data>BASE64_PDF</Data>
    </Form>

  </Data>

</AnalyzeDocumentRs>

Discover new fields only

With DiscoverNewFields true and KeepExistingFields false, the response lists the discovered fields in NewFormFieldCounts, along with a Form that you can copy into a SubmitDocument request. The Data element holds the PDF with the new fields added.

AnalyzeDocument - annotated response (discover new fields only)
<AnalyzeDocumentRs xmlns="urn:com:signix:schema:sdddc-1-1">

  <Status>
    <StatusCode>0</StatusCode>
    <StatusDesc>success</StatusDesc>
  </Status>

  <Data>

    <!-- The fields SIGNiX discovered. -->
    <NewFormFieldCounts>
      <SignatureFieldsCount>2</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>20</TextFieldsCount>
      <CheckboxesCount>30</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </NewFormFieldCounts>

    <!-- All the fields. The same as above in this mode. -->
    <TotalFormFieldCounts>
      <SignatureFieldsCount>2</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>20</TextFieldsCount>
      <CheckboxesCount>30</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </TotalFormFieldCounts>

    <Form>
      <RefID/>
      <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
      <MimeType>application/pdf</MimeType>

      <FormStructure>
        <Section name="Section1">
          <FormField name="Checkbox_2_4168807354">
            <Value>Off</Value>
            <Required>false</Required>
          </FormField>
          <!-- ... one FormField for each discovered field ... -->
        </Section>
      </FormStructure>

      <!-- All assigned to MemberInfoNumber 1. Re-assign to your signers in SubmitDocument. -->
      <SignatureLine>
        <MemberInfoNumber>1</MemberInfoNumber>
        <SignField>Signature_3_3991701660</SignField>
        <Covers section="Section1" editInDocument="false"/>
      </SignatureLine>
      <SignatureLine>
        <MemberInfoNumber>1</MemberInfoNumber>
        <SignField>Signature_3_9245742591</SignField>
      </SignatureLine>

      <Length>YOUR_LENGTH</Length>
      <Data>BASE64_PDF_WITH_NEW_FIELDS</Data>
    </Form>

  </Data>

</AnalyzeDocumentRs>

Detect existing and discover new fields

With both options true, the response includes ExistingFormFieldCounts, NewFormFieldCounts and TotalFormFieldCounts, and one Form for all the fields. The Data element holds the PDF with every field. The counts below are only an illustration.

AnalyzeDocument - annotated response (detect existing and discover new)
<AnalyzeDocumentRs xmlns="urn:com:signix:schema:sdddc-1-1">

  <Status>
    <StatusCode>0</StatusCode>
    <StatusDesc>success</StatusDesc>
  </Status>

  <Data>

    <!-- The fields already in the PDF. -->
    <ExistingFormFieldCounts>
      <SignatureFieldsCount>1</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>18</TextFieldsCount>
      <CheckboxesCount>9</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </ExistingFormFieldCounts>

    <!-- The fields SIGNiX discovered. -->
    <NewFormFieldCounts>
      <SignatureFieldsCount>1</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>2</TextFieldsCount>
      <CheckboxesCount>0</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </NewFormFieldCounts>

    <!-- Existing plus new. -->
    <TotalFormFieldCounts>
      <SignatureFieldsCount>2</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>20</TextFieldsCount>
      <CheckboxesCount>9</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </TotalFormFieldCounts>

    <Form> <!-- One Form for all the fields -->
      <RefID/>
      <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
      <MimeType>application/pdf</MimeType>
      <FormStructure>
        <!-- ... FormField elements for the existing and the new fields ... -->
      </FormStructure>
      <!-- ... SignatureLine and other field elements, assigned to MemberInfoNumber 1 ... -->
      <Length>YOUR_LENGTH</Length>
      <Data>BASE64_PDF_WITH_ALL_FIELDS</Data>
    </Form>

  </Data>

</AnalyzeDocumentRs>

Remove existing fields

With both options false, SIGNiX removes the existing form fields from the PDF and returns the untagged PDF as Base64 in the Form. The response has no field structure.

AnalyzeDocument - annotated response (remove existing fields)
<AnalyzeDocumentRs xmlns="urn:com:signix:schema:sdddc-1-1">

  <Status>
    <StatusCode>0</StatusCode>
    <StatusDesc>success</StatusDesc>
  </Status>

  <Data>

    <!-- All counts are zero because no fields remain in the PDF. -->
    <TotalFormFieldCounts>
      <SignatureFieldsCount>0</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>0</TextFieldsCount>
      <CheckboxesCount>0</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </TotalFormFieldCounts>

    <Form>
      <RefID/>
      <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
      <MimeType>application/pdf</MimeType>
      <Length>YOUR_LENGTH</Length>
      <Data>BASE64_PDF_WITHOUT_FIELDS</Data> <!-- The PDF with its form fields removed -->
    </Form>

  </Data>

</AnalyzeDocumentRs>

No fields found

If the analysis finds no fields, the request still succeeds. Every count is zero and the Form carries the PDF unchanged.

AnalyzeDocument - annotated response (no fields found)
<AnalyzeDocumentRs xmlns="urn:com:signix:schema:sdddc-1-1">

  <Status>
    <StatusCode>0</StatusCode>
    <StatusDesc>success</StatusDesc>
  </Status>

  <Data>

    <ExistingFormFieldCounts>
      <SignatureFieldsCount>0</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>0</TextFieldsCount>
      <CheckboxesCount>0</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </ExistingFormFieldCounts>

    <TotalFormFieldCounts>
      <SignatureFieldsCount>0</SignatureFieldsCount>
      <InitialFieldsCount>0</InitialFieldsCount>
      <DateFieldsCount>0</DateFieldsCount>
      <PrintedNameFieldsCount>0</PrintedNameFieldsCount>
      <ReasonFieldsCount>0</ReasonFieldsCount>
      <NotarySealsCount>0</NotarySealsCount>
      <TextFieldsCount>0</TextFieldsCount>
      <CheckboxesCount>0</CheckboxesCount>
      <RadioGroupsCount>0</RadioGroupsCount>
      <RadioButtonsCount>0</RadioButtonsCount>
    </TotalFormFieldCounts>

    <Form>
      <RefID/>
      <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
      <MimeType>application/pdf</MimeType>
      <Length>YOUR_LENGTH</Length>
      <Data>BASE64_PDF</Data>
    </Form>

  </Data>

</AnalyzeDocumentRs>

AnalyzeDocument - Error codes

If the request cannot be processed, the response has a non-zero StatusCode, a StatusDesc giving the reason, and no Data element. Check StatusCode before reading anything else. Examples of the errors you may see follow. See Status Codes on the main API page for the full list.

A request to discover new fields fails if your account has not been configured for form field detection. Contact SIGNiX to have it set up.

AnalyzeDocument - example error responses
<!-- Each Status element below is from a separate response. -->

<!-- The detection endpoint is unavailable. -->
<Status>
  <StatusCode>101</StatusCode>
  <StatusDesc>Detection endpoint is unavailable at this time.</StatusDesc>
</Status>

<!-- An option is not a valid boolean. -->
<Status>
  <StatusCode>104</StatusCode>
  <StatusDesc>Invalid value in parameter 'KeepExistingFields' (BooleanOption 'null' Not a valid boolean option.)</StatusDesc>
</Status>

<!-- The Base64 data could not be decoded. -->
<Status>
  <StatusCode>104</StatusCode>
  <StatusDesc>Form #1: Error decoding data: java.lang.RuntimeException: Fatal decoding error: iaik.utils.Base64Exception: Invalid length.</StatusDesc>
</Status>

<!-- An element has an invalid value, such as an empty numeric option. -->
<Status>
  <StatusCode>101</StatusCode>
  <StatusDesc>cvc-datatype-valid.1.2.1: '' is not a valid value for 'integer'.</StatusDesc>
</Status>