Send Your First Inspection

Send a Vision inspection, complete it on a phone, and confirm that your system receives its webhook event.

Before you begin

Complete these steps before starting:

1. Create API credentials for your organization in the Vision Dashboard. See Get API Access for the Dashboard steps and token request.
2. Choose an inspection type already configured for your team, or ask Truepic to configure one during onboarding. It needs at least one custom field and a default list (the photos, videos, or questions the customer must complete). See Inspection Types and Lists.
3. Use a phone number or email address that you control. Vision sends real SMS and email messages, including during testing.
4. Make a publicly reachable HTTPS endpoint available to receive webhooks. For a first test, use a request inspector such as webhook.site or expose a local endpoint through ngrok.

This walkthrough uses the US endpoints. If your organization uses the EU region, use the region-specific authorization and API URLs in Regions.

1. Generate API credentials and an access token

In the Vision Dashboard, open Settings > API Integration and select Generate API Credentials. Save the client ID and client secret in your server-side secret manager; do not expose them in a browser or mobile app.

Request an OAuth 2.0 access token with the client credentials flow:

curl --request POST \
  --url https://vision-auth.truepic.com/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "audience": "https://vision-api.truepic.com",
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

A successful response includes an access_token and its lifetime in seconds. This abbreviated example shows the fields you need:

{
  "access_token": "ACCESS_TOKEN",
  "expires_in": 259200,
  "token_type": "Bearer"
  // Additional response fields omitted.
}

Store and reuse the token until it expires. Vision access tokens are valid for 72 hours; generating a token for every API request is unnecessary. For credential-management details and region-specific authorization URLs, see Get API Access and Regions.

2. Find a team and inspection type

Every inspection requires a team_id and an inspection_type_id. The team controls branding and team-level behavior. The inspection type controls the required custom fields, list, customer messages, and other inspection configuration.

List your teams and save the id for the team you want to use:

curl --request GET \
  --url https://vision-api.truepic.com/v3/organization-teams \
  --header 'Authorization: Bearer ACCESS_TOKEN'

The response returns teams in result; each team's id is its team_id. This abbreviated example shows the fields you need:

{
  "response_code": 200,
  "result": [
    {
      "id": 123,
      "name": "Claims"
      // Additional team fields omitted.
    }
  ]
  // Additional response fields and teams omitted.
}

Next, list inspection types assigned to that team. Replace 123 with your team ID:

curl --request GET \
  --url 'https://vision-api.truepic.com/v3/inspection-types?filter[team_id][in][]=123' \
  --header 'Authorization: Bearer ACCESS_TOKEN'

Select an inspection type from result and record its id and custom_fields array. This abbreviated example shows the fields you need:

{
  "response_code": 200,
  "result": [
    {
      "id": 456,
      "name": "Vehicle inspection",
      "custom_fields": [
        {
          "label": "Claim number",
          "entry_method": "ENTRY_METHOD_TEXT",
          "is_required": true
        }
      ]
      // Additional inspection-type fields omitted.
    }
  ]
  // Additional response fields and inspection types omitted.
}

Send values in custom_field_values in exactly the same order as custom_fields. Provide null for an optional field you do not have a value for. If the selected type uses use_single_name_field: true, send customer_name instead of customer_first_name and customer_last_name. For the full configuration model, see Teams, Inspection Types, and Custom Fields.

3. Configure a webhook

Configure the webhook before creating the inspection so your endpoint receives its lifecycle events.

1. In the Vision Dashboard, open Settings > Webhooks.
2. Select the team you recorded in the previous step.
3. Enter your publicly reachable HTTPS webhook URL.
4. Select only the events your endpoint needs. For this walkthrough, select ACTION_STATUS_READY_FOR_REVIEW.
5. Set a webhook secret in your secure configuration, then activate and save the webhook.

Each team supports one webhook. If you do not select events, the webhook receives every event for its team. Select only the actions your handler uses to avoid unnecessary deliveries and processing; your handler should still ignore unexpected actions. You can also set enabled_events when creating or updating the webhook through the API. See Webhook Setup for configuration steps and Webhook Actions to choose event names.

Vision signs deliveries when you configure a secret and sends the signature in the truepic-signature header. Verify the signature against the unparsed request body, return 200 within 10 seconds, and deduplicate retries using stable payload fields such as the inspection ID and event action.

For a complete Node.js verification route and manual-verification guidance, see Webhook Setup. See Webhook Actions for all available events and Webhooks for delivery retries and common uses.

4. Create an inspection

Send an email inspection request to an address you control. Replace the IDs, email address, and custom-field value with your test values.

curl --request POST \
  --url https://vision-api.truepic.com/v3/inspections \
  --header 'Authorization: Bearer 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
  }'

A successful response has response_code: 200. Save result.id as the inspection ID and result.inspection_link as the smart link that opens the inspection. 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.
}

Replace [email protected] with an email address you control. For SMS delivery, set send_methods.text to true and provide both of these fields:

• customer_phone_number: 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.

If you set both send_methods.text and send_methods.email to false, Vision creates the inspection without messaging the customer. Share the returned inspection_link yourself to open it on your test phone. For required fields, delivery options, custom lists, and advanced request configuration, see Create Inspections.

5. Complete the inspection on a phone

1. Open the email or inspection_link on the test phone.
2. If your team uses the default Vision Native Apps, the link prompts the tester to install the Truepic Vision app before the inspection opens. This is expected; use the Vision Web Inspection App if you need a no-download flow.
3. Follow the prompts from the inspection's configured list to capture the required photos or videos and answer required questions.
4. Submit the inspection in the Vision app.

The exact prompts depend on the list assigned to your inspection type. After submission, Vision processes the inspection and moves it through the inspection lifecycle. See Lists to configure capture prompts, Inspection Statuses for the complete status model, and Compare Integration Approaches to choose a no-download web flow.

6. Confirm the webhook delivery

Inspect your webhook endpoint logs after the inspection reaches the configured event. For the ACTION_STATUS_READY_FOR_REVIEW event, confirm all of the following:

• The request reached your configured URL.
• The truepic-signature verification passed when you configured a secret.
• Your handler returned 200 within 10 seconds.
• Your handler recorded the inspection ID and event action before starting any longer-running work.

A ready-for-review delivery identifies the event in action and the inspection in result.id. This abbreviated example shows the fields you need:

{
  "action": "ACTION_STATUS_READY_FOR_REVIEW",
  "result": {
    "id": 789,
    "status": {
      "id_internal": "STATUS_READY_FOR_REVIEW",
      "name": "Ready for Review"
    }
  },
  "additional_fields": "omitted"
}

Use body.action to route the event and body.result.id with that action as your idempotency key. The full result object contains the inspection data and varies with your inspection configuration.

Some actions also include an operation object. For example, when body.action is ACTION_PDF_READY, retrieve the generated PDF URL from body.operation.result.url.

If you do not receive an event, confirm that the webhook is activated for the same team used in the create-inspection request, that ACTION_STATUS_READY_FOR_REVIEW is selected, that your endpoint is publicly reachable, and that it returns 200. Vision retries deliveries that do not receive a successful response within 10 seconds. For signature verification, retry behavior, and the available event actions, see Webhook Setup, Webhooks, and Webhook Actions.

Next steps