Export inspection PDFs

Generate an inspection PDF with one export request by calling either GET /v3/inspections/{inspectionId}/export or POST /v3/inspections/{inspectionId}/export.

Before you start

1. Get the inspection ID for the inspection you want to export.
2. Set your Vision API base URL, such as https://vision-api.truepic.com/v3.
3. Send requests with your Bearer token.
4. Choose the request style that matches your integration:
   • Use GET for the shortest request when you are testing or exporting a smaller PDF.
   • Use POST when you need to send more export options in a JSON request body.
   • Add async export when your workflow can poll an operation or receive webhook events.

1. Choose GET or POST

👍

If your integration can support polling or webhooks, queue the PDF asynchronously. Use async=1 with GET or "async": true with POST, especially for large PDFs because synchronous requests time out after 2 minutes.

2. Configure the PDF export

Both export endpoints support the same export options. With GET, pass them as query parameters. With POST, pass the same fields in the JSON request body.

For array options:

• With GET, pass include[] and exclude[] as query parameters.
• With POST, send include and exclude as JSON arrays.
• If you need to send several array values or nested filter data, prefer POST so you do not run into URL length limits.

Here is an example POST body that uses the shared export options:

{
  "async": true,
  "filter": {
    "photos": [123, 456]
  },
  "include": ["inspectionNote"],
  "exclude": ["timeline", "thumbnails"],
  "tz": "America/New_York"
}

Optional: Queue the export asynchronously

Use async export when your integration can poll an operation or receive webhook events. Async export returns an Operation (an object that tracks background work) and lets the worker fleet generate the PDF instead of application servers.

Use this option for large PDFs because synchronous requests time out after 2 minutes.

With POST, queue the export by setting async to true in the JSON request body:

curl --request POST \
  --url 'https://vision-api.truepic.com/v3/inspections/{inspectionId}/export' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "async": true,
    "filter": {
      "photos": [123, 456]
    },
    "include": ["inspectionNote"],
    "exclude": ["timeline", "thumbnails"],
    "tz": "America/New_York"
  }'

What success looks like

• 202 Accepted
• The export job is queued instead of completed inline
• The response body includes an operation you can track

Save the returned operation ID from the 202 response. You will use that ID to poll the operation status.

You can also queue an async export with GET by setting async=1 in the query string:

curl --request GET \
  --url 'https://vision-api.truepic.com/v3/inspections/{inspectionId}/export?async=1' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'

Optional: Export synchronously

Use synchronous export when you want the PDF returned directly in the response and you expect the export to finish in under 2 minutes.

This is the easiest way to test PDF export, but large PDFs can time out because synchronous generation runs on application servers. Use this pattern for smaller exports or quick manual checks.

curl --request GET \
  --url 'https://vision-api.truepic.com/v3/inspections/{inspectionId}/export' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/pdf' \
  --output inspection-{inspectionId}.pdf

If you want to queue the GET request instead of returning the PDF inline, add async=1 to the query string and expect an Operation response instead of a PDF.

What success looks like

• 200 OK when the export runs synchronously
• 202 Accepted when you set async=1
• The response body is either the generated PDF (200) or an operation you can track (202)

Optional: Poll the operation until it finishes

After an async export request returns an operation ID, poll GET /v3/operations/{operationId} to track progress. This applies whether you started the export with POST and "async": true or with GET and async=1.

curl --request GET \
  --url 'https://vision-api.truepic.com/v3/operations/{operationId}' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'

Repeat that request until the operation indicates it has completed or failed. In most integrations, polling every few seconds is enough.

Polling flow

1. Send POST /v3/inspections/{inspectionId}/export with "async": true, or send GET /v3/inspections/{inspectionId}/export?async=1.
2. Read the returned operation ID from the 202 Accepted response.
3. Call GET /v3/operations/{operationId} on a short interval.
4. Stop polling when the operation shows completion or failure.
5. If the operation succeeds, retrieve the finished PDF using the data returned by the completed operation.
6. If the operation fails, log the failure and retry or surface the error to your team.

Do not hold open a single long-running export request while waiting for a large PDF. Synchronous requests time out after 2 minutes. Queue the export, poll the operation, and complete the workflow after the background job finishes.

Optional: Use webhooks instead of polling

If your integration already receives webhooks, you can track PDF generation through webhook events instead of relying only on polling:

• ACTION_PDF_READY
• ACTION_PDF_FAILED

Use polling when you need an immediate request-response workflow. Use webhooks when you want your system to react after the export finishes without repeatedly calling the operations endpoint.

Troubleshooting

The export request times out

Queue the export asynchronously. Use POST /v3/inspections/{inspectionId}/export with "async": true, or use GET /v3/inspections/{inspectionId}/export?async=1. This is required for large PDFs because synchronous requests time out after 2 minutes.

The export request returns 202 Accepted

That means the export was queued successfully. Read the operation ID from the response and poll GET /v3/operations/{operationId} until it completes.

The API returns 400

Check the request body or query parameters. This usually means the export options could not be parsed. For GET, verify your query parameters, especially array values and nested filter data. For POST, verify the JSON body shape.

The API returns 401 or 403

Verify the Bearer token and make sure the calling client has permission to access that inspection.

The API returns 404

Confirm that the inspection ID or operation ID exists and belongs to the right environment.

The API returns 412

Check for a missing required parameter or property.

API reference

• Export a PDF of an inspection (GET)
• Export a PDF of an inspection (POST)
• Get an existing operation to track its progress
• Webhook Actions