Partner API

Submit vehicle inspection orders programmatically and receive results via webhook the moment a report is ready. No login, no dashboard — your platform stays in control end-to-end.

Base URL

https://inspecteam.ca/api/v1/

All requests and responses use JSON. Set Content-Type: application/json on every request.

Authentication

Every request must include your API key in the X-Api-Key header. Keys are partner-specific and scoped to your slug.

HTTP Header

X-Api-Key: your_api_key_here

A missing or invalid key returns 401 Unauthorized. Keys are managed by Inspecteam — contact us if you need a key rotated.

Create Order

POST

/api/v1/partner/{your-slug}/orders/

Submits a vehicle for inspection. The order is created in paid status immediately — payment is assumed handled on your side. Inspector dispatch begins automatically.

Example request

curl

curl -X POST https://inspecteam.ca/api/v1/partner/your-slug/orders/ \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "auction_id": "LOT-2024-8812",
    "vehicle_vin": "1HGBH41JXMN109186",
    "vehicle_make": "Honda",
    "vehicle_model": "Civic",
    "vehicle_year": 2021,
    "location": {
      "address": "123 Lakeshore Blvd W, Toronto, ON M6K 1A1"
    },
    "buyer": {
      "name": "Sarah Nguyen",
      "email": "sarah@example.com",
      "phone": "4165551234"
    }
  }'

Request Body

Top-level fields

Field	Type	Description
auction_idrequired	string	Your lot or auction identifier. Used for idempotency — submitting the same `auction_id` twice returns the existing order.
vehicle_vinrequired	string	17-character VIN.
vehicle_makerequired	string	Manufacturer, e.g. `"Toyota"`.
vehicle_modelrequired	string	Model name, e.g. `"Camry"`.
vehicle_yearrequired	integer	Four-digit model year.
locationrequired	object	Where the vehicle is located. See below.
buyerrequired	object	Person who ordered the inspection. The completed report is emailed here.
selleroptional	object	Seller contact details — stored for reference, not contacted by Inspecteam.
admin_emailoptional	string	An additional email address to CC on the delivered report.

location object

Field	Type	Description
addressrequired	string	Full street address including city and province, e.g. `"123 Main St, Toronto, ON M5V 2T6"`.
latitudeoptional	number	Decimal degrees. If provided alongside `longitude`, geocoding is skipped.
longitudeoptional	number	Decimal degrees.

buyer / seller object

Field	Type	Description
namerequired (buyer)	string	Full name.
emailrequired (buyer)	string	Report delivery address.
phoneoptional	string	Digits only, no formatting required.

Responses

201 Created

Order successfully created and inspector dispatch initiated.

JSON

{
  "order_number": "INS-2026-A4F2B1",
  "order_id":     "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status":       "paid",
  "message":      "Order created. Inspector dispatch initiated."
}

400 Bad Request

One or more required fields are missing.

JSON

{
  "error": "Missing required fields: buyer.email, vehicle_vin"
}

401 Unauthorized

JSON

{
  "error": "Invalid or missing API key."
}

Idempotency

Submitting the same auction_id for your partner account twice returns the existing order with a 200 status instead of creating a duplicate.

200 OK

JSON

{
  "order_number": "INS-2026-A4F2B1",
  "order_id":     "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status":       "paid",
  "detail":       "Order already exists for this auction_id."
}

Webhooks

When an inspection report is ready, Inspecteam posts a report.completed event to your configured webhook URL. Configure your endpoint and signing secret when requesting access.

X-Inspecteam-Event: report.completed

Delivery is attempted up to 3 times with 60-second delays on failure. Your endpoint should return any 2xx status to acknowledge receipt.

Webhook Payload

POST your-webhook-url

{
  "auction_id":    "LOT-2024-8812",       // your original auction_id
  "order_number":  "INS-2026-A4F2B1",
  "order_id":      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status":        "completed",
  "overall_score": "87.50",             // null if scoring unavailable
  "report_url":    "https://...",          // signed S3 URL, valid 7 days
  "inspector": {
    "name":  "James Okafor",
    "level": 2
  },
  "completed_at":  "2026-09-19T14:32:00+00:00"
}

Webhook headers

Header	Description
X-Inspecteam-Event	`report.completed`
X-Inspecteam-Order	The order number, e.g. `INS-2026-A4F2B1`
X-Inspecteam-Signature	HMAC-SHA256 signature — see below. Only sent if you have a webhook secret configured.
Content-Type	`application/json`

Verifying Signatures

When a webhook secret is configured, every delivery includes an X-Inspecteam-Signature header. Verify it to confirm the payload came from Inspecteam and was not tampered with.

Read the raw request body as bytes — before JSON-parsing it.
Compute HMAC-SHA256(secret, body) using your webhook secret.
Compare your result (prefixed with sha256=) against the header value using a constant-time comparison.

Python example

Python

# Django / Flask view — raw_body is bytes
import hashlib, hmac

def verify_signature(raw_body: bytes, secret: str, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

# Usage:
sig = request.headers.get("X-Inspecteam-Signature", "")
if not verify_signature(request.body, WEBHOOK_SECRET, sig):
    return HttpResponse(status=401)

Node.js example

JavaScript

const crypto = require('crypto');

function verifySignature(rawBody, secret, header) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header)
  );
}