Forms

Create, read, update, or delete forms (apps)

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

Endpoints

Method Endpoint Description
GET /api/v2/forms.json Fetch a list of all available forms.
GET /api/v2/forms/:id.json Fetch a single form from the API.
POST /api/v2/forms.json Create a new form. Validation is required for this action.
PUT /api/v2/forms/:id.json Update a single form. The entire form representation must be included in the request. Validation is required for this action.
DELETE /api/v2/forms/:id.json Delete a form.

Query Parameters

Parameter Type Description
page integer The page number requested.
per_page integer Number of forms per page. By default, all requests are paginated to the maximum value of 20,000 items per request.
schema boolean schema=false will only return the form metadata.

Form Properties

Property Type Required Readonly Description
name string yes no The name you’ve given this form.
elements array yes no Custom form elements (see form elements table below).
id string no yes The unique ID of the form.
description string no no The description you’ve given this form.
bounding_box array no yes Bounding box containing all the form’s records. Format is [min_lat, min_long, max_lat, max_long]
title_field_keys array no no Array of strings, where the strings are keys for fields in the elements attribute.
status_field object no no Status field object (see status field table below).
auto_assign boolean no no Assigns records to the user who creates them.
hidden_on_dashboard boolean no no Is the form visible in the mobile dashboard?
geometry_required boolean no no Requiring the location will force a location to be saved with each record.
projects_enabled boolean no no Are projects enabled for this form?
assignment_enabled boolean no no Is record assignment enabled for this form?
geometry_types array no no Enables/disables record location. ['Point'] or []
script string no no Custom Data Events script.
record_count number no yes The number of records in this form.
created_at string no yes Timestamp when the form was created.
updated_at string no yes Timestamp when the form was last updated.
image string no yes The URL to the original image which was uploaded as this app’s icon.
image_thumbnail string no yes The URL to the thumbnail-sized image which was uploaded as this app’s icon. 160x160 px
image_small string no yes The URL to the small-sized image which was uploaded as this app’s icon. 320x320 px
image_large string no yes The URL to the large-sized image which was uploaded as this app’s icon. 640x640 px

Status Field Properties

Property Type Default Description
type string "StatusField" The type of field.
label string "Status" The label for this field.
key string "@status" The key for this field.
data_name string "status" The data name for this field.
default_value string "" The default value for this field.
enabled boolean false Whether this form has the status field enabled.
read_only boolean false Whether status can be modified by user.
hidden boolean false Whether status is visible on mobile.
description string "" The description for this field.
choices array [] See status field choices below.
required boolean false Whether status value is required.
default_previous_value boolean false Whether to automatically set the previously used value.

Status Field Choice Properties

Property Type Default Description
label string "" What’s shown to the user in the web and mobile apps when they select a status for records in this app.
value string "" What’s stored in the record.
color string "#CB0D0C" The hexadecimal value for the color used for the status and the marker color on the map.

Form Element Properties (all field types)

Property Type Required Description
type string yes Must 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".
key string yes The id for the field. Must be unique to the form and lowercase. The Fulcrum app builder uses system generated 4 character codes.
label string yes The field label, visible to mobile and web users.
data_name string yes Can 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.
required boolean yes Is this field required?
disabled boolean yes Is this field read only?
hidden boolean yes Is this field visible on mobile?
default_value string yes The attribute to use as default value.
description string no Helper text for the user.
visible_conditions_type string no Match all or any of the conditions to display this field. ("all" or "any")
visible_conditions array no Array of objects containing visibility conditions (see conditions table below).
required_conditions_type string no Match all or any of the conditions to make this field required. ("all" or "any")
required_conditions array no Array of objects containing requirement conditions (see conditions table below).

Additional Form Element Properties (TextField)

Property Type Required Description
numeric boolean no Is it a numeric field?
format string no If it a numeric field, what is the format ("decimal" or "integer")?
pattern string no Custom validation pattern using a regular expression (regex) pattern. More information.
pattern_description string no Description to show user on validation error.
min_length number no Minimum length of text string (when numeric=false).
max_length number no Maximum length of text string (when numeric=false).
min number no Minimum number (when numeric=true).
max number no Maximum number (when numeric=true).
default_previous_value boolean false Whether to automatically set the previously used value.

Additional Form Element Properties (DateTimeField)

Property Type Required Description
default_previous_value boolean false Whether to automatically set the previously used value.
default_value string no The attribute to use as default value. Use now to default to today’s date.

Additional Form Element Properties (TimeField)

