Valuation & Damage Analysis API

Create a new valuation. The valuation is processed asynchronously — poll the returned status_url for the result.

Headers

Header	Required	Description
Idempotency-Key	Optional	Unique key to prevent duplicate submissions on retry. Same key returns the original valuation.

Request Body

Field	Type	Required	Description
reference	string	Optional	Your internal reference (max 100 chars).
source	string	Optional	Origin system or integration name (max 100 chars).
vehicle object
vehicle.mileage	integer	Required	Odometer reading (0–9,999,999).
vehicle.make	string	Optional	Manufacturer (e.g. "Volkswagen").
vehicle.model	string	Optional	Model name (e.g. "Golf").
vehicle.build_year	integer	Optional	4-digit year of manufacture.
vehicle.fuel	enum	Optional	Fuel type enum value.
vehicle.transmission	enum	Optional	Transmission type enum value.
vehicle.body_type	enum	Optional	Body type enum value.
vehicle.mileage_type	enum	Optional	Unit for mileage (km / miles).
vehicle.power_kw	integer	Optional	Engine power in kW.
vehicle.new_price	integer	Optional	Original new price in the smallest currency unit (cents).
vehicle.date_first_admission	date	Optional	First registration date (Y-m-d).
vehicle.vat_margin	enum	Optional	VAT or margin scheme indicator.
vehicle.options	string[]	Optional	List of factory option codes or names.
condition object
condition.general	enum	Optional	Overall condition level.
condition.body	enum	Optional	Body / exterior condition level.
condition.interior	enum	Optional	Interior condition level.
damage object
damage.written_description	string	Optional	Free-text damage description (max 5000 chars).
damage.drivable	boolean	Optional	Whether the vehicle is still drivable.
images array of objects
images[].url	string (URL)	Required	Publicly accessible image URL.
images[].position	string	Optional	Shot position label (e.g. "front-left").
config object
config.mode	enum	Optional	Valuation processing mode.
config.include_comparables	boolean	Optional	Include comparable vehicles in the response.
config.include_image_analysis	boolean	Optional	Run AI image damage analysis.
callback object
callback.url	string (URL)	Required with callback	Webhook URL to POST the result to when completed.
callback.secret	string	Optional	Secret included in the webhook payload for verification.

Response — 202 Accepted

