Get Rows data in Webhook & API
A Row is a response item created on a form, either being submitted by a user through a form interface, imported by excel, or added by a script through the API.
Each row contains a different set of data, either entered by the user, calculated by the user entered data, or some metadata. Here is the list of all data inside a row:
Note The data sent to the webhooks does not contain all of these. We will explain it in the following topic.
form: Slug of the form to which the row belongs. You can use this slug to get the form’s full data.
slug: Row’s slug. It’s the main identifier for the row, that can be used to get, update, or delete a row (given one has sufficient access to its form).
submit_code: An identifier that can be used by anyone to read a row’s data. In order to use this, the form should have the proper settings (show_answers field on the form should be set to true)
tracking_code: Depending on the form settings, may contain a numerical tracking code that is given to the user and can be used to filter the rows.
data: The raw data user has submitted. In order to read this, you have to have the full data of the form’s fields and their choices, etc. (For example, it may contain a pair of {"field_slug": "choice_slug"} for a choice field). Since working with this data can be complex, we rendered them with all the needed data and serve it in the rendered_data field.
rendered_data: It basically rendered the raw data, along with some extra data (e.g. payment data for the forms with payment), with all the metadata needed to understand the row’s data without the need to have anything else (e.g. the fields’ data). We will expand this field in the following topic.
readable_data: As its simplest form, it’s a dictionary mapping each field’s title to its readable value. (For example, it may contain a pair of {"Field Title": "Choice Title"} for a choice field).
calculation_score: For the forms with calculation, it will contain the calculation results, for example, grade or currency. Will be explained more in the following topic.
create_type: Will show if the row was created normally (by API), or through excel import.
row_tags: This will contain a list of tags assigned to a row, by the admin.
phone_verification_state: If the form has a phone verification field, it will show whether this specific submission was verified or not. If the form does not have a phone verification field, it defaults to not_reuired.
`email_verification_state`If the form has an email verification field, it will show whether this specific submission was verified or not. If the form does not have an email verification field, it defaults to not_reuired.
sumbit_time: How much time did it take the user to submit the form. It’s optionally sent by the client and can be null for most of the forms.
status: Whether the row is still a draft or is submitted.
submitter_referer_address: The referrer address from which the form was submitted. (e.g. the web page in which the form was embedded).
created_at: Row’s creation time.
updated_at: When was the row last edited.
Of the fields mentioned above, the webhooks contain the following, along with some webhook-specific fields:
form
slug
submit_code
data
rendered_datatli
created_at
updated_at
The data field is a raw field that contains a lot of slugs and numbers, basically mapping the fiel_slug to the value entered for the field. For some cases (e.g. number fields, email fields, text fields, etc) the value is the same as we read it (e.g. 12, [[email protected]](/cdn-cgi/l/email-protection), some text, etc). But for some other fields (e.g. choice fields, matrix fields, etc), the value is either a slug, list, or object that is not human readable.
In order to understand the data, you will need to have all the fields and their data (e.g. choices) to be able to understand the data.
Generally, you don’t need to work with data, unless you know what you're doing. In most cases, you’re better off with the rendered_data field.
Example
The rendered data field takes the data field, analyses it based on the data in it and the form and fields’ data, adds the order data to it, and creates a more complex but sufficient data map.
The rendered_data contains the data in the order of the form’s fields. each item contains the corresponding field’s data, users entered value, the rendered value, etc.
Example
Here is a description of the data inside each item of rendered data:
type: The filed’s type. For example choice, number, rating, etc.
If the form has payment, there will be three items at the end of the list that contain no type.
title: Title of the field.
value: The rendered value. For example, a choice field will contain the selected choice`s title.
raw_value: The value from the data field, as it has been submitted. For example, a choice field will contain the selected choice’s slug.
The rest (slug, json_key, alias, choice_items, etc) are read directly from the related field.
Payment Items
If the form has payment, there will be three items at the end of the list, containing the payment info: Whether it was successful or not, user’s order code, and how much has been paid.
If the form has calculations, you can see the result of the calculations in the calculation_score field. It can contain one or both of these fields: grade and currency, based on your calculations settings.
Please note that the grade field is rounded up to a maximum of three decimal points, and the field's currency is rounded up to a maximum of two decimal points.
Example
The readable data is the simplest digested form of the submitted data. It is simply a map from each field’s title to the submitted value. You can use it to see and handle the submitted data without the need for any logic. For example, if you simply want to put the data into a spreadsheet using your webhooks. The data inside the readable data is derived from the rendered data, only much simpler for simpler uses.
Note: Since the data is sent inside a mapping, its ordering is not guaranteed. If the ordering of the fields is important to you, you should use the rendered_data instead.
Note: If your form has payment, the payment data (e.g. Order Code) will be included in the readable data.
Example
Each row contains a different set of data, either entered by the user, calculated by the user entered data, or some metadata. Here is the list of all data inside a row:
Note The data sent to the webhooks does not contain all of these. We will explain it in the following topic.
form: Slug of the form to which the row belongs. You can use this slug to get the form’s full data.
slug: Row’s slug. It’s the main identifier for the row, that can be used to get, update, or delete a row (given one has sufficient access to its form).
submit_code: An identifier that can be used by anyone to read a row’s data. In order to use this, the form should have the proper settings (show_answers field on the form should be set to true)
tracking_code: Depending on the form settings, may contain a numerical tracking code that is given to the user and can be used to filter the rows.
data: The raw data user has submitted. In order to read this, you have to have the full data of the form’s fields and their choices, etc. (For example, it may contain a pair of {"field_slug": "choice_slug"} for a choice field). Since working with this data can be complex, we rendered them with all the needed data and serve it in the rendered_data field.
rendered_data: It basically rendered the raw data, along with some extra data (e.g. payment data for the forms with payment), with all the metadata needed to understand the row’s data without the need to have anything else (e.g. the fields’ data). We will expand this field in the following topic.
readable_data: As its simplest form, it’s a dictionary mapping each field’s title to its readable value. (For example, it may contain a pair of {"Field Title": "Choice Title"} for a choice field).
calculation_score: For the forms with calculation, it will contain the calculation results, for example, grade or currency. Will be explained more in the following topic.
create_type: Will show if the row was created normally (by API), or through excel import.
row_tags: This will contain a list of tags assigned to a row, by the admin.
phone_verification_state: If the form has a phone verification field, it will show whether this specific submission was verified or not. If the form does not have a phone verification field, it defaults to not_reuired.
`email_verification_state`If the form has an email verification field, it will show whether this specific submission was verified or not. If the form does not have an email verification field, it defaults to not_reuired.
sumbit_time: How much time did it take the user to submit the form. It’s optionally sent by the client and can be null for most of the forms.
status: Whether the row is still a draft or is submitted.
submitter_referer_address: The referrer address from which the form was submitted. (e.g. the web page in which the form was embedded).
created_at: Row’s creation time.
updated_at: When was the row last edited.
Webhook Data
Of the fields mentioned above, the webhooks contain the following, along with some webhook-specific fields:
form
slug
submit_code
data
rendered_datatli
created_at
updated_at
Data
The data field is a raw field that contains a lot of slugs and numbers, basically mapping the fiel_slug to the value entered for the field. For some cases (e.g. number fields, email fields, text fields, etc) the value is the same as we read it (e.g. 12, [[email protected]](/cdn-cgi/l/email-protection), some text, etc). But for some other fields (e.g. choice fields, matrix fields, etc), the value is either a slug, list, or object that is not human readable.
In order to understand the data, you will need to have all the fields and their data (e.g. choices) to be able to understand the data.
Generally, you don’t need to work with data, unless you know what you're doing. In most cases, you’re better off with the rendered_data field.
Example
{ "data": { "YNHFIUaR": "R26dAkQn", "i1RsdMgp": 4, "sXWAiN0W": "2VKHBcCc", "uyJ8LKIL": "gl9VQ8sN", "v4MGG6JA": "OixeSMRI" } }Rendered Data
The rendered data field takes the data field, analyses it based on the data in it and the form and fields’ data, adds the order data to it, and creates a more complex but sufficient data map.
The rendered_data contains the data in the order of the form’s fields. each item contains the corresponding field’s data, users entered value, the rendered value, etc.
Example
{ "rendered_data": [ { "slug": "sXWAiN0W", "type": "choice", "title": "Did you sleep well last night?", "value": "Yes", "json_key": null, "position": 1, "raw_value": "2VKHBcCc", "admin_only": false, "json_value": null, "choice_items": [ { "slug": "2VKHBcCc", "image": null, "title": "Yes", "deleted": null, "json_key": null, "position": 1, "created_at": "2021-11-20T09:07:09.710010+03:30", "updated_at": "2021-11-20T09:07:09.710025+03:30", "is_other_choice": false, "is_random_sortable": true }, { "slug": "c8V0LWoI", "image": null, "title": "No", "deleted": null, "json_key": null, "position": 2, "created_at": "2021-11-20T09:07:09.714140+03:30", "updated_at": "2021-11-20T09:07:09.714153+03:30", "is_other_choice": false, "is_random_sortable": true } ] }, { "slug": "uyJ8LKIL", "type": "choice", "title": "But...", "value": "I'm bored", "json_key": null, "position": 2, "raw_value": "gl9VQ8sN", "admin_only": false, "json_value": null, "choice_items": [ { "slug": "5XBeFbVo", "image": null, "title": "The kids are asleep", "deleted": null, "json_key": null, "position": 1, "created_at": "2021-11-20T09:07:09.726127+03:30", "updated_at": "2021-11-20T09:07:09.726139+03:30", "is_other_choice": false, "is_random_sortable": true }, { "slug": "wLbhhoFs", "image": null, "title": "I don't feel well", "deleted": null, "json_key": null, "position": 2, "created_at": "2021-11-20T09:07:09.729057+03:30", "updated_at": "2021-11-20T09:07:09.729068+03:30", "is_other_choice": false, "is_random_sortable": true }, { "slug": "gl9VQ8sN", "image": null, "title": "I'm bored", "deleted": null, "json_key": null, "position": 3, "created_at": "2021-11-20T09:07:09.732773+03:30", "updated_at": "2021-11-20T09:07:09.732784+03:30", "is_other_choice": false, "is_random_sortable": true }, { "slug": "EYKVAT4W", "image": null, "title": "I'm still tired", "deleted": null, "json_key": null, "position": 4, "created_at": "2021-11-20T09:07:09.735940+03:30", "updated_at": "2021-11-20T09:07:09.735952+03:30", "is_other_choice": false, "is_random_sortable": true } ] }, { "slug": "i1RsdMgp", "type": "rating", "title": "How do you rate me?", "value": 4, "json_key": null, "position": 19, "sub_type": "star", "raw_value": 4, "admin_only": false, "json_value": null, "max_message": "", "min_message": "", "thumbnail_type": null }, { "title": "Order Status", "slug": "order_status", "json_key": null, "alias": null, "value": "completed", "position": -1 }, { "title": "Order Code", "slug": "order_code", "json_key": null, "alias": null, "value": "87346289347", "position": 1000 }, { "title": "payment amount", "slug": "payment_amount", "json_key": null, "alias": null, "value": 10.00, "position": 999 } ] }Here is a description of the data inside each item of rendered data:
type: The filed’s type. For example choice, number, rating, etc.
If the form has payment, there will be three items at the end of the list that contain no type.
title: Title of the field.
value: The rendered value. For example, a choice field will contain the selected choice`s title.
raw_value: The value from the data field, as it has been submitted. For example, a choice field will contain the selected choice’s slug.
The rest (slug, json_key, alias, choice_items, etc) are read directly from the related field.
Payment Items
If the form has payment, there will be three items at the end of the list, containing the payment info: Whether it was successful or not, user’s order code, and how much has been paid.
**Calculation Score**
If the form has calculations, you can see the result of the calculations in the calculation_score field. It can contain one or both of these fields: grade and currency, based on your calculations settings.
Please note that the grade field is rounded up to a maximum of three decimal points, and the field's currency is rounded up to a maximum of two decimal points.
Example
{ "calculation_score": { "grade": 123.333, "currencuy": 10.55 } }Readable Data
The readable data is the simplest digested form of the submitted data. It is simply a map from each field’s title to the submitted value. You can use it to see and handle the submitted data without the need for any logic. For example, if you simply want to put the data into a spreadsheet using your webhooks. The data inside the readable data is derived from the rendered data, only much simpler for simpler uses.
Note: Since the data is sent inside a mapping, its ordering is not guaranteed. If the ordering of the fields is important to you, you should use the rendered_data instead.
Note: If your form has payment, the payment data (e.g. Order Code) will be included in the readable data.
Example
{ "readable_data": { "Order Code": "87346289347", "How do you rate me?": 4, "But...": "I'm bored", "Order Status": "completed", "Did you sleep well last night?": "Yes", "payment amount": 10.0 } }Updated on: 22/01/2023
Thank you!