Forms API

The Forms API gives you access to your form fields, or app schema.

Properties

PropertyTypeRequiredReadonlyDescription
namestringyesnoThe name you've given this form.
elementsarrayyesnoCustom form elements (see form elements table below).
idstringnoyesThe unique ID of the form.
descriptionstringnonoThe description you've given this form.
bounding_boxarraynoyesBounding box containing all the form's records. Format is [min_lat, min_long, max_lat, max_long]
title_field_keysarraynonoArray of strings, where the strings are keys for fields in the elements attribute.
status_fieldobjectnonoStatus field object (see status field table below).
form_links (beta)objectnoyesUsed in conjuncture with a record link field, this object stores form_id’s to or from which the app is linked.
auto_assignbooleannonoAssigns records to the user who creates them.
hidden_on_dashboardbooleannonoIs the form visible in the mobile dashboard?
geometry_requiredbooleannonoRequiring the location will force a location to be saved with each record.
projects_enabledbooleannonoAre projects enabled for this form?
assignment_enabledbooleannonoIs record assignment enabled for this form?
attachment_idsarraynonoList of Reference Files that are attached to the form
geometry_typesarraynonoEnables/disables record location. ['Point'] or []
scriptstringnonoCustom Data Events script.
record_countnumbernoyesThe number of records in this form.
created_atstringnoyesTimestamp when the form was created.
updated_atstringnoyesTimestamp when the form was last updated.
imagestringnoyesThe URL to the original image which was uploaded as this app's icon.
image_thumbnailstringnoyesThe URL to the thumbnail-sized image which was uploaded as this app's icon. 160x160 px
image_smallstringnoyesThe URL to the small-sized image which was uploaded as this app's icon. 320x320 px
image_largestringnoyesThe URL to the large-sized image which was uploaded as this app's icon. 640x640 px

Status Field Properties

PropertyTypeDefaultDescription
typestring"StatusField"The type of field.
labelstring"Status"The label for this field.
keystring"@status"The key for this field.
data_namestring"status"The data name for this field.
default_valuestring""The default value for this field.
enabledbooleanfalseWhether this form has the status field enabled.
read_onlybooleanfalseWhether status can be modified by user.
hiddenbooleanfalseWhether status is visible on mobile.
descriptionstring""The description for this field.
choicesarray[]See status field choices below.
requiredbooleanfalseWhether status value is required.
default_previous_valuebooleanfalseWhether to automatically set the previously used value.

Status Field Choice Properties

PropertyTypeDefaultDescription
labelstring""What's shown to the user in the web and mobile apps when they select a status for records in this app.
valuestring""What's stored in the record.
colorstring"#CB0D0C"The hexadecimal value for the color used for the status and the marker color on the map.

Form Element Properties (all field types)

PropertyTypeRequiredDescription
typestringyesMust be one of the valid element types: "TextField", "YesNoField", "Label", "Section", "ChoiceField", "ClassificationField", "PhotoField", "VideoField", "AudioField", "BarcodeField", "DateTimeField", "TimeField", "Section", "Repeatable", "AddressField", "SignatureField", "HyperlinkField", "CalculatedField", "RecordLinkField".
keystringyesThe id for the field. Must be unique to the form and lowercase. The Fulcrum app builder uses system generated 4 character codes.
labelstringyesThe field label, visible to mobile and web users.
data_namestringyesCan be set manually or auto generated using the label of the element. This field will be the column name on all exported files. It is recommended to use something that works easily with Esri Shapefiles that have a 10 character maximum column heading limitation.
requiredbooleanyesIs this field required?
disabledbooleanyesIs this field read only?
hiddenbooleanyesIs this field visible on mobile?
default_valuestringyesThe attribute to use as default value.
descriptionstringnoHelper text for the user.
visible_conditions_typestringnoMatch all or any of the conditions to display this field. ("all" or "any")
visible_conditionsarraynoArray of objects containing visibility conditions (see conditions table below).
required_conditions_typestringnoMatch all or any of the conditions to make this field required. ("all" or "any")
required_conditionsarraynoArray of objects containing requirement conditions (see conditions table below).

TextField

General free text entry. Launches the standard alphanumeric keyboard on mobile if numeric is false or the numeric keyboard if true. Non-numeric text fields support regex pattern validation.

