Dispatch a Form with the API


Before You Begin

Before attempting to dispatch a form, please ensure that the pre-requisite configurations are in place by reviewing the dispatching documentation.


Dispatch a Data Record to a User

This method sends a dispatch message to the ProntoForms server, which in turn will dispatch that record to the ProntoUser. 

Note that the response message to a successful dispatch will include the unique ID of the created record.  If your business process requires that a dispatched record may need to be subsequently "undispatched" (deleted from the recipient's device), your API application should store this ID for use in the data record deletion API call.

Read more about data formats and supported question and data types for dispatching.

It is also possible to dispatch a data record to a User Alias, or using Form Tags.

URL Structure




Request Parameters



Request Body

The dispatch request body must contain the following aspects:

Indicates the ID of the ProntoForm which is used to render the form for the user.  Please note that this is the top-level form ID, and does not refer to the form iteration ID.  

userId or username or userAlias
One of these values must be provided to indicate the user who will receive the dispatch.
For assistance in locating these values, refer to How to find the Form ID, Username and User ID in the Portal


The following dispatch message parameters are optional.  Dispatching records that do not contain any question data is supported.

If the form you are working with is in a draft state and you want to dispatch using the draft (for development purposes), then set this value to true.  The default is false.  If this property is set to false, the active version of the form is used for the dispatch. 

The data section is used to pre-fill the questions of the form with answers for the dispatch. All answer data must be contained within the data section of the dispatch message.

Use 1 or more "answer" properties in your dispatch message to pre-fill questions in the dispatched form.  Please keep in mind the guidelines for Data Formats and Supported Question and Data Types for Dispatching.


Note: When using the API to dispatch data to a question that has been configured to "collect additional answers," the additional answers will NOT  be automatically populated in the form.  If it is essential that these values are pushed, it is up to the dispatcher to include the data in the dispatch.  



Two sample dispatch messages are provided below, one in XML and one in JSON format.  The XML version illustrates a dispatch sent to an active form, with the dispatch recipient specified via the ProntoUser user ID.  The questions labelled as "firstName" and "lastName in the form definition are given preset values.  The question labelled as "colors" is assigned 2 preset values of "grey" and "blue".  The JSON sample performs the same dispatch but assigns it through ProntoUser username rather than the user ID, and sends it to the draft version of the form rather than the active version.


    <answer label="firstName">John</answer>
    <answer label="lastName">Smith</answer>
<answer label="colors">grey</answer>
<answer label="colors">blue</answer>


"formId": "140001",
"dispatchToDraft": "true",
"username": "bjohnston",
"data": [
"label": "firstName",
"answer": "John"
"label": "lastName",
"answer": "Smith"
"label": "colors",
"answer": "grey"
"label": "colors",
"answer": "blue"

[ top ]


Response Body Samples




"dataId": "123",
"referenceNumber": "20110902-123"

 NOTE:  When using JSON, the raw number and boolean data types are accepted where applicable. Formatting all values as strings is also supported.

[ top ]


Sample cURL Commands

curl -v -k -u user:password -X POST --upload-file FILENAME.xml https://api.prontoforms.com/api/1.1/data/dispatch.xml
curl -v -k -u user:password -X POST --upload-file FILENAME.json https://api.prontoforms.com/api/1.1/data/dispatch.json

Important Note: Replace user with your API Key ID and password with your API Key secret.  Also, replace FILENAME with the name of your actual file which should be formatted as per the XML or JSON request body samples above.

[ top ]


Error Codes

Error Code
Response Header
HTTP Response
 InvalidDataException 400  Data did not meet the requirements specified in the form.
 DataLabelNotInForm 400  One of the labels specified in the pre-set data list does not exist in the form.
 InvalidAnswerData 400  Data could not be formatted to the data type of the question referenced by the label.
 DispatchToUnauthorizedUser 416  You have attempted to dispatch to a user who does not have access to the form.
 DispatchToArchivedForm 416  You have attempted to dispatch to an archived form
 DispatchNotAllowed 416  This form is not configured to allow dispatch. You must choose a Form Initiation Method of 'Dispatch' or 'Both'.
 DispatchFormVersionNotFound 404  The form does not have a version in the specified state (Active or Draft).
 DispatchFormNotFound 404  A form with the specified identifier could not be found.
 DispatchUserNotFound 404  A user with the specified identifier could not be found

[ top ]


Dispatching Metadata using the API

Dispatchable Metadata Fields

Easily assign notes, priorities, due dates, and locations to dispatches, giving mobile users the tools they need to efficiently plan their work in the field. Your mobile users can get a higher-level look at their assigned jobs without needing to look at each individual form: they can sort based on the information right from the inbox.

It is possible to dispatch data into the following fields:

  • Notes: These can be a maximum of 840 characters. These might be things such as working hours, or cautions about the site.
  • Priority: This can be Low, Medium, or High. If you do not specify a priority, it will default to Normal or No Priority.
  • Due Date: This must be a valid date/time in ISO format (YYYY-MM-DD, e.g. 2017-03-23), and if you do not supply a timezone, it will default to the dispatcher's timezone.
  • Location: These must be latitude/longitude coordinates (e.g. 45.347484,-75.909761). You can use tools such as Geocodio (third party web-app) to convert addresses to coordinates.

[ top ]


How to dispatch into Metadata Fields

This section focuses upon dispatching into metadata fields instead of dispatching internal form data. For more information on dispatching a form, please read our documentation: Dispatching a Form. The metadata field is optional, and all fields within are also optional.

Below is a sample of how to dispatch metadata fields into a form using the API.

JSON Sample:

 "formId": "141",
 "username": "devuser1",
 "data": [
   { "label": "Part Number", "answer": "237-1575-ND"  }
 "metadata": {
 	"notes": "Repair the transformer between the warehouses.",
 	"dueDate": "2017-12-22T17:00:00Z",
 	"priority": "High",
 	"coordinates": "45.3475631,-75.9097503"

XML Sample

    <answer label="Part Number">237-1575-ND</answer>
    <notes>Repair the transformer between the warehouses.</notes>

[ top ]


Dispatching into Additional Comments

Additional comments are a feature available on options-based questions and questions configured to use Exceptions. For more information on additional comments, read: Additional Comments on Questions.

How to dispatch into Additional Comments

The request to dispatch into additional comments adds the commentAnswer field in JSON:

   "formId": "14148001",
   "username": "john_smith",
   "data": [
"label": "question1",
"commentAnswer": "here are my comments",
"answer": "blah"

And in XML, it is via adding the "Comment" type:

<answer label="question1">blah</answer>
<answer label="question1" type="Comment">here are my comments</answer>

[ top ]

Was this article helpful?
3 out of 3 found this helpful
Have more questions? Submit a request