{
  "error": false,
  "message": "Valuation created",
  "data": {
    "uuid": "...",
    "reference": "...",
    "status": "queued",
    "status_url": "/api/valuation/v1/valuations/{uuid}",
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}

Retrieve the status and result of a valuation. Poll this endpoint after creation until status is completed or failed.

Path Parameters

Parameter	Type	Description
uuid	string (UUID)	The UUID returned by the create endpoint.

Response — 200 OK

{
  "data": {
    "uuid": "...",
    "reference": "...",
    "status": "completed",        // queued | processing | completed | failed
    "progress": {
      "current_stage": "...",
      "completed_stages": [...],
      "percent": 100
    },
    "latest_result": {
      "trade_value": 12500,
      "currency": "EUR",
      "range": { "low": 11800, "high": 13200 },
      "confidence": 0.87,
      "review_required": false,
      "market": { ... },
      "adjustments": [...],
      "signals": [...],
      "warnings": [...]
    },
    "comparables": [
      {
        "id": "...",
        "similarity_score": 0.94,
        "comparable_value": 12400,
        "currency": "EUR",
        "vehicle_data": { ... }
      }
    ],
    "stage_outputs": [...],
    "created_at": "...",
    "completed_at": "..."
  }
}

Apply manual price corrections to an existing valuation. Triggers an async recalculation.

Request Body

Field	Type	Required	Description
replace_existing	boolean	Optional	When `true`, removes all existing manual corrections before applying. Defaults to `false`.
corrections array of objects — required, min 1
corrections[].type	enum	Required	Correction type enum value.
corrections[].amount	numeric	Required	Correction value (can be negative for deductions).
corrections[].code	string	Required	Short identifier for this correction (max 100 chars).
corrections[].reason	string	Optional	Human-readable reason (max 500 chars).

Response — 202 Accepted

{
  "error": false,
  "message": "Valuation created",
  "data": {
    "uuid": "...",
    "reference": "...",
    "status": "queued",
    "status_url": "/api/valuation/v1/valuations/{uuid}",
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}

List and filter valuations with pagination support.

Query Parameters

Parameter	Type	Description
status	string	Filter by valuation status (e.g., `completed`, `queued`).
reference	string	Search by reference (partial match, case-insensitive).
page	integer	Page number. Defaults to `1`.

Response — 200 OK

{
  "error": false,
  "message": "Ok",
  "data": [
    {
      "uuid": "...",
      "reference": "...",
      "status": "completed",
      "source": "portal",
      "review_required": false,
      "started_at": "2026-01-01T00:00:00+00:00",
      "completed_at": "2026-01-01T00:05:00+00:00",
      "duration_ms": 300000,
      "created_at": "2026-01-01T00:00:00+00:00",
      "updated_at": "2026-01-01T00:05:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 30,
    "total": 45,
    "from": 1,
    "to": 30
  },
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  }
}

Retrieve the status and result of a valuation. Poll this endpoint after creation until status is completed or failed.

Path Parameters

Parameter	Type	Description
uuid	string (UUID)	The UUID returned by the create endpoint.

Response — 200 OK

{
  "data": {
    "uuid": "...",
    "reference": "...",
    "status": "completed",        // queued | processing | completed | failed
    "progress": {
      "current_stage": "...",
      "completed_stages": [...],
      "percent": 100
    },
    "latest_result": {
      "trade_value": 12500,
      "currency": "EUR",
      "range": { "low": 11800, "high": 13200 },
      "confidence": 0.87,
      "review_required": false,
      "market": { ... },
      "adjustments": [...],
      "signals": [...],
      "warnings": [...]
    },
    "comparables": [
      {
        "id": "...",
        "similarity_score": 0.94,
        "comparable_value": 12400,
        "currency": "EUR",
        "vehicle_data": { ... }
      }
    ],
    "stage_outputs": [...],
    "created_at": "...",
    "completed_at": "..."
  }
}

Trigger a synchronous recalculation of a valuation. Re-runs the full valuation pipeline and returns the updated valuation data.

Path Parameters

Parameter	Type	Description
uuid	string (UUID)	The valuation UUID to recalculate.

Response — 200 OK

{
  "error": false,
  "message": "Valuation recalculated successfully",
  "data": {
    "uuid": "...",
    "reference": "...",
    "status": "completed",
    "current_stage": null,
    "normalized_input": { ... },
    "warnings": [],
    "comparables": [ ... ],
    "latest_result": { ... },
    "stage_outputs": [ ... ],
    "created_at": "2026-01-01T00:00:00+00:00",
    "updated_at": "2026-01-01T00:05:30+00:00"
  }
}

Error Response (500): If recalculation fails, returns {"error": true, "message": "Failed to recalculate valuation: ..."}

Apply manual price corrections to an existing valuation. Triggers an async recalculation.

Request Body

Field	Type	Required	Description
replace_existing	boolean	Optional	When `true`, removes all existing manual corrections before applying. Defaults to `false`.
corrections array of objects — required, min 1
corrections[].type	enum	Required	Correction type enum value.
corrections[].amount	numeric	Required	Correction value (can be negative for deductions).
corrections[].code	string	Required	Short identifier for this correction (max 100 chars).
corrections[].reason	string	Optional	Human-readable reason (max 500 chars).

Response — 202 Accepted

{
  "error": false,
  "message": "Valuation created",
  "data": {
    "uuid": "...",
    "reference": "...",
    "status": "queued",
    "status_url": "/api/valuation/v1/valuations/{uuid}",
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}

Record outcome feedback for a valuation (realized sale price, days to sale, etc.). Used to improve future model accuracy.

Request Body

Field	Type	Required	Description
realized_value	integer	Optional	Actual sale price achieved.
currency	string (ISO 4217)	Optional	3-letter currency code (e.g. "EUR").
sold	boolean	Optional	Whether the vehicle was sold.
sold_at	date	Required if sold	Date of sale.
days_to_sale	integer	Optional	Number of days from listing to sale.
notes	string	Optional	Free-text notes (max 2000 chars).
used_for_training	boolean	Optional	Consent to use this feedback for model training.

Response — 200 OK

{
  "error": false,
  "message": "Feedback recorded",
  "data": {
    "uuid": "..."
  }
}

Submit images for AI-powered damage analysis. Supports file uploads or public image URLs. Analysis is processed asynchronously — poll the returned status_url for results.

Request Body

Field	Type	Required	Description
input_mode	string	Optional	Input method: `files` or `urls`. Defaults to `files`.
File Upload Mode (input_mode=files)
images	file[]	Required*	Array of 1-10 image files (max 10MB each). Supported formats: jpg, jpeg, png, webp, gif.
URL Mode (input_mode=urls)
image_urls	string[]	Required*	Array of 1-10 publicly accessible image URLs (max 2048 chars each).

* Required when the corresponding input_mode is selected. Either images or image_urls must be provided.

Response — 202 Accepted

{
  "error": false,
  "message": "Damage analysis created",
  "data": {
    "uuid": "...",
    "status": "queued",
    "status_url": "/api/damage-analysis/v1/damage-analysis/{uuid}",
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}

Retrieve the status and results of a damage analysis. Poll this endpoint after creation until status is completed or failed.

Path Parameters

Parameter	Type	Description
uuid	string (UUID)	The UUID returned by the create endpoint.

Response — 200 OK

{
  "data": {
    "uuid": "...",
    "status": "completed",        // queued | processing | completed | failed
    "progress": {                 // Present when status is queued or processing
      "status": "queued",
      "queued_at": "2026-01-01T00:00:00+00:00"
    },
    "results": {                  // Present when status is completed
      "overall_condition_score": 0.85,
      "detected_damages": ["scratch", "dent"],
      "warnings": [],
      "image_signals": [
        {
          "image_url": "https://...",
          "confidence": 0.92,
          "condition_score": 0.85,
          "detected_damages": ["scratch"],
          "description": "Minor scratch visible on rear bumper",
          "damage_boxes": [
            {
              "x": 0.65,
              "y": 0.42,
              "width": 0.15,
              "height": 0.08,
              "damage_type": "scratch",
              "confidence": 0.88
            }
          ]
        }
      ]
    },
    "error": {                    // Present when status is failed
      "message": "AI service unavailable",
      "failed_at": "2026-01-01T00:00:00+00:00"
    },
    "created_at": "...",
    "queued_at": "...",
    "completed_at": "...",
    "failed_at": "..."
  }
}

List and filter damage analyses with pagination support.

Query Parameters

Parameter	Type	Description
status	string	Filter by status: `queued`, `processing`, `completed`, or `failed`.
sort	string	Sort field: `created_at`, `completed_at`, or `queued_at`. Defaults to `created_at`.
direction	string	Sort direction: `asc` or `desc`. Defaults to `desc`.
per_page	integer	Results per page (1-100). Defaults to `15`.
page	integer	Page number. Defaults to `1`.

Response — 200 OK

{
  "data": [...],              // Array of damage analysis objects
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 150,
    "last_page": 10
  },
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  }
}

Retry a failed damage analysis. Resets error state and re-queues the job for processing.

Response — 202 Accepted

{
  "error": false,
  "message": "Damage analysis created",
  "data": {
    "uuid": "...",
    "status": "queued",
    "status_url": "/api/damage-analysis/v1/damage-analysis/{uuid}",
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}

Error Response (400): Only analyses with status failed can be retried. Returns {"error": true, "message": "Only failed analyses can be retried"} for other statuses.

Valuation & Damage Analysis API

Valuation API

Headers

Request Body

Response — 202 Accepted

Path Parameters

Response — 200 OK

Request Body

Response — 202 Accepted

Query Parameters

Response — 200 OK

Path Parameters

Response — 200 OK

Path Parameters

Response — 200 OK

Request Body

Response — 202 Accepted

Request Body

Response — 200 OK

Damage Analysis API

Request Body

Response — 202 Accepted

Path Parameters

Response — 200 OK

Query Parameters

Response — 200 OK

Response — 202 Accepted