AI Analysis

Use AI Analysis to review a full inspection, extract structured insights from its evidence, and return results reviewers can act on faster.

⚠️

AI can make mistakes. Review all AI Analysis results before using them to make decisions.

AI Analysis helps Vision interpret photos, videos, and question responses across an inspection. You create AI Item Types and apply them to inspection types so Vision knows what items to expect and what information to extract during review.

Each AI Item Type has two sections:

• Item Information — structured fields Vision should answer for each expected item, such as manufacturer, model, serial number, condition, or movement type.
• Additional Details — supporting items to look for and free-text considerations that guide the analysis.

Apply an AI Item Type to an inspection type when inspections created from that type should use the same AI analysis instructions. When an inspection is created, Vision saves a copy of the linked AI Item Type configuration on that inspection, similar to how list items are copied onto an inspection. The inspection response includes that copy alongside the extracted AI results, so you can map each result back to the field or detail it answers.

📘

AI Analysis requires the organization feature ai_analysis_configuration. You cannot enable this feature yourself. Contact your sales or service representative to enable AI Analysis for your organization. If the feature is disabled, the admin endpoints return 403 feature_not_enabled and the new AI fields are omitted from inspection responses.

Why use AI Analysis

Most inspections collect photos, videos, and question responses about a real-world item. That item might be a watch, car, home, business, piece of equipment, or another physical thing a reviewer needs to understand.

Reviewing an inspection means using the submitted evidence to understand the current state of that item. AI Analysis reviews the inspection as a whole, extracts the facts your team needs, and surfaces supporting details that help reviewers make faster decisions.

Use AI Analysis when you want Vision to turn inspection evidence into structured review information. Instead of manually reading every response and checking every photo for the same details, you can define the information your team needs once on the inspection type and then read consistent AI results from each inspection response.

Understand AI Item Types

An AI Item Type is the configuration for an expected item in an inspection. It answers: “What kind of item should Vision identify, and what should Vision report about it?”

For example, a Watch AI Item Type can tell Vision to look for a watch, extract structured fields such as manufacturer and movement type, and check for supporting details such as a warranty card or appraisal document.

Link an AI Item Type to an inspection type when every inspection created from that type should use the same AI analysis instructions. The inspection response includes ai_item_types[], which is the inspection's saved copy of the AI Item Type configuration. Use that copy to interpret result IDs returned in ai_status_details.

AI Item Type vs. AI item result

An AI Item Type is the reusable configuration you create and manage with the admin endpoints. It defines both the kind of item Vision should try to detect in an inspection and the information Vision should extract when it finds that item.

An AI item result is an instance of an item Vision detected in a specific inspection. Vision returns detected expected items in ai_status_details.ai_items[], where each result points back to the AI Item Type that guided detection and extraction.

Use ai_item_types[] in the inspection response as the configuration copy for that inspection. Then match each result's item_type_id and field_id back to that copy.

Item Information

Use Item Information for questions that should produce a structured answer for each expected item. These fields are best for values you want to display in a table, validate, or use to drive review workflows.

Examples include:

• Manufacturer
• Model
• Serial number
• Condition
• Movement type

Each field defines how Vision should answer:

• Use open_answer for free-form values, such as manufacturer or serial number.
• Use choose_from_options for controlled values, such as movement type.
• Use warn_mode to decide whether missing or found values should create a review warning.

Additional Details

Use Additional Details for supporting evidence and broader observations that help reviewers understand the item but are not individual structured field answers.

Additional Details has two parts:

• items_to_look_for for related documents, accessories, or evidence, such as a warranty card or appraisal document.
• considerations for free-text analysis guidance, such as noting signs of polishing or refinishing.

Additional Details results appear under ai_status_details.ai_additional_details, not as Item Information field answers. Use them when you want Vision to report observations or supporting findings instead of filling a per-item field.

Choose the right section

Use this guidance when deciding whether a requirement belongs in Item Information or Additional Details.

Use Item Information when you need a structured answer

Define the field under item_information.fields[] when:

• You need one answer per expected item.
  • Example: manufacturer, model, serial number, condition, or movement type.
  • Results map to ai_status_details.ai_items[].item_information[].
• You need the answer to come from an allowed set of values.
  • Use response_mode: "choose_from_options".
  • Vision returns a structured answer that matches your configured options.
• Missing or found values should create a review warning.
  • Use warn_mode.
  • Field-level warnings drive disposition and inspection-level ai_status.

Use Additional Details when you need supporting findings

Define the guidance under additional_details when:

• You want Vision to look for supporting documents, accessories, or evidence.
  • Use items_to_look_for.
  • Results appear in ai_status_details.ai_additional_details.items_found[].
• You want to give broader analysis guidance.
  • Use considerations.
  • Vision returns consideration-based observations without requiring a separate structured field.

Configure an AI Item Type

Create an AI Item Type with POST /v3/org/{slug}/ai-item-types.

