---
title: "List fields"
method: POST
path: "/structures/v1/fields/list"
tags: ["Structures"]
---

# List fields

`POST /structures/v1/fields/list`

## Request

- Base URL: `https://api.mitti.com`
- URL: `https://api.mitti.com/structures/v1/fields/list`
- Auth: HTTP bearer

Returns the field definitions in your organization. Use it to resolve the `field_id` values you need before setting field values on a structure, filtering by the structure type a field applies to. Each field carries its type, whether it is required, and its per-structure-type settings.

## Request body

- S12StructuresV1ListFieldsRequest
  - `filter` S12StructuresV1ListFieldsRequestFieldsFilter: Filters that narrow which fields are returned. Filters combine with AND — a field is returned only when it satisfies every filter supplied.
    - `field_category` 'FIELD_CATEGORY_UNSPECIFIED' | 'FIELD_CATEGORY_SYSTEM_FIELD' | 'FIELD_CATEGORY_CUSTOM_FIELD': - FIELD_CATEGORY_UNSPECIFIED: Field category Unspecified. - FIELD_CATEGORY_SYSTEM_FIELD: Field category pre-defined. - FIELD_CATEGORY_CUSTOM_FIELD: Field category custom.
    - `field_value_types` S12TypefieldV1FieldValueType[]: Optional. Restrict to fields whose value is one of these types.
    - `query` string: Optional. Restrict to fields whose name matches this search text.
    - `created_by` string[]: Optional. Restrict to fields created by any of these users, identified by user ID.
    - `applies_to` string[]: Optional. Restrict to fields mapped to any of these structure types, identified by structure type ID. Set this to find the fields that apply to the type of structure you are about to create.
    - `status` 'FIELD_STATUS_ACTIVE' | 'FIELD_STATUS_ARCHIVED': - FIELD_STATUS_ACTIVE: The field is active and can hold values on structures. - FIELD_STATUS_ARCHIVED: The field is archived and can no longer be set on structures.
    - `mapping_metadata` object: Optional. Restrict to fields that have at least one mapping whose metadata contains every supplied key/value pair. Typically combined with `applies_to` to scope to a specific structure type. Supported keys today: "display_on_profiles", "field_required".
  - `page_token` string: Optional. The `next_page_token` returned by a previous call, to fetch the following page of results. Omit it to fetch the first page.
  - `page_size` integer: Optional. The number of fields to return per page, between 1 and 100. Defaults to 25.

## Response `200`

A successful response.

