Create a Basic Inspection

Use this page as a field reference for POST /v3/inspections. For credentials, team and inspection-type discovery, phone completion, and webhook delivery, follow Send Your First Inspection.

Quick Start Example

curl --request POST \
  --url https://vision-api.truepic.com/v3/inspections \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "team_id": 123,
    "inspection_type_id": 456,
    "customer_first_name": "Taylor",
    "customer_last_name": "Nguyen",
    "custom_field_values": ["TEST-CLAIM-001"],
    "send_methods": {
      "text": false,
      "email": true
    },
    "customer_email_address": "[email protected]",
    "include_list": true
  }'

Replace [email protected] with an email address you control. A successful response includes the inspection ID and smart link. This abbreviated example shows the fields you need:

{
  "response_code": 200,
  "message": "Success",
  "result": {
    "id": 789,
    "inspection_link": "visionbytruepic.com/INSPECTION_LINK",
    "team_id": 123,
    "inspection_type_id": 456
    // Additional inspection fields omitted.
  }
  // Additional response fields omitted.
}

Required Fields

All inspections must include these fields:

Team and Inspection Configuration

• team_id - Determines the team for this inspection. Teams control customer-facing branding, sender phone numbers, and other configuration settings.
• inspection_type_id - Controls the type of inspection being sent. Inspection types determine custom fields, lists, message templates, alerts, and available outcomes. Find these in Vision Dashboard under Settings > Inspection Types. See Inspection Types for the full configuration model.

Customer Information

• customer_first_name and customer_last_name - Customer's name for the inspection.
  • Alternative: Use customer_name if your inspection type has use_single_name_field set to true.

Custom Data

• custom_field_values - Array of values corresponding to the custom fields configured on your inspection type. All inspection types require at least one custom field, so this array must contain at least one value.

To render custom fields dynamically, call GET /v3/inspection-types and use the selected inspection type's custom_fields metadata. Send values in custom_field_values in the same order the fields appear in the custom_fields array. See Custom Fields for the complete workflow and validation rules.

Delivery Method

• send_methods - Object specifying how to deliver the inspection:
  JSON

  {
    "text": true,    // Send via SMS
    "email": false  // Send via email
  }

Contact Information (Conditional)

• customer_phone_number - Required if send_methods.text is true. Send the national number with digits only, 9–11 digits, and no + or country-code prefix.
• customer_phone_country - Optional; defaults to US. For another supported country (GB, IT, DE, NL, or FR), your team needs a sender number configured for that country. Ask Truepic to add one before creating the inspection.
• customer_email_address - Required if send_methods.email is true. Email address for email delivery.

List Configuration

• include_list - Must be set to true any time you want a list included in your inspection, whether you're using the default list from your inspection type or providing a custom list via the list property.

Optional: Add a custom note to the invitation message

If the message template for the selected inspection type contains the {{CustomNote}} template token, include message_supplement in the create-inspection request. Vision inserts the message_supplement value into the customer's text or email message wherever {{CustomNote}} appears.

{
  "message_supplement": "Please complete this inspection before your appointment on Friday."
}

message_supplement is the API field in the create-inspection request. {{CustomNote}} is the message template token that displays that value. See Message Template Sets for the full list of supported template variables.

Custom Lists (Advanced)

Lists define the photos, videos, and questions customers must provide during an inspection. You must always set include_list: true when you want a list included. By default, this uses the list configured for your inspection type. If you require a different list for each inspection, set include_list: true and provide a list property in your request to override the default. For a very basic list that might look something like this:

{
  "list": {
    "items": [
      {
        "type": "PHOTO",
        "name": "2019 Ford Focus (VIN: KNAHG8A80B7339463)",
        "is_required": true,
        "capture_max": 1
      },
      {
        "type": "PHOTO", 
        "name": "2012 Toyota Camry (VIN: 4T9BMBEBD939161X)",
        "is_required": true,
        "capture_max": 1
      }
    ]
  }
}

As a list grows they can get quite complex. If you do need a custom list, the best way to create that is to create a template list on the Dashboard under Settings > Lists. Then, send a GET request to /v3/lists/{list_id} to retrieve the list structure, modify the retrieved payload as needed and then include the modified payload under the list property in your inspection request

Additional Configuration Options

Many optional fields are available for advanced use cases. See the full API reference: Inspections > Create a new inspection request

What to read next

1. Send Your First Inspection — Follow the complete first-inspection workflow, including token creation, phone completion, and webhook delivery.
2. Webhook Setup — Configure and verify the endpoint that receives inspection events.
3. Webhook Actions — Choose the events your integration should process.