- Before you Begin
- Dispatch a Data Record to a User
Before attempting to dispatch a form, please ensure that the pre-requisite configurations are in place by reviewing the dispatching documentation.
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.
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
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.
NOTE: When using JSON, the raw number and boolean data types are accepted where applicable. Formatting all values as strings is also supported.
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.
|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|