- S12StructuresV1ListFieldsResponse
  - `fields` S12StructuresV1Field[]: The fields matching the request, ordered with system fields before custom fields.
    - `id` string: The unique identifier for the field.
    - `field_value_type` 'FIELD_VALUE_TYPE_UNSPECIFIED' | 'FIELD_VALUE_TYPE_STRING' | 'FIELD_VALUE_TYPE_MONEY' | 'FIELD_VALUE_TYPE_TIMESTAMP' | 'FIELD_VALUE_TYPE_USER_ID' | 'FIELD_VALUE_TYPE_SELECT' | 'FIELD_VALUE_TYPE_TEMPLATE_ID' | 'FIELD_VALUE_TYPE_MULTI_SELECT' | 'FIELD_VALUE_TYPE_SITE' | 'FIELD_VALUE_TYPE_MULTI_SITE' | 'FIELD_VALUE_TYPE_INTEGER' | 'FIELD_VALUE_TYPE_ADDRESS' | 'FIELD_VALUE_TYPE_TIMEZONE' | 'FIELD_VALUE_TYPE_CONTACT_DETAILS': Type of FieldValue. Defaults to type String. - FIELD_VALUE_TYPE_UNSPECIFIED: Field value type unspecified. - FIELD_VALUE_TYPE_STRING: Field value type string. - FIELD_VALUE_TYPE_MONEY: Field value type money. - FIELD_VALUE_TYPE_TIMESTAMP: Field value type timestamp. - FIELD_VALUE_TYPE_USER_ID: Field value type user ID. - FIELD_VALUE_TYPE_SELECT: Field value type select - FIELD_VALUE_TYPE_TEMPLATE_ID: Field value type template ID. - FIELD_VALUE_TYPE_MULTI_SELECT: Field value type multi-select - FIELD_VALUE_TYPE_SITE: Field value type site - FIELD_VALUE_TYPE_MULTI_SITE: Field value type multi-site - FIELD_VALUE_TYPE_INTEGER: Field value type integer - FIELD_VALUE_TYPE_ADDRESS: Field value type address. - FIELD_VALUE_TYPE_TIMEZONE: Field value type timezone - FIELD_VALUE_TYPE_CONTACT_DETAILS: Field value type contact details
    - `name` string: The display name of the field.
    - `description` string: The description of the field.
    - `category` 'FIELD_CATEGORY_UNSPECIFIED' | 'FIELD_CATEGORY_SYSTEM_FIELD' | 'FIELD_CATEGORY_CUSTOM_FIELD': - FIELD_CATEGORY_UNSPECIFIED: Field category Unspecified. - FIELD_CATEGORY_SYSTEM_FIELD: Field category pre-defined. - FIELD_CATEGORY_CUSTOM_FIELD: Field category custom.
    - `select_options` S12TypefieldV1FieldOption[]: The options that a value for this field can be chosen from. Populated only for the select and multi-select field value types.
      - `id` string: The id of a field select option.
      - `label` string: The label of a field select option.
      - `order` integer: The display order of this option, 0-indexed. Options should be displayed in ascending order of this field, matching the order they were defined in the field settings.
    - `structure_settings` S12StructuresV1FieldStructureTypeSettings[]: The structure types this field applies to, and how it behaves on each — whether it is required and whether it displays on that type's profile.
      - union: The mapping between a field and one structure type it applies to. The mapping controls whether the field is required for structures of that type, whether it displays on their profile, and what value it takes when none is supplied.
        - object
          - `structure_type_id` string, required: The unique identifier of the structure type this mapping applies to.
          - `field_required` boolean: Whether a structure of this type must carry a value for the field.
          - `display_on_profiles` boolean: Whether the field displays on the profile of a structure of this type. Reading a structure returns only the field values whose field has this set.
          - `string_value` string, required: Default string value for FIELD_VALUE_TYPE_STRING, FIELD_VALUE_TYPE_TIMEZONE, FIELD_VALUE_TYPE_USER_ID, FIELD_VALUE_TYPE_TEMPLATE_ID and FIELD_VALUE_TYPE_SITE.
        - object
          - `structure_type_id` string, required: The unique identifier of the structure type this mapping applies to.
          - `field_required` boolean: Whether a structure of this type must carry a value for the field.
          - `display_on_profiles` boolean: Whether the field displays on the profile of a structure of this type. Reading a structure returns only the field values whose field has this set.
          - `timestamp_value` string, date-time, required: Default timestamp value for FIELD_VALUE_TYPE_TIMESTAMP.
        - object
          - `structure_type_id` string, required: The unique identifier of the structure type this mapping applies to.
          - `field_required` boolean: Whether a structure of this type must carry a value for the field.
          - `display_on_profiles` boolean: Whether the field displays on the profile of a structure of this type. Reading a structure returns only the field values whose field has this set.
          - `integer_value` string, int64, required: Default integer value for FIELD_VALUE_TYPE_INTEGER.
        - object
          - `structure_type_id` string, required: The unique identifier of the structure type this mapping applies to.
          - `field_required` boolean: Whether a structure of this type must carry a value for the field.
          - `display_on_profiles` boolean: Whether the field displays on the profile of a structure of this type. Reading a structure returns only the field values whose field has this set.
          - `select_options` S12TypefieldV1FieldOption, required
            - `id` string: The id of a field select option.
            - `label` string: The label of a field select option.
            - `order` integer: The display order of this option, 0-indexed. Options should be displayed in ascending order of this field, matching the order they were defined in the field settings.
    - `created_by` string: The ID of the user who created the field.
    - `status` 'FIELD_STATUS_ACTIVE' | 'FIELD_STATUS_ARCHIVED': - FIELD_STATUS_ACTIVE: The field is active and can hold values on structures. - FIELD_STATUS_ARCHIVED: The field is archived and can no longer be set on structures.
  - `next_page_token` string: The token to pass as `page_token` to fetch the next page of results. Empty when this is the last page.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-11-03** `eb6bb843bf18`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/safetyculture/apis/safetyculture-api/changes/structures/v1/fields/list/post.md)

---

[API](https://skmtc.dev/safetyculture/apis/safetyculture-api.md) - [All operations](https://skmtc.dev/safetyculture/apis/safetyculture-api/llms.txt) - [OpenAPI document](https://skmtc.dev/safetyculture/apis/safetyculture-api/revisions/eb6bb843bf18?raw)