Property Type Required Description
default_previous_value boolean false Whether to automatically set the previously used value.
default_value string no The attribute to use as default value. Use now to default to the current time.

Additional Form Element Properties (YesNoField)

Property Type Required Description
neutral_enabled boolean yes Enable N/A choice?
neutral object if neutral_enabled Label/Value for neutral choice ({"label": "N/A","value": "n/a"}).
positive object yes Label/Value for positive choice ({"label": "Yes","value": "yes"}).
negative object yes Label/Value for positive choice ({"label": "No","value": "no"}).
default_previous_value boolean false Whether to automatically set the previously used value.

Additional Form Element Properties (ChoiceField)

Property Type Required Description
choices array yes Array of choice objects.
multiple boolean no Multiple choice field?
allow_other boolean no Allow other values?
default_previous_value boolean false Whether to automatically set the previously used value.

Additional Form Element Properties (ClassificationField)

Property Type Required Description
classification_set_id string yes The id of the classification set to reference.
default_previous_value boolean false Whether to automatically set the previously used value.

Additional Form Element Properties (PhotoField)

Property Type Required Description
min_length number no Minimum number of photos.
max_length number no Maximum number of photos.

Additional Form Element Properties (VideoField)

Property Type Required Description
track_enabled boolean no GPS track enabled?
audio_enabled boolean no Audio enabled?
min_length number no Minimum number of videos.
max_length number no Maximum number of videos.

Additional Form Element Properties (AudioField)

Property Type Required Description
track_enabled boolean no GPS track enabled?
min_length number no Minimum number of audio recordings.
max_length number no Maximum number of audio recordings.

Additional Form Element Properties (Section)

Property Type Required Description
display string yes Display type ("inline", "drilldown")
elements array yes Array of field elements nested within the section.

Additional Form Element Properties (AddressField)

Property Type Required Description
auto_populate boolean no Automatically reverse geocode to determine address?

Additional Form Element Properties (SignatureField)

Property Type Required Description
agreement_text string no The text that appears below the signature line.

Additional Form Element Properties (HyperlinkField)

Property Type Required Description
default_url string no Optional default URL.

Additional Form Element Properties (CalculatedField)

Property Type Required Description
display object yes Calculation display object ({"style": "number","currency": null}).
expression string no Calculation expression.
default_previous_value boolean false Whether to automatically set the previously used value.

Additional Form Element Properties (RecordLinkField)

Property Type Required Description
allow_existing_records boolean yes Whether to allow the user to select existing records from the app linked in the record link field.
allow_creating_records boolean yes Whether to allow the user to create new records in the app that is linked to the record link field.
allow_updating_records boolean yes Whether to allow the user to update data in existing records in the app linked to the record link field.
allow_multiple_records boolean yes Whether to allow the user to select multiple records to link from the app linked to the record link field.
record_conditions_type string no Match all or any of the conditions to filter linked records. ("all" or "any")
record_conditions array no Array of objects containing conditions to filter linked records (see conditions table below).
record_defaults array no Array of objects containing conditions to filter linked records (see defaults table below).
default_previous_value boolean false Whether to automatically set the previously used value.
Property Type Required Description
source_field_key string The key of the source field.  
destination_field_key string The key of the destination field.  

Conditions

Property Type Description
field_key string The key of the field to match.
operator string Condition operator ("equal_to", "not_equal_to", "is_empty", "is_not_empty").
value string The 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

Property Type Description Example
name string The name you’ve given this form. "Fire Hydrant Inventory"
elements array Custom 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

Examples

Valid Form 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
    }]
  }
}

Get all forms

cURL

curl --request GET 'https://api.fulcrumapp.com/api/v2/forms.json' \
--header 'Accept: application/json' \
--header 'X-ApiToken: my-api-key'

jQuery

$.ajax({
  type: "GET",
  url: "https://api.fulcrumapp.com/api/v2/forms.json",
  contentType: "application/json",
  dataType: "json",
  headers: {
    "X-ApiToken": "my-api-key"
  },
  success: function (data) {
    // do something!
    console.log(data);
  }
});

Get a single form by ID

cURL

curl --request GET 'https://api.fulcrumapp.com/api/v2/forms/my-form-id.json' \
--header 'Accept: application/json' \
--header 'X-ApiToken: my-api-key'

jQuery

