How-To: Dispatch a form via the API using Postman

Available on the Advanced and Enterprise tiers:

• About
• Dispatch via the API

About

Dispatching via the API sends a dispatch message to the TrueContext server, which in turn will dispatch that record to the user.

To use this dispatching system, you will have to install an API add-on to your browser, such as Postman.

Dispatch via the API

1. Ensure the form you would like to dispatch to is enabled to receive dispatches. For more, see the How to: Set up a form for dispatching.
   
   

2. Launch the Postman Plugin, and choose to create a Request.

   

3. Name your request something like "Dispatch The term "dispatch" refers to the act of sending a form to a mobile user or customer. Typically, a dispatched form includes some information pre-filled to give the recipient context for the work to be done. Dispatch can be manual or automated (using a Dispatch Data Destination or the TrueContext REST API). to User". You'll be able to re-use this request later.

   

4. If you don't already have a collection (which is like a folder for different requests), create one. I've named ours "TrueContext Dispatch." Select the collection, then save the request.

   

5. Change the method to POST. This is the method supported for creating dispatches.

   

6. Insert the Request URL https://api.prontoforms.com/api/1.1/data/dispatch.xml

   

7. Go to the Authorization tab.

   

   Change the type to "Basic Auth".

   

   Use the API Key as the Username and the API Key An API Key is used to authenticate calls to the TrueContext REST API. An admin creates the API Key in the TrueContext Web Portal to generate the necessary credentials to connect to the API. Secret as the Password. If you do not have an API Key and Secret, read about Setting up an API Application on TrueContext.

   

8. Go to the Body tab and select the radiobutton for "raw."

   

   In the text area, identify:

   • the ID of the form to dispatch to: <formId>FORM ID</formId>

   • the ID of the user who will receive the form: <userId>USER ID</userId>

   • the Unique ID of the question being filled, and the data to dispatch to that field: <answer label="UNIQUE ID">ANSWER</answer>

Sample: 

<dispatch>
  <formId>141938312</formId>
  <userId>131662191</userId>
  <data>
  <answer label="E-mail">j.doe@email.com</answer>
  <answer label="Name">Jane Doe</answer>
  <answer label="Phone">9145551026</answer>
  </data>
</dispatch>

In Postman: 

Below is a sample of what the raw text will look like after form, user, question and response have been identified:

9.Tap Send.

Look at the Response area. If successful, a Dispatch Result will appear complete with a Data ID and Reference Number.

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