Lists

Build inspection lists in the Truepic Dashboard, then use default or custom list payloads in inspections so you collect exactly the information you need from each customer.

Prerequisites

1. Create and configure a list in the Admin Section of the Truepic Dashboard, then assign it to your inspection type if you want to use the default list for every inspection.
2. Set include_list: true any time you want a list included with an inspection.
3. Retrieve an existing list with GET /v3/lists/{list_id} if you need to customize that payload for a specific inspection.

Most teams should configure lists in the Admin Section of the Truepic Dashboard first. Lists can get complex, and the Dashboard UI is usually the fastest way to build item types, grouping, conditional logic, and other list options. Once the list is ready, assign it to the inspection type and use that default list for new inspections.

If you do need a custom list per inspection, build most of it in the Dashboard first, then fetch the list payload with GET /v3/lists/{list_id} and use that payload when creating the inspection. This lets you make only the inspection-specific changes in code instead of building the full list object from scratch.

Build a list

1. Choose where the list comes from

You can include a list in an inspection in two ways:

For most teams, the best starting point is a list configured in the Admin Section of the Truepic Dashboard and assigned to the inspection type.

1. Use the inspection type default list by setting include_list: true.
2. Override the default list per inspection by setting include_list: true and sending a custom list object in the request.

Use the default list when the inspection steps stay the same for every customer. Override the list only when the prompts need to change per inspection, such as vehicle-specific items or claim-specific follow-up questions. In that case, it is usually easiest to start with the Dashboard version of the list, retrieve the payload, and make only the inspection-specific changes in code.

2. Add the right item types

A list is made up of list items. A list item can be one of these types:

• PHOTO a photo
• IMAGE a photo or video
• VIDEO a video
• QUESTION a question - By default a question allows for a free form response, but you can also provide question properties to make it into a multiple choice question.

Most teams create these item types in the Dashboard. If you are sending a custom list object, use the same structure in your request payload.

When a customer opens the inspection, they move through the list item by item and submit the requested photo, video, or answer.

3. Configure the shared item properties

Most list items use the same core fields.

Start with type, name, and is_required. Add the other fields only when the inspection flow needs them.

4. Add question configuration when the item is a question

Question items use a nested question object.

Use a free-form question when you need a typed response. Use a multiple-choice question when the answer should drive conditional logic or standardized downstream review.

5. Send a custom list with the inspection

Use this pattern when you need to override the inspection type default list for a specific inspection. In most cases, you will save time by starting with a list built in the Dashboard, retrieving it with GET /v3/lists/{list_id}, and then modifying that payload before you send the inspection request.

Here is a basic custom list inside an inspection request:

{
  "include_list": true,
  "list": {
    "items": [
      {
        "type": "PHOTO",
        "name": "Front of vehicle",
        "is_required": true,
        "capture_max": 1
      },
      {
        "type": "VIDEO",
        "name": "Start the engine and record the dashboard",
        "is_required": true,
        "capture_max": 1
      },
      {
        "type": "QUESTION",
        "name": "Describe any visible damage",
        "is_required": false,
        "question": {
          "type": "FREE_FORM"
        }
      }
    ]
  }
}

This configuration gives the customer three prompts:

1. one required photo
2. one required video
3. one optional typed answer

Combine list items to match your workflow

Most production lists mix required media, optional supporting evidence, and questions that explain or route what happens next. If you are customizing a list payload in code, these patterns let you extend a list you already built in the Dashboard.

Example: group related prompts

Use group_id when several items belong together in the inspection response.

{
  "list": {
    "groups": {
      "vehicle_exterior": {
        "name": "Vehicle exterior"
      }
    },
    "items": [
      {
        "type": "IMAGE",
        "name": "Front of vehicle",
        "group_id": "vehicle_exterior",
        "is_required": true
      },
      {
        "type": "IMAGE",
        "name": "Rear of vehicle",
        "group_id": "vehicle_exterior",
        "is_required": true
      }
    ]
  }
}

In the inspection payload, you can resolve an item's group_id through result.list.groups to show reviewers the group name alongside the item prompt.

Example: mix required and optional evidence

{
  "list": {
    "items": [
      {
        "type": "PHOTO",
        "name": "Photo of the damaged area",
        "is_required": true,
        "capture_max": 2
      },
      {
        "type": "PHOTO",
        "name": "Photo of the wider scene",
        "is_required": false,
        "capture_max": 1
      },
      {
        "type": "QUESTION",
        "name": "When did the damage occur?",
        "is_required": true,
        "question": {
          "type": "FREE_FORM"
        }
      }
    ]
  }
}

Use this pattern when you need a minimum set of proof but want to give the customer a place to add helpful context.

Optional: Add conditional logic

Use conditional items when a prompt should appear only after a specific answer to a multiple-choice question. This is another case where the Dashboard is usually the easiest place to build and verify the flow before you work with the payload in code.

Here is the documented nested pattern:

[
  {
    "type": "QUESTION",
    "name": "Is the car in a drivable condition?",
    "condition_id": "abc-1234567890",
    "conditions": null,
    "question": {
      "type": "MULTIPLE_CHOICE",
      "options": {
        "choices": [
          { "name": "Yes" },
          { "name": "No" }
        ]
      }
    }
  },
  {
    "type": "QUESTION",
    "name": "Does the car have a broken windshield?",
    "condition_id": "def-1234567890",
    "conditions": [
      {
        "id": "abc-1234567890",
        "question": {
          "answer": "No"
        }
      }
    ],
    "question": {
      "type": "MULTIPLE_CHOICE",
      "options": {
        "choices": [
          { "name": "Yes" },
          { "name": "No" }
        ]
      }
    }
  },
  {
    "type": "PHOTO",
    "name": "Please take a photo of the broken windshield.",
    "condition_id": null,
    "conditions": [
      {
        "id": "def-1234567890",
        "question": {
          "answer": "Yes"
        }
      }
    ]
  }
]

This creates a step-by-step follow-up flow:

1. Ask whether the car is drivable.
2. Ask about the windshield only if the customer answers No.
3. Request a photo only if the customer then answers Yes.

Some important constraints from the existing conditional-items guide:

• You can create a maximum depth of five layers of conditional items.
• The conditions field is an array, so an item can be shown when any listed condition is met.
• The answer strings do not have to be Yes or No.

For the full walkthrough, see Conditional List Items.

Optional: Update a list after the inspection has been sent

Use PUT /text/request when you need to ask for more photos or videos on an existing inspection.

This workflow is usually easiest when the inspection started from a list you already configured in the Dashboard, because you can preserve the existing structure and update only the items that need more evidence.

When you update a list on an existing inspection:

1. Include all existing list items in list.items, not only the items you want to change.
2. Include each existing item's id so the API preserves that item and its current responses.
3. Set incomplete: true on the items the customer must redo.

{
  "inspection_id": 1843,
  "include_list": true,
  "list": {
    "items": [
      {
        "id": 501,
        "name": "Front of vehicle",
        "type": "IMAGE",
        "is_required": true,
        "incomplete": true
      },
      {
        "id": 502,
        "name": "Rear of vehicle",
        "type": "IMAGE",
        "is_required": true
      }
    ]
  }
}

If you omit an existing item, that item is removed from the inspection list and any submitted media for it becomes uncategorized because it is no longer associated with a current list item.

See list data in inspection responses

When you retrieve an inspection, each submitted photo can include:

• list_item_id to identify which prompt it belongs to
• list_item to embed the matching list item details when present

The returned list item can include fields such as:

• name
• type
• group_id
• content_analysis
• object_detection

Use this data to show reviewers both the customer submission and the original prompt that requested it.

What to read next