Custom Fields

Custom fields attach your organization’s identifiers, such as claim numbers or policy numbers, to every inspection you create.

Custom fields are defined on an inspection type. Before creating an inspection, retrieve the inspection type, map each configured field to a value, and send the values in the same order.

Create an inspection with custom fields

1. Configure custom fields on the inspection type in the Vision Dashboard.

   Every inspection type has at least one custom field. Choose labels that make sense to the people who create inspections and receive customer communications.

2. Retrieve the inspection type with GET /v3/inspection-types.

   The response includes the selected inspection type’s custom_fields array. Use the array order to build custom_field_values.

   title="GET /v3/inspection-types response excerpt"

   {
     "id": 456,
     "name": "Auto Claim",
     "custom_fields": [
       {
         "label": "Claim Number",
         "entry_method": "ENTRY_METHOD_TEXT",
         "is_required": true
       },
       {
         "label": "Policy Number",
         "entry_method": "ENTRY_METHOD_TEXT",
         "is_required": false
       },
       {
         "label": "Loss Type",
         "entry_method": "ENTRY_METHOD_SELECTABLE",
         "is_required": false,
         "custom_field_option_set_id": 12,
         "custom_field_options": [
           { "value": "COLLISION", "name": "Collision" },
           { "value": "COMPREHENSIVE", "name": "Comprehensive" },
           { "value": "GLASS_ONLY", "name": "Glass Only" }
         ]
       }
     ]
   }

   custom_field_options is populated only for selectable fields, and it is read-only. Vision assembles it at read time from the option set named by custom_field_option_set_id.

3. Send custom_field_values when you create the inspection.

   The array is positional: the first value maps to the first item in custom_fields, the second value maps to the second item, and so on.

   title="POST /v3/inspections"

   {
     "team_id": 123,
     "inspection_type_id": 456,
     "customer_first_name": "Alex",
     "customer_last_name": "Rivera",
     "customer_phone_number": "5555550123",
     "send_methods": {
       "text": true,
       "email": false
     },
     "custom_field_values": [
       "CLM-2024-8891",
       "POL-44821",
       "COLLISION"
     ]
   }

   For a selectable field, send the option’s value, not its display name. In the example above, COLLISION is the option’s value; the text shown in the Dashboard is its name, Collision.

   A successful request returns 200 and an inspection object containing the submitted custom_field_values.

4. Send null for optional fields without a value.

   Optional fields still require a position in the array. For the inspection type in the example, send:

   JSON

   {
     "custom_field_values": ["CLM-2024-8891", null, null]
   }

Understand custom field metadata

Each item in an inspection type’s custom_fields array describes one expected value.

The API response preserves the custom field order. It does not provide a separate ordering property.

Configure selectable fields

You cannot define options inline on an inspection type. Create the option set first in the Vision Dashboard, then reference its ID from the custom field with custom_field_option_set_id.

custom_field_option_set_id is required when entry_method is ENTRY_METHOD_SELECTABLE. When writing an inspection type, a custom field accepts only label, entry_method, custom_field_option_set_id, and is_required.

Keep field order stable

The field position is the binding between an inspection type’s custom_fields and an inspection’s custom_field_values. Message-template variables and custom-field search filters also use positions.

Use these practices when changing an inspection type:

• Put your primary business identifier first.
• Append new fields instead of inserting them between existing fields.
• Do not reorder or remove existing fields without auditing integrations and templates that use their positions.
• Update integrations when you add a field, because their custom_field_values arrays must include the new position.

Optional: Use custom fields in message templates

Message templates can reference a custom field’s label or value by its 1-based position.

For example, this template text:

Hi {{CustomerFirstName}}, please add photos for {{CustomFieldLabel_1}} {{CustomFieldValue_1}}: {{SmartLink}}

renders with the example values as:

Hi Alex, please add photos for Claim Number CLM-2024-8891: https://...

Write templates so they remain understandable when an optional custom field has no value.

See Message Template Sets for the complete variable list.

Optional: Use custom fields in content analysis

A list item can use the CUSTOM_FIELD_MATCHING content-analysis test. This test compares captured content with a custom field selected by index.

Because the test uses a custom field index, changing field order can change the value it evaluates. Configure the test in the Vision Dashboard and keep the inspection type’s field order stable.

See Lists for list configuration and Alerts for alert configuration.

Optional: Update custom field values

Use PUT /v3/inspections/{inspectionId} to update an inspection’s custom field values. Send values in the same order as the inspection type’s custom_fields array, and send null for optional positions without a value.

{
  "custom_field_values": ["CLM-2024-8891", "POL-44821", null]
}

The updated inspection response includes the current custom_field_values array.

See Update Inspections for other supported inspection updates.

Optional: Find inspections by custom field

Use GET /v3/inspections to search across custom field values or filter an exact value by position.

GET /v3/inspections?filter[custom_field_1][=]=CLM-2024-8891

Custom-field filters support positions 1 through 20. They trim surrounding whitespace and ignore letter case. You can also use filter[q][=] to search across all custom field values and other inspection data.

See Find Inspections for all filtering and search options.

Related API endpoints

What to read next