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

api.prontoforms.com/api/[version]/data/dispatch.xml
api.prontoforms.com/api/[version]/data/dispatch.json 

Method

POST

Request Parameters

None. 

 

Request Body

The dispatch request body must contain the following aspects:

formId
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
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.

dispatchToDraft
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. 
data
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.
answer
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.  

 

Samples

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.

XML

<dispatch>
 <formId>140001</formId>
 <userId>160002</userId>
 <data>
    <answer label="firstName">John</answer>
    <answer label="lastName">Smith</answer>
<answer label="colors">grey</answer>
<answer label="colors">blue</answer>
 </data>
</dispatch>

 JSON

{
"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

XML

<dispatchResult>
<dataId>123</dataId>
<referenceNumber>20110902-123</referenceNumber>
</dispatchResult>

JSON

{
"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/data/dispatch.xml
curl -v -k -u user:password -X POST --upload-file FILENAME.json https://api.prontoforms.com/api/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
Code
Description
 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 ]

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

Comments