PropertyTypeRequiredDescription
numericbooleannoIs it a numeric field?
formatstringnoIf it a numeric field, what is the format ("decimal" or "integer")?
patternstringnoCustom validation pattern using a regular expression (regex) pattern. More information.
pattern_descriptionstringnoDescription to show user on validation error.
min_lengthnumbernoMinimum length of text string (when numeric=false).
max_lengthnumbernoMaximum length of text string (when numeric=false).
minnumbernoMinimum number (when numeric=true).
maxnumbernoMaximum number (when numeric=true).
default_previous_valuebooleanfalseWhether to automatically set the previously used value.

DateTimeField

Formatted date entry. Launches the native calendar picker on mobile. Format for import is YYYY-MM-DD.

PropertyTypeRequiredDescription
default_previous_valuebooleanfalseWhether to automatically set the previously used value.
default_valuestringnoThe attribute to use as default value. Use now to default to today's date.

TimeField

Relative time (no timezone) with in 24-hour format (13:30). Launches the native time picker on mobile. Format for import is hh:mm.

PropertyTypeRequiredDescription
default_previous_valuebooleanfalseWhether to automatically set the previously used value.
default_valuestringnoThe attribute to use as default value. Use now to default to the current time.

YesNoField

For simple yes/no questions with optional neutral state.

PropertyTypeRequiredDescription
neutral_enabledbooleanyesEnable N/A choice?
neutralobjectif neutral_enabledLabel/Value for neutral choice ({"label": "N/A","value": "n/a"}).
positiveobjectyesLabel/Value for positive choice ({"label": "Yes","value": "yes"}).
negativeobjectyesLabel/Value for positive choice ({"label": "No","value": "no"}).
default_previous_valuebooleanfalseWhether to automatically set the previously used value.

ChoiceField

Choices can be specified inline or referenced from a predefined choice list. Allowing “Other” will allow users to enter a custom value. Choice labels are displayed in the form while values are saved in the database.

PropertyTypeRequiredDescription
choicesarrayyesArray of choice objects ({"label":"My Label", "value":"My Value"}).
multiplebooleannoMultiple choice field?
allow_otherbooleannoAllow other values?
default_previous_valuebooleanfalseWhether to automatically set the previously used value.

ClassificationField

Similar to single choice field, but can have nested choices to give a logical grouping or hierarchy to the choices. ClassificationField elements must have a classification_set_id field that contains a valid id of an existing classification set object.

PropertyTypeRequiredDescription
classification_set_idstringyesThe id of the classification set to reference.
default_previous_valuebooleanfalseWhether to automatically set the previously used value.

PhotoField

Associate photos with this field by launching the camera or selecting from the camera roll. Each Photo field allows any number of photos to be added to it.

PropertyTypeRequiredDescription
min_lengthnumbernoMinimum number of photos.
max_lengthnumbernoMaximum number of photos.

VideoField

Associate videos with this field by launching the camera or selecting from the camera roll. Each Video field allows any number of videos to be added to it. Enabling the GPS track allows for spatial video playback with synced map.

PropertyTypeRequiredDescription
track_enabledbooleannoGPS track enabled?
audio_enabledbooleannoAudio enabled?
min_lengthnumbernoMinimum number of videos.
max_lengthnumbernoMaximum number of videos.

AudioField

Associate audio recordings with this field by launching the microphone or selecting from the camera roll. Each Audio field allows any number of audio files to be added to it. Enabling the GPS track allows for spatial audio playback with synced map.

PropertyTypeRequiredDescription
track_enabledbooleannoGPS track enabled?
min_lengthnumbernoMinimum number of audio recordings.
max_lengthnumbernoMaximum number of audio recordings.

Section

Use sections to group fields together to better organize your form for presentation to the user. Also includes display options: inline display simply provides a group heading while drill-down display makes the section display in a separate page.

PropertyTypeRequiredDescription
displaystringyesDisplay type ("inline", "drilldown")
elementsarrayyesArray of field elements nested within the section.

AddressField

Store a single street address. Can autopopulate on mobile devices by reverse geocoding the record’s location coordinates to determine the nearest address.

PropertyTypeRequiredDescription
auto_populatebooleannoAutomatically reverse geocode to determine address?

