Export inspection PDFs

Export an inspection PDF by choosing shared export options and then calling either the direct GET /v3/inspections/{inspectionId}/export endpoint or the recommended asynchronous POST /v3/inspections/{inspectionId}/export workflow.

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 your export pattern:
   • Use POST when you want the recommended production workflow or need to send more export options.
   • Use GET when you want the shortest request for quick testing or smaller exports.

1. Choose your export pattern

Prefer POST /v3/inspections/{inspectionId}/export with "async": true for new integrations. It is easier on the system and avoids large synchronous exports timing out.

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"
}

3. Recommended: Export with POST asynchronously

Use POST /v3/inspections/{inspectionId}/export when you want the recommended production flow. This endpoint supports the same export behavior as GET, but it sends options in the request body instead of the URL and is better suited for larger payloads.

To avoid timeouts, queue the export by setting async to true. The API returns an Operation (an object that tracks background work) instead of the PDF itself.

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.

Optional: Export with GET

Use GET /v3/inspections/{inspectionId}/export when you want the simplest request flow. In the synchronous pattern, the API returns the PDF directly in the response.

This is the easiest way to test PDF export, but large PDFs and long query strings can cause problems. 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)

4. 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.

Recommended polling flow

1. Send POST /v3/inspections/{inspectionId}/export with "async": true.
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. 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 GET request times out

Switch to POST /v3/inspections/{inspectionId}/export with "async": true. This is the recommended fix for larger PDFs.

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