This field read the list of its choices from a remote source (i.e. remote API endpoint) rather than reading it from our own database.
Imagine if a customer has a dynamic list of products in their own service, and wants to select them in a form. Instead of having to add their products into our database, they can simply add a fetch choice field that automatically connects to their API to retrieve the items.
The Endpoint
Read this document to know the specifications about the choice items endpoint.
Endpoint Specifications for Fetch Choice Field
Creating the fetch choice field
Endpoint:
/v3/fields/Method:
POSTRequired fields:
type,choices_source
In order to create the fetch choice field, you can send the standard field attributes, along with a required choices_sourcefield. The choices_source should be the address to a remote endpoint that meets the needed criteria. If the endpoint is invalid or doesn’t meet the criteria, the server will throw an HTTP 400 error.
Example
// Request https://formaloo_api_server/v1.0/fields/ (POST) { "title": "Select one of these remote choices!", "type": "choice_fetch", "choices_source": "https://SOME_REMOTE_ADDRESS/choices/" } **//Response** { "status": 201, "errors": { "general_errors": [], "form_errors": {} }, "data": { "field": { "slug": "Noc3n72F", "created_at": "2022-01-18T07:21:29.225484Z", "updated_at": "2022-01-18T07:21:29.225515Z", "type": "choice_fetch", "title": "Select one of these remote choices!", "alias": null, "description": null, "answer_description": null, "position": 0, "required": false, "unique": false, "admin_only": false, "json_key": null, "is_calculatable": false, "is_random_sortable": true, "choices_source": "https://SOME_REMOTE_ADDRESS/choices/" } } }Example (Bad endpoint)
// Request https://formaloo_api_server/v1.0/fields/ (POST) { "title": "Select one of these remote choices!", "type": "choice_fetch", "choices_source": "https://SOME_BAD_REMOTE_ADDRESS/choices/" } **//Response** { "status": 400, "errors": { "general_errors": [], "form_errors": { "choices_source": [ "The URL is either invalid, returns an improper response, or times out!" ] } }, "data": {} }Updating the fetch choice field
Endpoint:
/v3/fields/{field_slug}/Method:
PUT,PATCH
Like creating the field, the choices_source will be validated upon update as well, and if it fails, an HTTP 400 error will be thrown.
Reading a form with fetch choice field
Unlike the other choice fields, the fetch choice field will not contain any choice_items in its data. The client should use the provided endpoint (choices_source) to receive the list of choices on their side.
Example
{ "status": 200, "errors": { "general_errors": [], "form_errors": {} }, "data": { "form": { "fields": { "ZZT1h23S": { "slug": "ZZT1h23S", "created_at": "2022-01-18T07:28:01.536337Z", "updated_at": "2022-01-18T08:02:25.019133Z", "type": "choice_fetch", "title": "Select one of these remote choices!", "alias": null, "description": null, "position": 1, "required": false, "unique": false, "admin_only": false, "json_key": null, "is_calculatable": false, "is_random_sortable": true, "choices_source": "https://SOME_REMOTE_ADDRESS/choices/" } }, "fields_list": [ { "slug": "ZZT1h23S", "created_at": "2022-01-18T07:28:01.536337Z", "updated_at": "2022-01-18T08:02:25.019133Z", "type": "choice_fetch", "title": "Select one of these remote choices!", "alias": null, "description": null, "position": 1, "required": false, "unique": false, "admin_only": false, "json_key": null, "is_calculatable": false, "is_random_sortable": true, "choices_source": "https://SOME_REMOTE_ADDRESS/choices/" } ], ... } } }Submitting a form with fetch choice field
The submitted value for a fetch choice field should be an object containing the label and value items for the selected choice.
Example
// Request https://formaloo_api_server/v1.0/forms/form-displays/slug/{form_slug}/submit/ (POST) { "ZZT1h23S": { "label": "Alpha", "value": "alpha" } } **//Response** { "status": 201, "errors": { "general_errors": [], "form_errors": {} }, "data": { "row": { "id": 1216372, "data": { "ZZT1h23S": { "label": "Alpha", "value": "alpha" } }, "slug": "fvwHRP8bHNPHulUexPUj", "created_at": "2022-01-18T08:07:54.725364Z", "updated_at": "2022-01-18T08:07:54.773986Z", "user": null, "form": { ... }, "tracking_code": null, "submitter_referer_address": "127.0.0.1:8051", "redirection_url": null, "extra_response": {}, "deleted": null, "submit_code": "zpn83nggiczy56mrz3iz", "submitter_ip_address": "172.26.0.1", "sumbit_time": null, "phone_verification_state": "not_required", "email_verification_state": "not_required", "calculation_score": {}, "create_type": "api", "status": "submit" } } }Reading a row with fetch choice field
The row data will contain the label and value pair as the raw_value for the field, but will only return the label for its value:
{ "status": 200, "errors": { "general_errors": [], "form_errors": {} }, "data": { "row": { "id": 1216372, "user": null, "readable_data": { "Select one of these remote choices!": "Alpha" }, "rendered_data": [ { "slug": "ZZT1h23S", "type": "choice_fetch", "alias": null, "title": "Select one of these remote choices!", "value": "Alpha", "json_key": null, "position": 1, "raw_value": { "label": "Alpha", "value": "alpha" }, "admin_only": false, "json_value": null } ], "form": "ogHjEcIH", "row_tags": [], "slug": "fvwHRP8bHNPHulUexPUj", "submit_code": "zpn83nggiczy56mrz3iz", "tracking_code": null, "next_row": null, "previous_row": null, "deleted": null, "created_at": "2022-01-18T11:37:54.725364+03:30", "updated_at": "2022-01-18T11:37:54.856970+03:30", "sumbit_time": null, "submitter_referer_address": "127.0.0.1:8051", "phone_verification_state": "not_required", "email_verification_state": "not_required", "data": { "ZZT1h23S": { "label": "Alpha", "value": "alpha" } }, "calculation_score": {}, "create_type": "api", "status": "submit" } } }