SignatureField

Capture electronic signatures to attach to the record with optional agreement text.

PropertyTypeRequiredDescription
agreement_textstringnoThe text that appears below the signature line.

HyperlinkField

Include a link to open a URL in the browser. Can also be used as an action button with data events.

PropertyTypeRequiredDescription
default_urlstringnoOptional default URL.

CalculatedField

Define dynamic expressions and perform calculations using values from other fields and JavaScript.

PropertyTypeRequiredDescription
displayobjectyesCalculation display object ({"style": "number","currency": null}).
expressionstringnoCalculation expression.
default_previous_valuebooleanfalseWhether to automatically set the previously used value.

BarcodeField

Scan a barcode or QR code and store the text value.

PropertyTypeRequiredDescription
default_previous_valuebooleanfalseWhether to automatically set the previously used value.

RecordLinkField

Select or create records from other apps you have access to.

PropertyTypeRequiredDescription
allow_existing_recordsbooleanyesWhether to allow the user to select existing records from the app linked in the record link field.
allow_creating_recordsbooleanyesWhether to allow the user to create new records in the app that is linked to the record link field.
allow_updating_recordsbooleanyesWhether to allow the user to update data in existing records in the app linked to the record link field.
allow_multiple_recordsbooleanyesWhether to allow the user to select multiple records to link from the app linked to the record link field.
record_conditions_typestringnoMatch all or any of the conditions to filter linked records. ("all" or "any")
record_conditionsarraynoArray of objects containing conditions to filter linked records (see conditions table below).
record_defaultsarraynoArray of objects containing conditions to filter linked records (see defaults table below).
default_previous_valuebooleanfalseWhether to automatically set the previously used value.

Record Link Default Properties

PropertyTypeDescription
source_field_keystringThe key of the source field.
destination_field_keystringThe key of the destination field.

Conditions

Every element in the form may have two types of conditionals: required_conditions (to force data entry into the given field) and visible_conditions (to hide/show fields dynamically -- to enable "decision tree"-like functionality). These allow for special conditions to be met before a field can be shown or a record can be created on the mobile device. These conditions are not used in the validation process for record imports.

PropertyTypeDescription
field_keystringThe key of the field to match.
operatorstringCondition operator ("equal_to", "not_equal_to", "is_empty", "is_not_empty").
valuestringThe value to match against key field. (empty string for "is_empty" and "is_not_empty")

Validations

The following properties must be included in order to create/update a form object in our system. Any validation errors will return a 422: Unprocessable Entity and an object with a list of validation errors.

Required Form Properties

PropertyTypeDescriptionExample
namestringThe name you've given this form."Fire Hydrant Inventory"
elementsarrayCustom form elements.Required element properties vary by field type (see form element properties tables above).

Example validation response if the name is not included:

{
  "form": {
    "errors": {
      "name": ["cannot be blank"]
    }
  }
}

Notes

  • The entire form object is required when making an update. Omitting existing elements will result in data loss! The typical workflow for updating an existing form is to fetch the form object, modify it, and then submit the PUT request.

Sample Response

