App‑to‑App Action Details

Most App‑to‑App actions have additional parameters that you use to define exactly what you want to happen on the ProntoForms app. This topic describes the additional parameter details for each App‑to‑App action.

Supported on all tiers:

Essentials
Advanced
Enterprise

Info:Different identifiers apply at different stages in a workflow. When you build an App‑to‑App request, you must use valid combinations of identifier and location (Forms, Inbox, Drafts, or Search). The topic How to Use Form Identifiers in an App‑to‑App Call describes these combinations in more detail.

Note:Parameter names are case-sensitive.

launch parameters

The launch action has no additional parameters.

list parameters

type

Description

Displays a specific area of the ProntoForms app (Forms, Drafts, Inbox, or Sent).

Required

No

Default value

forms

Expected values

forms

drafts

inbox

sent

Example

Display the Inbox view of the ProntoForms app and trigger a reconcile.

prontoforms://x-callback-url/list?reconcile=1&type=inbox
tag

Description

Display a list of forms based on one or more valid form tags.

Tip:Use the type parameter along with tag to specify the location of the forms within the app (Forms, Inbox, or Drafts). Without the type parameter, the results default to Forms.

Limitations

Android devices do not support the tag parameter used with the list action.

Examples

Display a list of forms that have the “install” tag.

prontoforms://x-callback-url/list?tag=install

Display a list of forms that have both the “install” tag and the “checklist” tag.

prontoforms://x-callback-url/list?tag=install&tag=checklist

Note:If there are no forms that have all specified tags, the app displays an empty list.

open parameters

Open a form or a list of forms that match the specified parameters.

Tip:You can use multiple parameters to improve the precision of the results. For example, use the name and type=inbox parameters to open a list of matching forms in the user’s Inbox.

name

Description

Open a form or list of forms based on the form name. This parameter matches partial strings.

Note:You must enter the form name using URL encoding.

Example

Open a list of forms that have the words “asset” and “list” in the name.

prontoforms://x-callback-url/open?name=asset%20list
type

Description

Use the type parameter to specify whether the form opens from the Forms, Inbox, or Drafts.

Default value

forms

Expected values

forms

inbox

drafts

Example

Open a form or a list of forms in the user’s Inbox that have the word “asset” in the name.

prontoforms://x-callback-url/open?name=asset&type=inbox
tag

Description

Open a form or a list of forms based on one or more valid form tags. If more than one form matches the tags, the ProntoForms app displays a list of matching forms in the user’s Forms list.

Tip:Use the type parameter along with tag to specify the location of the forms within the app (Forms, Inbox, or Drafts). Without the type parameter, the results default to Forms.

Examples

Open a form or list of forms that have the “install” tag.

prontoforms://x-callback-url/open?tag=install

Open a form or list of forms that have both the “install” tag and the “checklist” tag.

prontoforms://x-callback-url/open?tag=install&tag=checklist

For any device, open a matching form or list of forms in the Inbox.

prontoforms://x-callback-url/open?tag=install&tag=checklist&type=inbox
formID

Description

Open a form or list of forms based on the form ID. This is the unique identifier of an empty form.

Examples

Open a form with ID of “99999999”.

prontoforms://x-callback-url/open?formID=99999999

Open and prepopulate the form with the customer name and work order number. This is an example of a “dispatch” type request.

prontoforms://x-callback-url/open?formID=99999999&CustomerName=Best%20Pianos&WorkOrderID=1234

Note:ProntoForms ignores any question unique IDs that are not defined in the form.

formIterationID

Description

Open a form or list of forms based on the form iteration ID. This is the unique identifier of a specific version of a form.

Examples

Open an active form with the version (iteration) of “98765432”.

prontoforms://x-callback-url/open?formIterationID=98765432

Open and prepopulate the form with the customer name and work order number.

prontoforms://x-callback-url/open?formIterationID=formIterationID&CustomerName=Best%20Pianos&WorkOrderID=1234
dataRecordID

Description

Open a dispatched form based on its form submission ID (the “data record” ID assigned when the ProntoForms server sends a form or receives a submitted form). The form can only be in the Inbox. The form can be

  1. a dispatched form

  2. a completed form sent for editing, or

  3. a reassigned incomplete ProntoForms TeamworkClosed ProntoForms Teamwork is an Enterprise tier feature that enables mobile users to transfer icomplete forms for other users to complete as part of a multi-user workflow. This can be useful for jobs that require someone else's expertise or that span multiple shifts.-enabled form.

Example

Open a dispatched form with a form submission ID of “123456789”.

prontoforms://x-callback-url/open?dataRecordID=123456789
clientDataRecordID

Description

Open a form that’s in a user’s Drafts.

This parameter is usually used for a previously opened form that the user saved in Drafts. Any previous App‑to‑App requests that have the x-success parameter included return the clientDataRecordID when the user saves the form to Drafts.

Example

Open a saved form with a form clientDataRecordID of “A1A1A1A1-AAAA-1111-AAAAAA111111”.

prontoforms://x-callback-url/open?clientDataRecordID=A1A1A1A1-AAAA-1111-AAAAAA111111
Note:When you use the open action to prepopulate (dispatch) a form, make sure that the answers match the supported question and data types.

For example:

  • To prepopulate a question that has an “Integer” data type, you must send an integer in your URL.

  • To prepopulate a dropdown question, you must send an answer that’s defined as an option for that question.

