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. For customer integrations, a disabled feature returns 403 with the {response_code, message} response body and no error code. Inspections created while the feature is disabled do not include AI fields. Inspections that already have an AI Item Type snapshot keep their ai_item_types[] and AI result fields if the feature is later disabled.

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.

Understand Live and Test mode

Once an inspection type has an AI Analysis configuration, it is set to Live for all inspections or Test mode. The mode belongs to the inspection type, not the AI Item Type. An AI Item Type linked to several inspection types can be Live for all inspections on one type and in Test mode on another.

Live for all inspections

Live for all inspections is the working state. Each new inspection created from that type receives its own configuration copy, and AI Analysis runs automatically after the inspection is ready for review.

Test mode

Test mode lets an administrator rehearse a configuration in Vision. They can run AI Analysis manually against an existing inspection and review the results there. New inspections created while the type is in Test mode do not receive a configuration copy, so AI Analysis never runs for them automatically — not while the type is in Test mode, and not after it returns to Live for all inspections.

Test results are private to administrators in Vision. They do not appear in the API responses your integration reads, and they do not send notifications or webhooks.

When an administrator publishes a configuration in Vision, they can also promote results from inspections they tested. A promoted result becomes visible in the ordinary inspection response at that point.

What this means for your integration

• You cannot set or read the mode through the AI Item Type API. These responses do not report it.
• Creating or linking the first AI Item Type on an inspection type sets that type to Live for all inspections automatically.
• Publishing does not update older inspections. An inspection created while the type was unconfigured or in Test mode never receives AI Analysis automatically.
• A later mode change does not affect an inspection that already has a configuration copy.
• A promoted result can appear without a notification and can renumber that inspection's ai_item_types[] IDs. See Map results back to the inspection copy.

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.

Why AI Analysis might not run

If inspections are not coming back with AI results, check that the organization has the AI Analysis feature enabled and that the inspection type has an AI Item Type linked. If both are true, ask an administrator to check the inspection type in Vision. When a type has been switched to Test mode, creating, linking, or updating an AI Item Type still returns success but does not set it back to Live for all inspections.

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.

Handle refusals when updating or removing configuration

Unlinking the last AI Item Type from an inspection type removes that type's AI Analysis configuration, and can return 409. Unlinking one of several linked AI Item Types does not. Check error.code, not the HTTP status alone:

• test_runs_in_progress means one or more test attempts are queued or running. Its details object contains inspections: [{ inspection_id, attempt_id, state }].
• test_data_not_removable means some test data cannot be removed. Its details object contains generations: [{ generation_id, extraction_event_id, reason }]. Either ID can be null when it is not available for the refused record.

PUT /v3/org/{slug}/ai-item-types/{itemTypeId} does not block updates while a test is queued or running. It also does not set an inspection type back to Live for all inspections after an administrator has switched it to Test mode.

Read AI analysis results

After an inspection reaches the ready-for-review event, AI Analysis runs automatically if the inspection type was Live for all inspections at the moment the inspection was created. Read the results with the existing inspection-detail endpoint.

⚠️

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

AI results can appear on an inspection without a notification. Re-read the inspection to detect results; do not rely on webhooks alone.

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. These IDs are stable only within one response. If an administrator promotes a tested result for that inspection, item types and field IDs can be renumbered or removed in later responses. Do not persist them as long-lived keys.

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.

ai_analysis_status can also include evaluated_truepic_count, the number of captures AI Analysis evaluated after applying its capture limit. This field is optional and is absent until an extraction completes.

The entire ai_status_details.ai_analysis_status object is absent when the inspection has no AI Item Type snapshot. Check that the object exists before reading state or evaluated_truepic_count.

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.
13. When changing an inspection's type, handle 409 responses if an administrator has test data on that inspection. A queued or running test can block the change; see the inspection type-change endpoint documentation for its response details.