$.ajax({
  type: "GET",
  url: "https://api.fulcrumapp.com/api/v2/forms/my-form-id.json",
  contentType: "application/json",
  dataType: "json",
  headers: {
    "X-ApiToken": "my-api-key"
  },
  success: function (data) {
    // do something!
    console.log(data);
  }
});

Create a new form

cURL

curl --request POST 'https://api.fulcrumapp.com/api/v2/forms.json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-ApiToken: my-api-key' \
--data '{"form": {"name": "A cURL Test","description": "Inventory of fire hydrant structures.","elements": [{"type": "TextField","key": "2832","label": "ID Tag","data_name": "id_tag","description": "Enter the asset tag ID.","required": false,"disabled": false,"hidden": false,"default_value": ""},{"type": "ChoiceField","key": "8373","label": "Hydrant Type","data_name": "hydrant_type","description": "What style of hydrant is it?","required": false,"disabled": false,"hidden": false,"default_value": "","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"}]}]}}'

jQuery

$.ajax({
  type: "POST",
  url: "https://api.fulcrumapp.com/api/v2/forms.json",
  data: JSON.stringify({
    "form": {
      "name": "Fire Hydrant Inventory",
      "description": "Inventory of fire hydrant structures.",
      "elements": [{
        "type": "TextField",
        "key": "2832",
        "label": "ID Tag",
        "data_name": "id_tag",
        "description": "Enter the asset tag ID.",
        "required": false,
        "disabled": false,
        "hidden": false,
        "default_value": ""
      },
      {
        "type": "ChoiceField",
        "key": "8373",
        "label": "Hydrant Type",
        "data_name": "hydrant_type",
        "description": "What style of hydrant is it?",
        "required": false,
        "disabled": false,
        "hidden": false,
        "default_value": "",
        "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"
        }]
      }]
    }
  }),
  contentType: "application/json",
  dataType: "json",
  headers: {
    "X-ApiToken": "my-api-key"
  },
  success: function (data) {
    // do something!
    console.log(data);
  }
});

Update a form

cURL

curl --request PUT 'https://api.fulcrumapp.com/api/v2/forms/my-form-id.json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-ApiToken: my-api-key' \
--data '{"form": {"name": "Fire Hydrant Inventory","description": "Inventory of fire hydrant structures.","elements": [{"type": "TextField","key": "2832","label": "ID Tag","data_name": "id_tag","description": "Enter the asset tag ID.","required": false,"disabled": false,"hidden": false,"default_value": ""},{"type": "ChoiceField","key": "8373","label": "Hydrant Type","data_name": "hydrant_type","description": "What style of hydrant is it?","required": false,"disabled": false,"hidden": false,"default_value": "","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": "PhotoField","key": "193f","label": "Photos","data_name": "photos","required": false,"disabled": false,"hidden": false,"default_value": ""}]}}'

jQuery

$.ajax({
  type: "PUT",
  url: "https://api.fulcrumapp.com/api/v2/forms/my-form-id.json",
  data: JSON.stringify({
    "form": {
      "name": "Fire Hydrant Inventory",
      "description": "Inventory of fire hydrant structures.",
      "elements": [{
        "type": "TextField",
        "key": "2832",
        "label": "ID Tag",
        "data_name": "id_tag",
        "description": "Enter the asset tag ID.",
        "required": false,
        "disabled": false,
        "hidden": false,
        "default_value": ""
      },
      {
        "type": "ChoiceField",
        "key": "8373",
        "label": "Hydrant Type",
        "data_name": "hydrant_type",
        "description": "What style of hydrant is it?",
        "required": false,
        "disabled": false,
        "hidden": false,
        "default_value": "",
        "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": "PhotoField",
        "key": "193f",
        "label": "Photos",
        "data_name": "photos",
        "required": false,
        "disabled": false,
        "hidden": false,
        "default_value": ""
      }]
    }
  }),
  contentType: "application/json",
  dataType: "json",
  headers: {
    "X-ApiToken": "my-api-key"
  },
  success: function (data) {
    // do something!
    console.log(data);
  }
});

Delete a form

cURL

curl --request DELETE 'https://api.fulcrumapp.com/api/v2/forms/my-form-id.json' \
--header 'Accept: application/json' \
--header 'X-ApiToken: my-api-key'

jQuery

$.ajax({
  type: "DELETE",
  url: "https://api.fulcrumapp.com/api/v2/forms/my-form-id.json",
  contentType: "application/json",
  dataType: "json",
  headers: {
    "X-ApiToken": "my-api-key"
  },
  success: function (data) {
    // do something!
    console.log(data);
  }
});