send parameters

Note:The type and at least one form identifier are required for the send request.

name

Description

Send a form based on the form name. This parameter matches partial strings.

Note:You must enter the form name using URL encoding.

Example

Send a form from the Inbox that has the words “asset list” in the name.

prontoforms://x-callback-url/send?name=asset%20list&type=inbox

If more than one form matches the search string, the user selects the form to send from a list.

type

Description

Specify the location of the form to send from the ProntoForms app to the ProntoForms server.

Required? Yes
Default value

None (you must provide a value)

Note:An unspecified or invalid value triggers the x-error callback. If the x-error is triggered but isn’t included in the request, the end user receives an error message.

Expected values

forms

drafts

inbox

Example

Send a form that a user started and saved to Drafts in the ProntoForms app.

prontoforms://x-callback-url/send?type=drafts&clientDataRecordID=A1A1A1A1-AAAA-1111-AAAAAA111111
tag

Description

Send a form based on one or more valid form tags. If more than one form matches the tags, the ProntoForms app displays a list of matching forms.

Examples

Send a form from the Inbox that has the “install” tag.

prontoforms://x-callback-url/send?tag=install&type=inbox

Send a form from the Inbox that has both the “install” tag and the “checklist” tag.

prontoforms://x-callback-url/send?tag=install&tag=checklist&type=inbox
formID

Description

Open, populate, and send a form from the ProntoForms app to the ProntoForms server based on the form ID. This is the unique identifier of a form.

Example

Open a form, populate an answer that triggers conditional logic to populate other answers, and send a form. This process requires no user interaction.

prontoforms://x-callback-url/send?type=forms&formID=99999999&ServiceType=Warranty
formIterationID

Description

Open, populate, and send a form from the ProntoForms app to the ProntoForms server based on the form iteration ID. This is the unique identifier of a specific version of a form.

Example

Open, populate, and send a form with the version (iteration) of “98765432”.

Note:On an iOS device, the user might have to select OK to confirm and send the form. To avoid this, in the ProntoForms mobile app settings, switch the Confirm Send option off.

prontoforms://x-callback-url/send?type=forms&formIterationID=98765432&ServiceType=Warranty
dataRecordID

Description

Send a dispatched, transferred, or completed form based on its form submission ID (the “data record” ID assigned when the ProntoForms server receives the submitted form).

Note:The term transferred only applies to ProntoForms Teamwork-enabled forms.

Example

Open and send a form from the user’s Inbox with a dispatched form ID of “123456789”.

prontoforms://x-callback-url/send?type=inbox&dataRecordID=123456789
clientDataRecordID

Description

Send a form already opened by your source app and saved by the ProntoForms app user in their Drafts.

You can find the clientDataRecordID in any previous App‑to‑App requests that have the x-success parameter included. An x-success callback returns the clientDataRecordID when the user saves the form to Drafts.

Example

Open and send a saved form with a clientDataRecordID of “A1A1A1A1-AAAA-1111-AAAAAA111111”.

prontoforms://x-callback-url/send?type=drafts&clientDataRecordID=A1A1A1A1-AAAA-1111-AAAAAA111111

search parameters

Note:The search action works when the ProntoForms mobile app user is online, belongs to a ProntoForms team with Search enabled, and has access to Search-enabled forms.

Tip:For ProntoForms Teamwork-enabled forms (Enterprise tier only), use the search action when you want to display a list of incomplete forms that a user can claim.

searchText

Description

Open a list of forms based on the form submission name. This parameter matches part of the form name, so that the user can select from a list of matching forms.

Note:You must enter the form submission name using App‑to‑App URL Encoding.

Example

Open a list of forms that have the words “asset list” in the name.

prontoforms://x-callback-url/search?searchText=asset%20list
stateFilter

Description

Open a list of forms based on the form submission state.

Default value Any
Expected values

For all types of Mobile App forms:

Any

AllComplete

For ProntoForms Teamwork-enabled forms only:

AllIncomplete

IncompleteUnassigned

Example

Open a list of incomplete ProntoForms Teamwork-enabled forms that are available for a user to claim.

prontoforms://x-callback-url/search?stateFilter=IncompleteUnassigned
dateSearchType

Description

Open a list of forms based on the date the form was last submitted. You can choose to search on a date range or date period.

Default value

AnyDate

Returns a list of forms submitted within the last 365 days.

Expected values

AnyDate

DatePeriod

DateRange

Additional parameters
  • The DatePeriod defaults to 7 days. To change the default value, you must also specify the datePeriod:

    • Today

    • Yesterday

    • ThisWeek

    • ThisMonth

    • LastHour

    • TwentyFourHours

    • SevenDays

    • ThirtyDays

  • The DateRange has no default—you must specify the dateRangeStart and dateRangeEnd values in the following format:

    YYYY-MM-DDTHH:mm:ssZ, for example, 2021-06-16T04:00Z

Examples

Open a list of incomplete ProntoForms Teamwork-enabled forms that were submitted this week.

prontoforms://x-callback-url/search?stateFilter=AllIncomplete&dateSearchType=DatePeriod&datePeriod=ThisWeek

Open a list of forms that were submitted during a specific date range.

prontoforms://x-callback-url/search?dateSearchType=DateRange&dateRangeStart=2021-06-16T04:00Z&dateRangeEnd=2021-06-18T04:00Z