Developers

Konvoi Partner API

Async document processing with smart classification and multi-document splitting, plus fleet data: vehicles, users, assignments, inspections and incidents, over a REST API with scoped tokens and signed webhooks.

On requestThe Partner API is enabled per workspace on request.

Download the OpenAPI specification MCP server for AI clients

What the Partner API does

Send any fleet document and get structured data back, keep vehicles and assignments in step with your own systems, and read inspections, incidents and vehicle positions.

Document processing: Upload fines, registrations, invoices, fuel receipts or insurance certificates and get structured data back.
Fleet sync: Create and update vehicles and assignments from your own fleet system, with your external IDs.
Users and drivers: Create and manage driver records with external ID mapping.
Workflow automation: Feed documents in from n8n or your own workflows, and react to webhooks.

Authentication

01Get access. Ask us to enable the Partner API for your workspace.
02Create a token. In Konvoi, open the Partner API settings and create a token with the scopes you need.
03Send it. Put the token in the Authorization header of every request.

Scopes

documents:read · documents:write	Upload, split and process documents; poll for results
vehicles:read · vehicles:write	Vehicles and their documents
assignments:read · assignments:write	Driver ↔ vehicle assignments
users:read · users:write	Users and drivers
fines:read · fines:write	Fines
inspections:read · inspections:write	Inspections, photos and analysis
incidents:read · incidents:write	Incidents and their photos
webhooks:read · webhooks:write	Webhook endpoints and deliveries
telemetry:read	Vehicle trail and geofence queries (read only)

First request

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://konvoi.ai/api/partner/v1/health

Examples

Upload and process a document

Processing is asynchronous: upload a document, then poll for the result. It works for any document type; Konvoi classifies it and extracts the fields.

curl -X POST https://konvoi.ai/api/partner/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document": "<base64-encoded-pdf>", "filename": "scan.pdf"}'

# → {"success": true, "id": "clx1abc2300001234", "status": "processing", "filename": "scan.pdf"}

Poll until the status is processed:

curl https://konvoi.ai/api/partner/v1/documents/clx1abc2300001234 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": "clx1abc2300001234",
  "status": "processed",
  "documentClass": "FINE",
  "classificationConfidence": 0.95,
  "data": {
    "referenceNumber": "PV-2024-12345",
    "amount": 58.00,
    "currency": "EUR",
    "type": "SPEEDING",
    "licensePlate": "1-ABC-123",
    "violationAddress": "Kortrijksesteenweg 123",
    "issuerName": "Politiezone Gent"
  }
}

Multipart upload

For large files, send multipart/form-data and skip the base64 overhead.

curl -X POST https://konvoi.ai/api/partner/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

A PDF with several documents

When a PDF holds several documents, the API proposes segments and waits. Adjust them if needed, then confirm the split.

# Polling returns the proposed segments
GET  /v1/documents/:id          → {"status": "awaiting_split", "segments": [...]}

# Optionally adjust them
PATCH /v1/documents/:id/segments

# Confirm: each segment becomes its own document
POST /v1/documents/:id/split    → {"success": true, "status": "splitting"}

Vehicles

Create vehicles with your own external ID, and search by plate.

curl -X POST https://konvoi.ai/api/partner/v1/vehicles \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vin": "WVWZZZ3CZWE123456", "make": "Volkswagen", "model": "Golf",
       "year": 2023, "type": "CAR", "externalId": "fleet_vehicle_001"}'

curl "https://konvoi.ai/api/partner/v1/vehicles?search=1-ABC-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Webhooks

Register up to five endpoints per workspace. Each delivery is a POST signed with HMAC-SHA256; check the signature before you trust the body. Send a test ping and see every delivery in the log.

Headers

X-Konvoi-Signature: sha256=<HMAC-SHA256 of the body>
X-Konvoi-Event: inspection.completed
X-Konvoi-Delivery-Id: <unique id>
X-Konvoi-Timestamp: <unix time>

Events

inspection.created
inspection.completed
inspection.analyzed
inspection.deleted
damage_check.completed
incident.created
incident.updated
incident.resolved
incident.closed
incident.deleted
vehicle.created
vehicle.updated
vehicle_document.created
vehicle_document.deleted
document.processed
document.failed
document.split_complete
fine.created
fine.assigned
assignment.created
assignment.ended

Best practices

Use external IDs to keep links with your source systems.
Retry with exponential backoff on errors.
Give each token only the scopes it needs.
Rotate tokens regularly.
Verify the webhook signature and timestamp before acting on a delivery.

Need help?

We help you plan and test your integration.

Contact API support