App-to-App Callbacks



App-to-app callbacks enable the ProntoForms app to return focus and data to the app that initiated an interaction, as long as it supports the x-callback-url protocol. This article will discuss the parameters, error codes, and best practices for using the x-callback-url protocol with ProntoForms.

More general information on inter-app communication is available in our Inter-App Communication and Inter-App Dispatch articles. 

[ top ]


URL Scheme

Please refer to the URL Scheme section in the App-to-App Communications article. 

[ top ]


X-Callback Parameters

ProntoForms uses the x-callback-url specification to control what happens after actions are triggered within the Inter-App Call URL. As follows: 


Action Parameter Description Type Expected Values
 x-cancel This is the URL that is opened when the requested action is cancelled, e.g. tapping the Back button on Android, thereby discarding the form that was opened via interapp call. string user-defined

If the action in the target method is intended to return a result to the source app, the x-callback parameter should be included and provide a URL to open to return to the source app. On completion of the action, the target app will open this URL. If x-success is not provided, it is assumed that the user will stay in the target app on successful completion of the action.

Additional parameters that may be appended to the URL for the open action: clientDataRecordID if the form was saved as a draft, and serverDataRecordID if the form was completed and sent.

Adding the x-success parameter into your ProntoForms URL action tells ProntoForms to perform the next action upon the success of the first one. That is, once the first action is completed, the next one will be run. Since this depends upon the success of the first action, remember that your second action will never be run if the first one fails. This is why testing and re-testing each part of your URL actions is important. Your second action could be typed up perfectly, but if the first one has a slight error that causes it to fail, the second will never get a chance.

 string user-defined

When used in conjunction with the action parameter, this URL will be opened if the action generates an error and cannot be completed successfully.

string user-defined


[ top ]



Error Codes and Messages

ProntoForms has a number of defined error codes. As follows: 

PFErrorCodeListNotFound / 2001
if the request is
Error message: Form list not found.

if the request is
Error message: Inbox not found.

if the request is
Error message: Sent list not found.


PFErrorCodeItemNotFound / 1010
if the request is
A form with the requested ID does not exist. FormID = 15872001

if the request is
prontoforms://x-callback-url/open? formIterationID=15872001
A form with the requested iteration ID does not exist. FormIterationID = 15872001

A form with the requested name does not exist. FormName = Inspection

if the request is
A Data Record with the requested ID does not exist. DataRecordID = 15872001

if the request is
A Data Record with the requested local data record ID does not exist. ClientDataRecordID = 15872001

if the request is
Error message: A list that is named “inboxList“ does not exist.


More will be added in future.

[ top ]


Best Practices


If you are concerned about security, it is best to use the following format for your inter-app callbacks:


Ensure all Outcomes have Parameters

If you have a success, add a /success/<parameters> into the URL to show the outcome of your inter-app call. This should be done for all the action parameters.

[ top ]


Diagrams and Examples






[ top ]

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