Include inspection_type_ids to attach the AI Item Type to one or more inspection types when you create it.

POST /v3/org/{slug}/ai-item-types
Content-Type: application/json

{
  "inspection_type_ids": [88],
  "name": "Watch",
  "item_information": {
    "fields": [
      {
        "name": "Manufacturer",
        "description": "Brand of the watch. Read from dial OCR, warranty card, or appraisal text.",
        "response_mode": "open_answer",
        "warn_mode": "missing",
        "position": 1
      },
      {
        "name": "Movement type",
        "description": "Mechanical, automatic, or quartz. Read from dial text or appraisal.",
        "response_mode": "choose_from_options",
        "options_multiple": false,
        "options": [
          { "label": "Mechanical", "position": 1 },
          { "label": "Automatic", "position": 2 },
          { "label": "Quartz", "position": 3 }
        ],
        "warn_mode": null,
        "position": 2
      }
    ]
  },
  "additional_details": {
    "items_to_look_for": [
      { "label": "Warranty card", "position": 1 },
      { "label": "Appraisal document", "position": 2 }
    ],
    "considerations": "Note any signs of polishing or refinishing on the case and bracelet."
  }
}

For response schemas, status codes, and management operations such as listing, updating, linking, unlinking, or deleting AI Item Types, see the AI Item Types API reference.

When you update an AI Item Type, existing inspections keep the configuration copy they were created with. New inspections use the latest configuration linked to their inspection type.

AI Item Type rules to remember

Keep these rules in your integration or admin UI validation:

• inspection_type_ids is required when creating an AI Item Type and forbidden when updating one.
• An AI Item Type can have up to 20 Item Information fields.
• An AI Item Type can have up to 20 Additional Details items to look for.
• response_mode must be open_answer or choose_from_options.
• Fields using choose_from_options must include options_multiple and at least one option.
• Fields using open_answer must not include options_multiple or options.
• warn_mode controls when a field creates a warning:
  • missing warns when the AI cannot find the value.
  • found warns when the AI does find the value.
  • null creates no warning for that field unless there is a conflict.

Read AI analysis results

After an inspection reaches the ready-for-review event, AI Analysis runs automatically for inspections created from linked inspection types. Read the results with the existing inspection-detail endpoint.

⚠️

AI analysis results are not always available immediately when the inspection becomes ready for review. API clients should poll GET /v3/inspections/{inspectionId} while ai_status_details.ai_analysis_status.state is waiting or running, and wait until the state changes to completed or failed before treating results as final.

GET /v3/inspections/{inspectionId}

For inspections using AI Analysis, the response includes:

After ai_status_details.ai_analysis_status.state reaches completed, key off the top-level ai_status first: pass means all Item Information fields passed, and warn means at least one field needs review. Then resolve AI result IDs against the ai_item_types[] copy in the same response to show reviewers the fields, findings, sources, and warning details behind that result.

{
  "ai_status": "warn",
  "ai_item_types": [
    {
      "id": 4099,
      "name": "Watch",
      "item_information": {
        "fields": [
          {
            "id": 50231,
            "name": "Manufacturer",
            "description": "Brand of the watch. Read from dial OCR, warranty card, or appraisal text.",
            "response_mode": "open_answer",
            "warn_mode": "missing",
            "position": 1
          }
        ]
      },
      "additional_details": {
        "items_to_look_for": [
          {
            "uuid": "a1b2c3d4-0001-0000-0000-000000000000",
            "label": "Warranty card",
            "position": 1
          }
        ],
        "considerations": "Note any signs of polishing or refinishing on the case and bracelet."
      }
    }
  ],
  "ai_status_details": {
    "summary": "Watch identified. Manufacturer extracted.",
    "detected_items": [
      {
        "id": 990001,
        "kind": "expected",
        "detected_type": "watch",
        "item_index": 0,
        "truepic_ids": [678901, 678902],
        "summary": "Rolex watch identified."
      }
    ],
    "ai_items": [
      {
        "id": 990001,
        "item_index": 0,
        "detected_type": "watch",
        "truepic_ids": [678901, 678902],
        "item_type_id": 4099,
        "classification_confidence": 0.97,
        "item_information": [
          {
            "field_id": 50231,
            "field_name": "Manufacturer",
            "status": "found",
            "value": "Rolex",
            "sources": [
              {
                "type": "photo_text",
                "truepic_ids": [678901],
                "string": "ROLEX"
              }
            ],
            "candidate_values": [],
            "confidence": 0.99,
            "reasoning": "Brand appears in OCR on dial photos.",
            "disposition": "pass"
          }
        ],
        "additional_details_attribution": [880011]
      }
    ],
    "ai_additional_details": {
      "items_found": [
        {
          "id": 880011,
          "lookfor_id": "a1b2c3d4-0001-0000-0000-000000000000",
          "label": "Warranty card",
          "item_id": 990001,
          "observation": "Original warranty card photographed alongside the watch.",
          "sources": [
            {
              "type": "photo_text",
              "truepic_ids": [678904],
              "string": "DATE OF PURCHASE 06-11-2021"
            }
          ],
          "confidence": 0.95
        }
      ],
      "considerations_observations": []
    },
    "ai_analysis_status": {
      "state": "completed",
      "completed_event_count": 1,
      "last_completed_at": "2026-05-18T10:23:45Z"
    }
  }
}

