Vehicle Monitoring

Subscribe to vehicle lifecycle events. Gemmai notifies you via webhook the moment a monitored vehicle is listed for sale or changes ownership.

Monitorings are identified by licence plate. Each monitoring can subscribe to one or more event types. When an event is detected, Gemmai delivers a POST to your configured webhook endpoint.

Requires API key scope vehicles.

Event types

Value	Trigger
`listed_for_sale`	The vehicle has appeared in a car-ad listing.
`ownership_change`	The vehicle's registered owner has changed.

List monitorings

`GET /v1/vehicles/se/monitorings`

Returns a paginated list of monitorings registered under your account.

Query parameters:

Name
limit
Type
number
Description
Maximum number of results to return. Defaults to 100, maximum 100.
Name
offset
Type
number
Description
Number of results to skip. Defaults to 0.

Request

GET /v1/vehicles/se/monitorings?limit=10&offset=0

Response (200)

{
  "data": [
    {
      "monitorId": "3f2e1a4b-...",
      "accountId": "acct_...",
      "licensePlate": "ABC123",
      "vin": null,
      "eventTypes": ["listed_for_sale", "ownership_change"],
      "createdAt": "2026-05-01T09:00:00.000Z"
    }
  ],
  "limit": 10,
  "offset": 0
}

Create a monitoring

`POST /v1/vehicles/se/monitorings`

Creates a monitoring for a vehicle. If a monitoring already exists for the same licence plate under your account it is updated with the new eventTypes.

Request body:

Name
licensePlate
Type
string
Description
The vehicle licence plate to monitor.
Name
eventTypes
Type
string[]
Description
One or more event types to subscribe to. At least one required. See event types for available values.
Name
metadata
Type
object
Description
Arbitrary key-value data you want to attach to this monitoring, e.g. your internal customer or loan ID. Returned as-is on all read and webhook responses.

Request body

{
  "licensePlate": "ABC123",
  "eventTypes": ["listed_for_sale", "ownership_change"],
  "metadata": { "customerId": "cust_9f3kd82", "loanId": "loan_4m2np91" }
}

Response (201)

{
  "monitorId": "3f2e1a4b-...",
  "accountId": "acct_...",
  "licensePlate": "ABC123",
  "vin": null,
  "eventTypes": ["listed_for_sale", "ownership_change"],
  "metadata": { "customerId": "cust_9f3kd82", "loanId": "loan_4m2np91" },
  "createdAt": "2026-05-01T09:00:00.000Z"
}

Get a monitoring

`GET /v1/vehicles/se/monitorings/:licensePlate`

Fetch a single monitoring by licence plate.

Path parameters:

Name
:licensePlate
Type
string
Description
The licence plate of the monitoring to fetch.

Request

GET /v1/vehicles/se/monitorings/ABC123

Response (200)

{
  "monitorId": "3f2e1a4b-...",
  "accountId": "acct_...",
  "licensePlate": "ABC123",
  "vin": null,
  "eventTypes": ["listed_for_sale"],
  "createdAt": "2026-05-01T09:00:00.000Z"
}

Response (404)

{ "error": "Monitor not found" }

Update a monitoring

`PATCH /v1/vehicles/se/monitorings/:licensePlate`

Update the event types on an existing monitoring. Replaces the full eventTypes array.

Path parameters:

Name
:licensePlate
Type
string
Description
The licence plate of the monitoring to update.

Request body:

Name
eventTypes
Type
string[]
Description
Replaces the current event type subscriptions.
Name
metadata
Type
object
Description
Replaces the attached metadata object.

Request body

{
  "eventTypes": ["ownership_change"]
}

Response (200)

{
  "monitorId": "3f2e1a4b-...",
  "accountId": "acct_...",
  "licensePlate": "ABC123",
  "vin": null,
  "eventTypes": ["ownership_change"],
  "createdAt": "2026-05-01T09:00:00.000Z"
}

Delete a monitoring

`DELETE /v1/vehicles/se/monitorings/:licensePlate`

Permanently removes a monitoring. No further webhook events will be delivered for this vehicle.

Path parameters:

Name
:licensePlate
Type
string
Description
The licence plate of the monitoring to delete.

Request

DELETE /v1/vehicles/se/monitorings/ABC123

Response (204 No Content)

# No response body

Response (404)

{ "error": "Monitor not found" }

Webhook events

When an event is detected for a monitored vehicle, Gemmai sends a POST to your webhook endpoint with the following payload.

Event types:

`type`	Trigger
`listed_for_sale`	The vehicle has appeared in a car-ad listing.
`ownership_change`	The vehicle's registered owner has changed.

Payload fields:

Name
eventType
Type
string
Description
vehicle.<type>, e.g. vehicle.listed_for_sale.
Name
occurredAt
Type
string
Description
ISO 8601 timestamp of when the event was detected.
Name
data.licensePlate
Type
string
Description
The monitored licence plate.
Name
data.vin
Type
string
Description
VIN, if available.
Name
data.pageUrl
Type
string
Description
URL of the listing. Present for listed_for_sale events.
Name
data.price
Type
number
Description
Listed price. Present for listed_for_sale events, if available.
Name
data.currency
Type
string
Description
ISO 4217 currency code. Present for listed_for_sale events, if available.

listed_for_sale event

{
  "eventType": "vehicle.listed_for_sale",
  "occurredAt": "2026-05-22T14:03:11.000Z",
  "data": {
    "licensePlate": "ABC123",
    "vin": "YV1BW9120S1234567",
    "pageUrl": "https://www.blocket.se/annons/...",
    "price": 129000,
    "currency": "SEK"
  }
}

ownership_change event

{
  "eventType": "vehicle.ownership_change",
  "occurredAt": "2026-05-22T14:03:11.000Z",
  "data": {
    "licensePlate": "ABC123",
    "vin": "YV1BW9120S1234567"
  }
}