Supported Question and Data Types for Dispatching

You can dispatch a partially prefilled form to provide your field users with context for the work they need to do. This topic describes the question and data types you can prefill when you dispatch forms. It also describes how to format dispatch API requests.

Available on all tiers, with more options on the Advanced and Enterprise tiers:

Contents

• Supported Question and Data Types for Dispatching
  • Data types supported for dispatch
  • Data type requirements
  • Question types supported for dispatch
  • Multiple answers
  • Data Formats
    • Date and Time Formats
    • Attachment Formats
    • Other Data Formats
  • Dispatch answers to repeatable sections

Data types supported for dispatch

You must ensure that all dispatched answers work with the target answers. This means that a dispatched answer must have the same data type as the target question. For example, you can’t dispatch Free Text data to a question with data type Phone Number. If there are problems with the dispatched data, the dispatch is rejected, and an error message is returned.

The supported data types depend on the dispatch method, as described in the following table.

Data type requirements

For the Audio, Document, File, Image, and Signature data types:

• For API/Bulk CSV dispatch, all dispatched files must be Base64 encoded.
• Ensure that the MIME/media type is correctly specified for the file format.

For the Audio data type, the media type must be:

• Android—audio/3gpp
• iOS—audio/mp4

For the Document data type, the media type must be:

• application/pdf

For the Image and Signature data types, the media type must be:

• image/jpg

• image/jpeg

• image/png

For the File data type, all media types are allowed.

Note:The URL data type does not support percent-encoding.

Question types supported for dispatch

The supported question types depend on the dispatch method, as described in the following table.

Multiple answers

With the REST API and Bulk Dispatch, you can send multiple answers to a single question. The question type and configuration—such as an Image question with more than one maximum attachment—must support multiple answers. The following data types are supported for questions that can accept multiple answers:

• Audio

• Currency Value

• Decimal

• Document

• Email

• File

• Image

• Integer

• Phone Number

• Text

• URL

To specify multiple answers through the API, define multiple answer nodes in JSON or XML. The following example specifies multiple answers for a question with the Unique ID A Unique ID refers to the specific identifier of a question, form page, form section, or Data Destination. Unique IDs are used as reference points when pulling data for conditional logic, Analytics projects, Data Destinations, and Documents. “email”:

<answer label="email">a@b.com</answer>
<answer label="email">b@c.com</answer>

To specify multiple answers in a Bulk CSV dispatch file, place each answer on a new line:

"Red
Blue
Green"

In Excel, you can enter a new line within a cell by pressing Alt+Enter.

"This is/
a two-line input in a CSV"

Data Formats

Date and Time Formats

The date and time formats used are based on ISO standards. Values must be specified in Coordinated Universal Time (UTC).

Time Stamp (Date + Time)

Format	yyyy-MM-ddTHH:mm:ssZ
Example	2022-01-31T23:59:59Z

Date only

Format	yyyy-MM-dd
Example	2022-01-31

Time only

Format	HH:mm:ss
Example	23:59:59

Duration

Format	HH:mm:ss or milliseconds
Example	1:30:15 or 5400000

Attachment Formats

• Images can be dispatched to Image, Sketch Pad, and Signature questions.

• Files can be dispatched to File Upload questions.

• Audio files (in .3gpp and .mp4 format for Android and iOS respectively) can be dispatched to Audio Recording questions.

• Documents (PDF files only) can be dispatched to Document Editor questions.

• Files are compressed or resized as necessary to match the quality settings on the mobile device and in the Form Builder.

• Files must be Base64 encoded. Base64 encoding is typically done programmatically but can also be done with an online tool.

• All files must be formatted in a similar way, specifying the media type and Base64-encoded file, separated by a pipe (|) character. For example, images must be formatted as:

  image/jpg|Base64 string

  or

  image/png|Base64 string

  and PDF files as

  application/pdf|Base64 string.

Dispatch destinations

For a Dispatch destination, the Automatically carry forward answers… option routes answers to matching questions in the target form. We recommend this option for attachments, because the Answers to Dispatch 4000-character limit doesn’t accommodate most Base64 strings.

Bulk Dispatch (CSV)

The following example shows how to dispatch a Base64-encoded JPEG image:

image/jpg|iVBORw0KGgoAAAANSUhEUgAAAAEAAAACCAYAAACZgbYnAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAAQSURBVBhXY/gPBEwMDAwMAB32A/9omztwAAAAAElFTkSuQmCC

REST API dispatch

XML examples

The following example shows how to dispatch a single image to another Image question:

<answer label="Image 1">
     <contentType>image/png</contentType>
     <bytes>iVBORw0KGgoAAAANSUhEUgAAAAEAAAACCAYAAACZgbYnAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAAQSURBVBhXY/gPBEwMDAwMAB32A/9omztwAAAAAElFTkSuQmCC</bytes>
     <filename>My_Image.png</filename>
</answer>

The next example shows how to dispatch multiple images to the same question:

<answer label="Image 1"> 
<contentType>image/png</contentType> 
<bytes>iVBORw0KGgoAAAANSUhEUgAAAAEAAAACCAYAAACZgbYnAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAAQSURBVBhXY/gPBEwMDAwMAB32A/9omztwAAAAAElFTkSuQmCC</bytes> 
<filename>My_Image1.png</filename> 
</answer>

<answer label="Image 1"> 
<contentType>image/png</contentType> 
<bytes>iVBORw0KGgoAAAANSUhEUgAAAAEAAAACCAYAAACZgbYnAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAAQSURBVBhXY/gPBEwMDAwMAB32A/9omztwAAAAAElFTkSuQmCC</bytes> 
<filename>My_Image2.png</filename> 
</answer>