Map results back to the inspection copy

Use these relationships when working with the inspection response:

1. Match ai_status_details.ai_items[].item_type_id to ai_item_types[].id.
2. Match ai_status_details.ai_items[].item_information[].field_id to ai_item_types[].item_information.fields[].id.
3. Match ai_status_details.ai_additional_details.items_found[].lookfor_id to ai_item_types[].additional_details.items_to_look_for[].uuid.
4. Use truepic_ids to link answers and detected items back to captures.

ai_item_types[] is the inspection's saved copy of the AI Item Type configuration. Always match AI result IDs against the ai_item_types[] in the same inspection response instead of looking up the latest AI Item Type through the admin endpoints.

Understand sources

Vision returns sources[] to explain the evidence behind an AI decision, such as a field answer, additional detail, or candidate value. Each source object has a type that identifies the kind of evidence Vision used and determines which other fields are present.

Sources can appear in these places:

• ai_status_details.ai_items[].item_information[].sources[] for the current Item Information answer.
• ai_status_details.ai_items[].item_information[].candidate_values[].sources[] for each side of a conflict.
• ai_status_details.ai_additional_details.items_found[].sources[] for supporting findings.

Source types

Source fields

Customer-stated sources

customer_stated sources have two shapes, depending on where the customer-provided information came from.

Use intake_field: "comment" when the source is a customer comment. In this case, the source includes the comment text and associated captures:

{
  "type": "customer_stated",
  "intake_field": "comment",
  "string": "The watch was serviced in 2024.",
  "truepic_ids": [678901]
}

Use intake_field: "list_item_answer" when the source is an answer to a list item. In this case, the source includes the answer text and the matching list item IDs:

{
  "type": "customer_stated",
  "intake_field": "list_item_answer",
  "string": "Automatic",
  "list_item_ids": [334455]
}

When rendering sources, use truepic_ids to link evidence back to captures and list_item_ids to link customer-stated answers back to the relevant list items. A sources array can be empty, so your integration should handle an answer or finding that has no source objects.

Understand result statuses

Each Item Information answer has a status and a disposition.

A conflict status can happen after you request more information, resend an inspection, and the user submits new photos or responses. When AI Analysis runs again, Vision compares the new extraction with the prior extraction. If the answer changed, the field returns status: "conflict" so reviewers can see that the analysis changed and compare the candidate values.

When a field has status: "found", read the extracted answer from the field-level value, confidence, sources, and reasoning properties. These properties describe the current result for that field.

When a field has status: "conflict", candidate_values[] contains the different results Vision produced across separate analysis runs. Use these candidates to show reviewers what changed between the prior extraction and the latest extraction.

Each candidate value includes:

disposition is the field-level decision:

At the inspection level, AI Analysis emits ai_status. Use this top-level result as the first decision point after analysis completes:

AI Analysis does not emit ai_status: "fail". Unexpected items are included in the response for review, but they do not affect ai_status in V1. Review all AI Analysis results even when ai_status is pass, because AI-generated results can be incorrect.

Track analysis progress

Use ai_status_details.ai_analysis_status.state to determine whether analysis results are ready. Results appear only after the ready-for-review event, and processing can continue for some time after that event.

You do not need to trigger analysis with a separate endpoint. Once configured, analysis runs automatically after inspections become ready for review. API clients should expect a processing delay and continue polling while the state is waiting or running; treat completed or failed as the terminal states for the latest analysis run.

Migration notes

AI Analysis replaces Vision AI and the legacy user-criteria workflow for inspections that use the new feature.

• The previous inspection_ready_criteria_text prompt maps conceptually to Additional Details considerations.
• ai_user_criteria_results is not used for inspections running on AI Analysis Configuration.
• ai_status_reason is no longer emitted. Do not depend on it.

Integration checklist

1. Create an AI Item Type with the fields and additional details you want Vision to analyze.
2. Link the AI Item Type to the inspection type used to create inspections.
3. Create inspections as usual from that inspection type.
4. Read results from GET /v3/inspections/{inspectionId}.
5. After analysis completes, key off ai_status to decide whether the inspection has AI-related warnings.
6. Use ai_item_types[] as the saved AI Item Type configuration for that inspection.
7. Extract answers from ai_status_details.ai_items[].
8. Extract findings from ai_status_details.ai_additional_details.
9. Use truepic_ids when linking AI evidence to captures.
10. Poll after the ready-for-review event until AI analysis reaches completed or failed.
11. Treat waiting and running as pending analysis states.
12. Review all AI Analysis results before using them to make decisions.