Skip to main content
POST
/
inspections
Submit Inspection
curl --request POST \
  --url https://api.inspecto.com/api/third-party/v1/inspections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "templateId": "<string>",
  "vehicleIds": [
    {}
  ],
  "responses": [
    {
      "templateItemId": "<string>",
      "responseText": "<string>",
      "fileUrl": "<string>",
      "followUpResponses": {}
    }
  ],
  "damages": [
    {
      "description": "<string>",
      "photoUrl": "<string>"
    }
  ],
  "notes": "<string>",
  "location": {
    "latitude": 123,
    "longitude": 123,
    "title": "<string>"
  }
}
'
{
  "data": {
    "id": "<string>",
    "templateId": "<string>",
    "status": "<string>",
    "performedAt": "<string>",
    "trackingId": "<string>",
    "vehicles": [
      {}
    ]
  }
}

​
Endpoint

POST /api/third-party/v1/inspections

​
Authentication

Requires inspections:write scope.

​
Request Body

​
templateId
string
required
ID of the inspection template to use (UUID)
​
vehicleIds
array
required
Array of vehicle IDs to inspect (min: 1)
​
responses
array
required
Array of inspection item responses
​
damages
array
Array of damage reports (optional)
​
notes
string
Additional inspection notes
​
location
object
Inspection location (optional)

​
Response

​
data
object
Created inspection object

​
Example Request

curl -X POST "https://api.inspecto.com/api/third-party/v1/inspections" \
  -H "Authorization: Bearer insp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "vehicleIds": ["550e8400-e29b-41d4-a716-446655440000"],
    "responses": [
      {
        "templateItemId": "item-001",
        "responseText": "true"
      },
      {
        "templateItemId": "item-002",
        "responseText": "Good"
      }
    ],
    "damages": [
      {
        "description": "Small scratch on driver door",
        "photoUrl": "https://storage.example.com/damage-123.jpg"
      }
    ],
    "notes": "Pre-trip inspection completed",
    "location": {
      "latitude": 52.2297,
      "longitude": 21.0122,
      "title": "Warsaw Depot"
    }
  }'

​
Example Response

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "templateId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "status": "COMPLETED",
    "performedAt": "2024-12-09T15:30:00Z",
    "trackingId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "vehicles": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "plateNumber": "ABC-1234"
      }
    ]
  },
  "meta": {
    "version": "v1",
    "message": "Inspection submitted successfully"
  }
}

​
Error Responses

{
  "errors": [{
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "field": "vehicleIds",
      "issue": "Must be a non-empty array"
    }
  }]
}

{
  "errors": [{
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": {
      "required": ["inspections:write"],
      "available": ["inspections:read"]
    }
  }]
}

​
File Uploads

File uploads (photos, signatures) should be handled separately. Upload files to your storage service first, then include the URLs in the inspection submission.
  1. Upload file to your storage (S3, CloudFlare, etc.)
  2. Get the public URL
  3. Include URL in fileUrl or photoUrl fields
  4. Submit inspection with URLs
// 1. Upload file
const fileUrl = await uploadToStorage(file);

// 2. Submit inspection with URL
const inspection = await client.post('/inspections', {
  // ...
  responses: [
    {
      templateItemId: 'photo-item',
      fileUrl: fileUrl
    }
  ]
});

​
Best Practices

Validate Before Submit

Validate all required fields client-side before submission

Handle Async Processing

Large inspections may be processed asynchronously

Store Tracking ID

Save the tracking ID for status checks

Retry on Failure

Implement retry logic for transient errors