JSON examples

The following example shows how to dispatch a single image to another Image question:

{
"data": [{
"label": "Image 1",
       "answer": {
            "contentType": "image/png",
            "bytes": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAACCAYAAACZgbYnAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAAQSURBVBhXY/gPBEwMDAwMAB32A/9omztwAAAAAElFTkSuQmCC",
            "filename": "My_Image.png"
       }
 }]
}

The next example shows how to dispatch multiple images to the same question:

"data": [{
      "label": "ImageLabel",
      "answer": {
             "contentType": "image/png",
             "bytes": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAACCAYAAACZgbYnAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAAQSURBVBhXY/gPBEwMDAwMAB32A/9omztwAAAAAElFTkSuQmCC",
             "filename": "My_Image.png"
      }
  }, {
      "label": "ImageLabel",
         "answer": {
              "contentType": "image/png",
              "bytes": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAACCAYAAACZgbYnAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAAQSURBVBhXY/gPBEwMDAwMAB32A/9omztwAAAAAElFTkSuQmCC",
              "filename": "My_Image2.png"
      }
  }]

Other Data Formats

Text

For question types that have specific format requirements— (Email, Phone Number, and URL—dispatched answer values must be properly formatted. Text questions have no formatting requirements.

Numbers

Number data type questions only accept valid numerical input. Integer data questions must not have decimal values.

Currency Value

Provide Currency Value data as a decimal with no currency symbol or currency type.

Yes/No

The yes/no answer can be set by using yes or no as the input string.

Barcode Scanner

Barcode data requires specific formatting, including both type and value.

We support the following barcode types:

• UpcA

• UpcE

• Ean8

• Ean13

• Code39

• Code128

• Itf

• QrCode

The following types of barcodes are supported but might be difficult to scan on older devices:

• DataMatrix

• Pdf417

REST API

This XML example shows how to dispatch a UPC E barcode value:

<answer label="barcode">
 <type>UpcE</type>
 <value>123456</value>
</answer>

This JSON example also shows how to dispatch a UPC E barcode value:

{
 "formId": "123456789",
 "dispatchToDraft": "false",
 "username": "TargetUsername",
 "data": [{
    "label": "barcode",
    "answer": {
      "type": "UpcE",
      "value": "123456"
    }
 }]
}

Dispatch Destination

To prefill Barcode Scanner questions, you can:

• Configure your destination to Automatically carry forward answers…. The dispatched form includes any Barcode Scanner answers from the submitted form if the question Unique IDs match.

• Specify the barcode type and value using the following DREL expression format:

  %a[UniqueID][barcodeType]|%a[UniqueID][barcodeValue]

  where [UniqueID] identifies the Barcode Scanner question and [barcodeType] and [barcodeValue] are additional properties.

Info:The topic Dispatch Data Destination describes how to configure Dispatch Destinations in more detail.

Bulk Dispatch

The following example shows how to dispatch Barcode Scanner data.

::type,UpcE
value,123456

Geolocation

Geolocation data requires specific formatting and uses latitude and longitude coordinates.

To dispatch geolocation data from the Web Portal, simply start typing the address. When you dispatch by means of the REST API, a Dispatch Destination, or Web Portal Bulk Dispatch, you can specify additional information.

REST API

This XML example shows how to dispatch geolocation coordinates:

<answer label="geo">
 <latitude>123.456</latitude>
 <longitude>987.654</longitude>
</answer>

This JSON example also shows how to dispatch geolocation coordinates:

{
 "formId": "123456789",
 "dispatchToDraft": "false",
 "username": "TargetUsername",
 "data": [{
    "label": "geo",
    "answer": {
      "latitude": "123.456",
      "longitude": "987.654"
    }
 }]
}

Dispatch Destination

To prefill Geo Location questions, you can:

• Configure your destination to Automatically carry forward answers…. The dispatched form includes any Geo Location answers from the submitted form if the question Unique IDs match.

• Specify the geolocation to dispatch using the following DREL expression format:

  %a[UniqueID][coordinates]

  where [UniqueID] identifies the Geo Location question and [coordinates] returns the latitude, longitude, and altitude of the geo location.

  The following example shows a Dispatch Destination configuration. The geolocation from the question “NewSite” prefills the question “SiteLocation” in the dispatched form.

  

Info:The topic Dispatch Data Destination describes how to configure Dispatch Destinations in more detail.

Bulk Dispatch

The following example shows how to dispatch geolocation data. The last three lines are optional:

::latitude,123
longitude,456
altitude,789
address,123 fake street
accuracy,100

Dispatch answers to repeatable sections

You can prefill questions in repeatable sections by means of the TrueContext REST API. Use the appropriate Data Formats for the questions that you want to prefill.

TrueContext supports nested repeatable sections up to two levels. To dispatch into a nested repeatable section A Repeatable Section is a subform that contains a set of related questions. The data captured is “repeating”, because the field user can complete the same subform more than once, which creates multiple entries., you can nest the request body as shown in the following example:

{"data": [{
    "type": "Repeat",
    "label": "Section1UniqueIdentifier",
    "rows": [{
        "data": [{
                "label": "Section1Question1",
                "answer": "Section1Answer1"
            },
            {
                "label": "Section1Question2",
                "answer": "Section1Answer2"
            },
            {
                "type": "Repeat",
                "label": "Section2UniqueIdentifier",
                "rows": [{
                    "data": [{
                            "label": "Section2Question1",
                            "answer": "Section2Answer1"
                        },
                        {
                            "label": "Section2Question2",
                            "answer": "Section2Answer2"
                        }
                    ]
                }]
            }
        ]
    }]
}]
}