Skip to main content

Search

Table of Contents


Articles in this section

API form field data

Avatar
Tim Schiller
  • Updated

Form data

When fetching a specific Form entry you will see the Form data split into 2 properties:

data: A serialized object of form field key\value pairs. The keys are all strings, but they represent an integer field ID. When updating or creating a form entry, this is the format the body of the API call must be in to submit the data.

For example,

{
    "2303": "https://test.thoughtfarmer.com",
    "2304": "test@thoughtfarmer.com",
}

 

fieldValues: This is an expanded array of objects that give more information about the fields associated with the form data. The rows property is a nested list of fieldValues used for each row in a Table type field.

For example,

[
    {
        "fieldId": 2303,
        "fieldLabel": "",
        "value": "https://test.thoughtfarmer.com",
        "fieldType": "url",
        "rows": null
      },
      {
        "fieldId": 2304,
        "fieldLabel": "Email",
        "value": "test@thoughtfarmer.com",
        "fieldType": "email",
        "rows": null
      }
]

 

More details about logic and sections for the various field IDs come from the schema for a form using the API call GET /formsapi/public/form/{formId}. For details about working with the form schema please see the page Working with a form's schema.

File field types

All files associated with a form entry must be pre-uploaded via the API call /formsapi/public/files/{scratchPadId}. The scratchPadId is a new GUID that is generated for this specific form entry. It must be unique (don't reuse IDs). Use this same GUID to pre-upload all files. Use this same GUID as the scratchPadId parameter in the final call along with the form data via POST /formsapi/public/formentry (for new entries), or PUT  /formsapi/public/formentry/{formEntryId} (for existing entries), then the files will be permanently associated with the form entry.

The pre-upload response will give you all of the information needed to properly populate the form data serialized string. For all fields of type File or Image simply use the fileId as the value when submitting the form data.

Example pre-upload response:

{
    "fileId": 14,
    "parentId": 0,
    "createdByUserId": 1,
    "fileName": "image.png",
    "subType": 2,
    "urlToken": "dddbbb6a-9d8b-4e6b-a835-0641483d7a2b",
    "url": "/formsapi/image/dddbbb6a-9d8b-4e6b-a835-0641483d7a2b/0x0/false/image.png",
    "thumbnailUrl": "/formsapi/image/dddbbb6a-9d8b-4e6b-a835-0641483d7a2b/252x0/false/image.png",
    "downloadUrl": "/formsapi/file/dddbbb6a-9d8b-4e6b-a835-0641483d7a2b/image.png"
}

You can use the upload response data to add files and images to the form.

Example of a File or Image form field:

{"123": 14 }

As part of rich text content you can use the fileId and url attributes to construct an img tag.

Example RTE image:

<img alt="image.png" 
     class="type-uploadimage" data-photoid="14" 
     src="/formsapi/image/dddbbb6a-9d8b-4e6b-a835-0641483d7a2b/0x0/false/image.png" />

Dropdown, radio button and check box fields

The available options come from the form schema. Check the options property. Each option will have a value property that can be used to submit data to a form.

Example options property on a field:

"options": [
            {
              "optionId": 342,
              "sortOrder": 0,
              "value": "1597254385352",
              "label": [
                {
                  "key": "en",
                  "value": "Choice 1"
                }
              ],
              "logicAction": 3,
              "logicTargetId": 11,
              "isDeleted": false
            },
            {
              "optionId": 343,
              "sortOrder": 1,
              "value": "1597254497857",
              "label": [
                {
                  "key": "en",
                  "value": "Choice 2"
                }
              ],
              "logicAction": 0,
              "logicTargetId": 0,
              "isDeleted": false
            },
            {
              "optionId": 344,
              "sortOrder": 2,
              "value": "1597254501238",
              "label": [
                {
                  "key": "en",
                  "value": "Choice 3"
                }
              ],
              "logicAction": 0,
              "logicTargetId": 0,
              "isDeleted": false
            }
          ]

 

Other optional text input
If the form field has the property hasOtherOption set to true, then users can enter a text value not included in the set options. Submitting data for this use case requires special consideration. For all types—select, dropdown, and radio—the field ID key must end with _other. Then instead of a valid option value ID, a text value can be used instead. 

UI type API fieldType Value format
Dropdown select { "1550": "1610650785556" }
Radio button radio { "1549": "1610650785556" }
Checkbox checkbox {  "1548": ["1610650743543", "1610650728305"] }
Other option select, radio, or checkbox { "1547_other": "User input for other option" }

 

All field types with examples

UI type Api fieldType Format Notes
Form heading formheading N/A Only used for display purposes in the form. This is not a valid field to send for update or create of a form entry. 
Instructions formcopy N/A Only used for display purposes in the form. This is not a valid field to send for update or create of a form entry. 
Text field textbox { "211": "Text area." } Value is a string. It will be sanitized and cannot contain any HTML.
Paragraph textarea { "211": "Text area\nContent here." } Value is a string. It will be sanitized and cannot contain any HTML but can contain new line characters.
Rich text richtext  { "233": "Rich text area<br />\n<br />\n<img alt=\"image.png\" class=\"type-uploadimage\" data-photoid=\"14\" id=\"image-1610644713530\" src=\"/formsapi/image/dddbbb6a-9d8b-4e6b-a835-0641483d7a2b/0x0/false/img.png\" />" }
   		 Value should be valid HTML. It will be sanitized. Embedded images must follow the method described in the File field types section. See the Example RTE image. 

 
Dropdown select { "1550": "1610650785556" } Valid values provided as part of the options parameter for this field from the form schema.
Radio button radio { "1549": "1610650785556" } Valid values provided as part of the options parameter for this field from the form schema.
Check box checkbox {  "1548": ["1610650743543", "1610650728305"] } Allows multiple selections, so is an array of options values. Valid values provided as part of the options parameter for this field from the form schema.
Other select, radio, or checkbox { "1547_other": "User input for other option" } If the form field has the property hasOtherOption set to true, then users can enter a text value not included in the set options. Key must end with _other to indicate this state.
Date date { "235": "2021-01-02T00:00:00.000Z" } Must be a valid date time format. Preferably ISO8601. 
Time time { "236": "05:00" } Must be a valid time format. 
Number number { "237": "12" }
OR
{ "237": "12.00" }
OR
{ "237": "12.123" }		 Must be a string as part of the JSON. However, it will be validated to ensure it can be parsed as a valid integer or float. 
Website url { "238": "https://www.thoughtfarmer.com/"; } Must be a valid URL. 
Email email { "239": "no-reply@thoughtfarmer.com" } Must be a valid email.
Table table { "249": [{
        "250": "Test",
        "251": "05:30",
        "252": [53],
        "rowId": 1610644669396
    }, {
        "250": "Test2",
        "251": "06:30",
        "252": [52],
        "rowId": 1610648271902
    }] }

An array of other fields that indicate the rows in the table. 

NOTE: rowId is optional. If updating an existing form entry it should be included to show which row was edited. This will make version differentials work in the application. If omitted the only affect is the inability to properly diff the versions. 

rowId should be any valid unique integer for this table.
File upload file  { "229": 12 } The value must be an integer (not a string). It must correspond to the fileId that is returned when pre-uploading the file via /formsapi/public/files/{scratchPadGuid}
Image upload image { "230": 14 } As above.
People lookup people { "240": [1] }
OR
{ "240": [1,12,17,34] }		 Array User IDs. These can be fetched from the regular site API (e.g. /api/users, or /api/currentuser). If the field property defaultValue here is {submitter} then it should use the userId from the object returned from /api/currentuser, or possibly using the ThoughtFarmer JavaScript API if developing a custom card using ctx.customPortlets.getUser().userId.
Telephone telephone {  "242": "123-456-7890" } Value must be a valid telephone number. 
Extension telephoneextension { "243": "123" }

Example with telephone:
{  "242": "123-456-7890", "243": "123" }

Always part of the schema as part of a telephone field. If enabled it will be a child field there in the schema. Use this to get the proper fieldId for the telephoneextension field.

The Extension field does not need to be nested in the data object for the form.
Page lookup pagelookup { "244": { "title": "Test Person", "url": "/content/136/test-person" } } Uses a custom type PageLookupData with required properties title and url.

 

Example complete data object

This example would be a complete create or update object used for an entire form entry. Values are based on the examples in the above table.

{
    "formId": 12,
    "scratchPadId": "291b81d5-0f19-4856-bf5b-455121158ce7",
    "startDate": "2021-01-02T14:12:23.123Z",
    "data": {
        "227": "Tim",
        "228": "10",
        "229": 12,
        "230": 13,
        "232": "Text area",
        "233": "Rich text area<br />\n<br />\n<img alt=\"image.png\" class=\"type-uploadimage\" data-photoid=\"14\" id=\"image-1610644713530\" src=\"/formsapi/image/dddbbb6a-9d8b-4e6b-a835-0641483d7a2b/0x0/false/image.png\" />",
        "234": "1597254385352",
        "235": "2021-01-02T00:00:00.000Z",
        "236": "05:00",
        "237": "12",
        "238": "https://www.thoughtfarmer.com";,
        "239": "tim@thoughtfarmer.com",
        "240": [1],
        "242": "123-456-7894",
        "244": {
            "title": "Test Person",
            "url": "/content/136/test-person"
        },
        "245": [1, 17],
        "248": ["1597254438829", "1597254453690"],
        "249": [{
            "250": "Test",
            "251": "05:30",
            "252": [53],
            "rowId": 1610644669396
        }, {
            "250": "Test2",
            "251": "06:30",
            "252": [52],
            "rowId": 1610648271902
        }]
    }
}

Related articles

Comments

0 comments

Please sign in to leave a comment.

Privacy Policy
ThoughtFarmer a product of ThoughtFarmer Inc. ©2024 All rights reserved.