{
  "form": {
    "name": "Fire Hydrant Inventory",
    "description": "Inventory of fire hydrant structures.",
    "bounding_box": [27.7644875, -87.9042981472685, 42.8251769, -73.8936123],
    "record_title_key": "8373",
    "title_field_keys": ["8373", "2832"],
    "status_field": {
      "type": "StatusField",
      "label": "Color",
      "key": "@status",
      "data_name": "color",
      "default_value": "Unknown",
      "enabled": true,
      "read_only": false,
      "hidden": false,
      "description": "",
      "choices": [{
        "label": "Unknown",
        "value": "Unknown",
        "color": "#B3B3B3"
      },
      {
        "label": "Blue",
        "value": "Blue",
        "color": "#1891C9"
      },
      {
        "label": "Green",
        "value": "Green",
        "color": "#87D30F"
      },
      {
        "label": "Orange",
        "value": "Orange",
        "color": "#FF8819"
      },
      {
        "label": "Red",
        "value": "Red",
        "color": "#CB0D0C"
      },
      {
        "label": "White",
        "value": "White",
        "color": "#FFFFFF"
      },
      {
        "label": "Yellow",
        "value": "Yellow",
        "color": "#FFD300"
      }],
      "required": false,
      "disabled": false
    },
    "auto_assign": false,
    "record_count": 97,
    "id": "7a0c3378-b63a-4707-b459-df499698f23c",
    "created_at": "2015-04-16T13:20:10Z",
    "updated_at": "2015-04-29T19:57:21Z",
    "image": "https://fulcrumapp.s3.amazonaws.com/form-images/7a0c3378-b63a-4707-b459-df499698f23c-0fe97096-fac5-41ec-81a6-b961b9ed9b24.png",
    "image_thumbnail": "https://fulcrumapp.s3.amazonaws.com/form-images/thumb_7a0c3378-b63a-4707-b459-df499698f23c-0fe97096-fac5-41ec-81a6-b961b9ed9b24.png",
    "image_small": "https://fulcrumapp.s3.amazonaws.com/form-images/small_7a0c3378-b63a-4707-b459-df499698f23c-0fe97096-fac5-41ec-81a6-b961b9ed9b24.png",
    "image_large": "https://fulcrumapp.s3.amazonaws.com/form-images/large_7a0c3378-b63a-4707-b459-df499698f23c-0fe97096-fac5-41ec-81a6-b961b9ed9b24.png",
    "elements": [{
      "type": "TextField",
      "key": "2832",
      "label": "ID Tag",
      "description": "Enter the asset tag ID",
      "required": false,
      "disabled": false,
      "hidden": false,
      "data_name": "id_tag",
      "default_value": null,
      "visible_conditions_type": null,
      "visible_conditions": null,
      "required_conditions_type": null,
      "required_conditions": null,
      "numeric": false,
      "pattern": null,
      "pattern_description": null,
      "min_length": null,
      "max_length": null
    },
    {
      "type": "ChoiceField",
      "key": "8373",
      "label": "Hydrant Type",
      "description": "What style of hydrant is it?",
      "required": false,
      "disabled": false,
      "hidden": false,
      "data_name": "hydrant_type",
      "default_value": null,
      "visible_conditions_type": null,
      "visible_conditions": null,
      "required_conditions_type": null,
      "required_conditions": null,
      "multiple": false,
      "allow_other": false,
      "choices": [{
        "label": "Pillar",
        "value": "Pillar"
      },
      {
        "label": "Pond",
        "value": "Pond"
      },
      {
        "label": "Standpipe",
        "value": "Standpipe"
      },
      {
        "label": "Underground",
        "value": "Underground"
      },
      {
        "label": "Wall",
        "value": "Wall"
      }]
    },
    {
      "type": "ChoiceField",
      "key": "11f8",
      "label": "Position",
      "description": "Where is the hydrant installed?",
      "required": false,
      "disabled": false,
      "hidden": false,
      "data_name": "position",
      "default_value": null,
      "visible_conditions_type": null,
      "visible_conditions": null,
      "required_conditions_type": null,
      "required_conditions": null,
      "multiple": false,
      "allow_other": false,
      "choices": [{
        "label": "Building",
        "value": "Building"
      },
      {
        "label": "Green Space",
        "value": "Green Space"
      },
      {
        "label": "Lane",
        "value": "Lane"
      },
      {
        "label": "Parking Lot",
        "value": "Parking Lot"
      },
      {
        "label": "Sidewalk",
        "value": "Sidewalk"
      }]
    },
    {
      "type": "TextField",
      "key": "57c9",
      "label": "Diameter",
      "description": null,
      "required": false,
      "disabled": false,
      "hidden": false,
      "data_name": "diameter",
      "default_value": null,
      "visible_conditions_type": null,
      "visible_conditions": null,
      "required_conditions_type": null,
      "required_conditions": null,
      "numeric": true,
      "format": "decimal",
      "min": null,
      "max": null,
      "min_length": null,
      "max_length": null
    },
    {
      "type": "PhotoField",
      "key": "193f",
      "label": "Photo",
      "description": null,
      "required": false,
      "disabled": false,
      "hidden": false,
      "data_name": "photo",
      "default_value": null,
      "visible_conditions_type": null,
      "visible_conditions": null,
      "required_conditions_type": null,
      "required_conditions": null,
      "min_length": null,
      "max_length": null
    }]
  }
}