The fetch choice field will use an endpoint provided by the form owner to show a list of choices to the user while submitting a form. This helps you to handle your choices without having to add them to a normal choice field. This is especially handy when the number of your choices is too large, or it is too dynamic (e.g. generated based on some dynamic data in your own service).
In order to use this service, you should create a simple endpoint that returns a list of choices in proper format (which we will specify in this document), so users can choose them, and Formaloo can validate them.
Your endpoint should accept the GET method to serve the request over the Internet. Formaloo will not use any other method (such as POST) to get the data, and will not use any authentication header or VPN to connect to the endpoint. Please also consider that Formaloo will use the endpoint from both frontend and backend services for the performance and validity of the data. So if your CORS policy won’t accept the requests from any of the used client domains or back-end servers, the field will not work.
The response should be a list of objects, each containing a label (which will be shown to the user) and a value. If your response is not a list, or its items don’t contain the needed values, Formaloo will not accept it.
Example of an acceptable response
[ { "label": "Alpha", "value": "1", }, { "label": "Beta", "value": "2", }, { "label": "Charlie", "value": "3", } ]
Note: The value is not validated to be unique by Formaloo, but if you need to use the selected value in your own code (e.g. through our web
Examples of unacceptable responses
// Lack of the needed data (label and value) [ { "label": "Alpha" }, { "label": "Beta" }, { "label": "Charlie" } ] // Sending anything other than a list { "choices" :[ { "label": "Alpha", "value": "alhpa", }, { "label": "Beta", "value": "beta", }, { "label": "Charlie", "value": "charlie", } ] } // Sending a non-JSON response: "Alpha,Beta,Charlie"
Searchability
Formaloo will only accept a list of 10 items on each API call, and even if you return more, Formaloo will only process the first 10 items. So, if your API contains more choice items than that, it should be searchable using the ?q= query param. When users enter any value in your field (in order to search for a choice), we will try to validate it in the backend. For example, if users choose this item:
{ "label": "Charlie", "value": "3", }
We will send this request to your endpoint to fetch the available choices, and validate the user’s chosen value:
https://your-endpoint-address/?q=Charlie
If the selected pair of label and value is not present in your response, or your response contains more than 10 items, we will throw a validation error at the user.
Whether the search is case sensitive or not, is up to you and your use case.
Performance
Please consider that If your endpoint takes too long to respond, we will deem it failed, and users won’t be able to submit your form.
Validations
Upon creating or updating the choice fetch field, we will validate your endpoint to make sure it returns a proper response. If this validation fails, we will throw an error and won’t let you perform the operation.