API docs by Redocly

API Documentation (1.0)

Download OpenAPI specification:

Photos

Sort

header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": [
    ]
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ]
}

Vehicles Integration

Show Vehicle

path Parameters
id
number
Example: 1
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token a7hKrsj3DcdMf9hoEHhg
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": {
    }
}

Update Vehicle

path Parameters
id
number
Example: 21
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token gxjZvA3HQ-vkM9qMy3sH
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "status": "reserved",
  • "nameplate_id": 21,
  • "owner_id": 104,
  • "color_id": 28,
  • "power": 237,
  • "msrp_price": "41707.0",
  • "base_price": null,
  • "features_optional": null,
  • "id": 21,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2016,
  • "created_at": "2025-04-01T07:57:51.171Z",
  • "updated_at": "2025-04-01T07:57:51.171Z",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "new",
  • "delivery_date": "2025-04-05",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 526081,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "video_url": null,
  • "features_standard": null,
  • "model_year": null,
  • "external_id": "8099f1",
  • "interior_color": "Ebony",
  • "created_by": null,
  • "price_hidden": false,
  • "prices_type": null,
  • "model_code": null,
  • "footnote": "Deserunt est aut iure et enim rem nobis natus consectetur.",
  • "config_url": null,
  • "subscribe_price": null,
  • "vehicle_batch_upload_id": null,
  • "order_number": null,
  • "metadata": null,
  • "locked_until": null,
  • "lock_id": null,
  • "code5000": null,
  • "price_metadata": { },
  • "manual_update_attributes": [ ],
  • "disclaimers": { },
  • "price_breakdown": false,
  • "total_price": null,
  • "published_at": null,
  • "number_of_seats": null
}

Lock vehicle temporarily

Action is used to lock vehicle after successful booking. It locks vehicle for 15 minutes in order to enable user completing the booking payment. In response it returns lock_id, which can be further used to perform acquire action to permanently reserve or mark vehicle as sold.

Request Path

PUT /integration_api/buy_online/vehicles/:id/lock

Request Header

Authorization: "Bearer {dealer authorization token}"

Request Body Structure

param example type required description
id 2 integer yes (in request path) Id of the vehicle in StockLocator

Response

Request response is JSON. Vehicle details are returned under data, while booking details (lock_id and locked_until) are returned under meta > lock_data.

When vehicle is not found, 404 status is returned.

When lock cannot be performed (because vehicle has reserved or sold status or it has already been locked), 422 status is returned.

path Parameters
id
number
Example: 4
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token _JczHK4LEMQmza_v-8mi
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": {
    },
  • "meta": {
    }
}

Cancel vehicle lock

Cancel vehicle lock [PUT /integration_api/buy_online/vehicles/{id}/unlock/{lock_id}]

Action is used to unlock soft-locked vehicle. By providing vehicle id and its lock_id lock can be cancelled before expiration time.

Request Path

PUT /integration_api/buy_online/vehicles/:id/unlock/:lock_id

Request Header

Authorization: "Bearer {dealer authorization token}"

Request Body Structure

param example type required description
id 2 integer yes (in request path) Id of the vehicle in StockLocator
lock_id 44c2 string yes (in request path) Lock ID of the vehicle

Response

Request response is JSON. Vehicle details are returned under data.

When vehicle is not found or is not locked, 404 status is returned.

When unlock fails, 422 status is returned.

  • Parameters

    • id: 10 (number, required)
    • lock_id: lock-id (string, required)

  • Request returns 200 status when vehicle with lock_id is found

path Parameters
id
number
Example: 11
lock_id
string
Example: lock-id
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token zrq5TinFnvN2xc9Tzybx
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": {
    }
}

Set vehicle status to reserved or sold

Action is used to permanently reserve or mark vehicle as sold. It is verified by lock id provided by lock action and optionally removes vehicle from all listings.

Request Path

PUT /integration_api/buy_online/vehicles/:id/acquire

Request Header

Authorization: "Bearer {dealer authorization token}"

Request Body Structure

param example type required description
id 2 integer yes (in request path) Id of the vehicle in StockLocator
status reserved string yes requested status, possible values are reserved and sold
lock_id 12ab string yes if vehicle has lock_id attr used to check lock identity, if vehicle has matching lock_id, lock is overridden and status is changed
remove_listings true boolean no when set to true vehicle is removed from all listings

Response

Request response is JSON. Vehicle details are returned under data key.

When vehicle is not found, 404 status is returned.

When lock cannot be performed (when status param is invalid or lock ids don't match), 422 status is returned.

path Parameters
id
number
Example: 16
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token sLt7a4L1ofF76GDuSAGH
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Authentication

Authentication for integration API

Authentication is implemented using the HTTP Bearer token.

Every request needs to include that token.

Example Authorization: Token abc123 - where abc123 is the token value.

header Parameters
Accept
any
Example: application/json
Content-Type
any
Example: application/json
Authorization
any
Example: Token 5ESMrk3uttnZd_4nz1ps
Request Body schema:
Schema not provided

Responses

Request samples

Content type
{
  • "vehicle": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 26,
  • "nameplate_id": 32,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2016,
  • "created_at": "2025-04-01T07:57:51.689Z",
  • "updated_at": "2025-04-01T07:57:51.697Z",
  • "msrp_price": "36144.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "approved",
  • "status": "delivery",
  • "delivery_date": "2025-04-30",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 450249,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 238,
  • "video_url": null,
  • "owner_id": 117,
  • "color_id": 40,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "36a450",
  • "interior_color": "Ebony",
  • "created_by": null,
  • "price_hidden": false,
  • "prices_type": null,
  • "model_code": null,
  • "footnote": null,
  • "config_url": null,
  • "subscribe_price": null,
  • "vehicle_batch_upload_id": null,
  • "order_number": null,
  • "metadata": {
    },
  • "locked_until": null,
  • "lock_id": null,
  • "code5000": null,
  • "price_metadata": { },
  • "manual_update_attributes": [ ],
  • "disclaimers": { },
  • "price_breakdown": false,
  • "base_price": null,
  • "total_price": null,
  • "published_at": null,
  • "number_of_seats": null
}

Create or Update a Vehicle

This endpoint allows you to create or update a vehicle in the Stock Locator system. For vehicle creation, you need to provide a set of required attributes (described below) but there are some extra, non-obligatory attributes which may be worth filling in to keep the vehicle description as complete as possible. For vehicle update, the attributes marked as required are no longer required - if they are not provided, the Stock Locator application assumes that they don't have to be updated.

One attribute which is important in this API is external_id - in general it is optional in the Stock Locator system, however in this API you should consider it as required. This attribute allows you to set an ID (you should set your own value or use value from your stock management system). The external_id is later used to identify a vehicle you may want to update od remove from the system.

Vehicle parameters (required for vehicle creation)

param example type description
color_name 'Eiger Grey' string See /colors endpoint for available colors. You can alternatively pass 'color_id' instead of the ID of the Color
nameplate_name 'F-Pace' string See /nameplates endpoint for available nameplates. You can alternatively pass nameplate_id instead with the ID of the Nameplate
version 'HSE' string Version/Trim Level name/description
drivetrain 'P300 AWD' string Drivetrain (Engine, gearbox etc) description
state 'new' enum Vehicle state. New, User or Approved
status 'stock' enum Stock status of the Vehicle
transmission 'auto' enum type of transmission, auto by default
mileage 123000 number vehicle mileage in ower company units
engine_type ['petrol', 'mhev'] array kind of engine, as a strings array
production_year 2020 integer Year when vehicle was manufacturedd
msrp_price 123000 decimal(18,2) Retailer price
external_id 'abd-3345' string External ID (of your choice) for the vehicle. Required to allow vehicle update/removal

Vehicle parameters (optional)

param example type description
short_description 'Lorem ipsum' string Short description paragraph
sale_price 120000 decimal(18,2) Sale Price
monthly_price 2500.01 decimal(18,2) Monthly price
subscribe_price 2700.00 decimal(18,2) Subscribe price
long_description 'Lorem ...' string Full description copy (potentialy HTML)
delivery_date 2020-02-02 date Date of delivery
vin 'XXX' string Vehicle Vin number
engine_capacity 1999 number engine capacity in ccm
battery_capacity 2020 number battery capacity in owner company units
power 200 number vehicle power in owner company units
video_url 'https://youtu.be/bJqimfimHjE' string youtube video url
photos ['http://site.com/1.png'] array photos url (first photo will become a cover photo)
attachment 'http://example.com/file.pdf' string attachment link
features_standard [{"code": "S1", "label": "Label1"}, ...] [Feature] array of Feature-type objects, described below
features_optional [{"code": "O1", "label": "Label2"}, ...] [Feature] array of Feature-type objects, described below
interior_color 'Snow white' string interior color
price_hidden false boolean defines if the price should be hidden for visitors (default: false)
prices_type 'incl_taxes' string defines if the price includes taxes
metadata { "some_key": "some_value" } json any metadata you'd like to set for the vehicle, not displayed in Stock Locator
listing_ids [] [integer] array of liting IDs the vehicle should be published to. Empty array unpublishes the vehicle from all listings
config_url 'https://config.url/conf213' string link to configuration of the vehicle
type DraftVehicle string ActiveVehicle (default) or DraftVehicle

Feature type objects

Each "feature" is a JSON object with 3 possible attributes:

  • code (optional)
  • label (required)
  • category (optional)

Allowed values for category are:

  • exterior
  • interior
  • lights
  • safety
  • wheels
  • seats
  • performance
  • infotainment
  • convenience
  • local_pack

Values for enums

state values

  • new
  • used
  • approved

status values

  • stock - Vehicles in stock
  • delivery - Vehicle in delivery
  • reserved - Reserved Vehicle (will be user later)
  • in_production - Vehicle in production
  • available_soon - Vehicle will be available soon
  • on_demand - Vehicle is available on demand
  • sold - Vehicle has been sold

transsmision values

  • auto
  • manual

engine_type values

  • petrol
  • diesel
  • bev - Electric Vehicle
  • hev - Hybrid
  • mhev - Mild Hybrid
  • phev - Plug-In Hybrid

prices_type values

  • incl_taxes (if the price includes taxes)
  • excl_taxes (if the prices does not include taxes)
  • null / empty - not specified
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token 4aBYBiznfESygdL7WTu3
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "vehicle": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 27,
  • "nameplate_id": 33,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2016,
  • "created_at": "2025-04-01T07:57:51.790Z",
  • "updated_at": "2025-04-01T07:57:51.799Z",
  • "msrp_price": "49367.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "new",
  • "status": "in_production",
  • "delivery_date": "2025-04-18",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 861494,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 201,
  • "video_url": null,
  • "owner_id": 119,
  • "color_id": 42,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "1ec721",
  • "interior_color": "Ebony",
  • "created_by": null,
  • "price_hidden": false,
  • "prices_type": null,
  • "model_code": null,
  • "footnote": null,
  • "config_url": null,
  • "subscribe_price": null,
  • "vehicle_batch_upload_id": null,
  • "order_number": null,
  • "metadata": {
    },
  • "locked_until": null,
  • "lock_id": null,
  • "code5000": null,
  • "price_metadata": { },
  • "manual_update_attributes": [ ],
  • "disclaimers": { },
  • "price_breakdown": false,
  • "base_price": null,
  • "total_price": null,
  • "published_at": null,
  • "number_of_seats": null
}

Delete Vehicle

path Parameters
external_id
string
Example: e38c8d21-f32d-4dcb-b52d-1678acab4c0e
query Parameters
external_id
required
string
Example: external_id=external_system_id_string

Uniq Id from integrated system alowing to find particular vehicle

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token KguJaa_4kWTFPwss8Gnu
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 28,
  • "nameplate_id": 34,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2016,
  • "created_at": "2025-04-01T07:57:51.867Z",
  • "updated_at": "2025-04-01T07:57:51.867Z",
  • "msrp_price": "26737.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "approved",
  • "status": "demo",
  • "delivery_date": "2025-04-02",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 980201,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 189,
  • "video_url": null,
  • "owner_id": 122,
  • "color_id": 43,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "e38c8d21-f32d-4dcb-b52d-1678acab4c0e",
  • "interior_color": "Ebony",
  • "created_by": null,
  • "price_hidden": false,
  • "prices_type": null,
  • "model_code": null,
  • "footnote": "Deserunt est aut iure et enim rem nobis natus consectetur.",
  • "config_url": null,
  • "subscribe_price": null,
  • "vehicle_batch_upload_id": null,
  • "order_number": null,
  • "metadata": null,
  • "locked_until": null,
  • "lock_id": null,
  • "code5000": null,
  • "price_metadata": { },
  • "manual_update_attributes": [ ],
  • "disclaimers": { },
  • "price_breakdown": false,
  • "base_price": null,
  • "total_price": null,
  • "published_at": null,
  • "number_of_seats": null
}

Colors List

Authentication

Authentication for integration API

Authentication is implemented using the HTTP Bearer token.

Every request needs to include that token.

Example Authorization: Token abc123 - where abc123 is the token value.

header Parameters
Accept
any
Example: application/json
Content-Type
any
Example: application/json
Authorization
any
Example: Token kKmnyEvgJBD8jN2wTXsE

Responses

Response samples

Content type
application/json; charset=utf-8
[ ]

List Colors

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token GtgHSTcSz_7p9hgcsfik
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    },
  • {
    },
  • {
    }
]

Nameplates List

Authentication

Authentication for integration API

Authentication is implemented using the HTTP Bearer token.

Every request needs to include that token.

Example Authorization: Token abc123 - where abc123 is the token value.

header Parameters
Accept
any
Example: application/json
Content-Type
any
Example: application/json
Authorization
any
Example: Token 1Z4rJWb6ATXTBGHEyfNQ

Responses

Response samples

Content type
application/json; charset=utf-8
[ ]

List Nameplates

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token J1jRy-bLCE_W_tztssp4
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Vehicle Photos Integration

Create Vehicle Photos

path Parameters
vehicle_external_id
string
Example: abc123
header Parameters
Accept
any
Example: application/json
Authorization
any
Example: Token invalid_token
Content-Type
any
Example: application/json
Request Body schema: application/json
Schema not provided

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Vehicles Integration

Show Vehicle

path Parameters
id
number
Example: 1
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token a7hKrsj3DcdMf9hoEHhg
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": {
    }
}

Update Vehicle

path Parameters
id
number
Example: 21
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token gxjZvA3HQ-vkM9qMy3sH
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "status": "reserved",
  • "nameplate_id": 21,
  • "owner_id": 104,
  • "color_id": 28,
  • "power": 237,
  • "msrp_price": "41707.0",
  • "base_price": null,
  • "features_optional": null,
  • "id": 21,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2016,
  • "created_at": "2025-04-01T07:57:51.171Z",
  • "updated_at": "2025-04-01T07:57:51.171Z",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "new",
  • "delivery_date": "2025-04-05",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 526081,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "video_url": null,
  • "features_standard": null,
  • "model_year": null,
  • "external_id": "8099f1",
  • "interior_color": "Ebony",
  • "created_by": null,
  • "price_hidden": false,
  • "prices_type": null,
  • "model_code": null,
  • "footnote": "Deserunt est aut iure et enim rem nobis natus consectetur.",
  • "config_url": null,
  • "subscribe_price": null,
  • "vehicle_batch_upload_id": null,
  • "order_number": null,
  • "metadata": null,
  • "locked_until": null,
  • "lock_id": null,
  • "code5000": null,
  • "price_metadata": { },
  • "manual_update_attributes": [ ],
  • "disclaimers": { },
  • "price_breakdown": false,
  • "total_price": null,
  • "published_at": null,
  • "number_of_seats": null
}

Lock vehicle temporarily

Action is used to lock vehicle after successful booking. It locks vehicle for 15 minutes in order to enable user completing the booking payment. In response it returns lock_id, which can be further used to perform acquire action to permanently reserve or mark vehicle as sold.

Request Path

PUT /integration_api/buy_online/vehicles/:id/lock

Request Header

Authorization: "Bearer {dealer authorization token}"

Request Body Structure

param example type required description
id 2 integer yes (in request path) Id of the vehicle in StockLocator

Response

Request response is JSON. Vehicle details are returned under data, while booking details (lock_id and locked_until) are returned under meta > lock_data.

When vehicle is not found, 404 status is returned.

When lock cannot be performed (because vehicle has reserved or sold status or it has already been locked), 422 status is returned.

path Parameters
id
number
Example: 4
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token _JczHK4LEMQmza_v-8mi
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": {
    },
  • "meta": {
    }
}

Cancel vehicle lock

Cancel vehicle lock [PUT /integration_api/buy_online/vehicles/{id}/unlock/{lock_id}]

Action is used to unlock soft-locked vehicle. By providing vehicle id and its lock_id lock can be cancelled before expiration time.

Request Path

PUT /integration_api/buy_online/vehicles/:id/unlock/:lock_id

Request Header

Authorization: "Bearer {dealer authorization token}"

Request Body Structure

param example type required description
id 2 integer yes (in request path) Id of the vehicle in StockLocator
lock_id 44c2 string yes (in request path) Lock ID of the vehicle

Response

Request response is JSON. Vehicle details are returned under data.

When vehicle is not found or is not locked, 404 status is returned.

When unlock fails, 422 status is returned.

  • Parameters

    • id: 10 (number, required)
    • lock_id: lock-id (string, required)

  • Request returns 200 status when vehicle with lock_id is found

path Parameters
id
number
Example: 11
lock_id
string
Example: lock-id
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token zrq5TinFnvN2xc9Tzybx
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": {
    }
}

Set vehicle status to reserved or sold

Action is used to permanently reserve or mark vehicle as sold. It is verified by lock id provided by lock action and optionally removes vehicle from all listings.

Request Path

PUT /integration_api/buy_online/vehicles/:id/acquire

Request Header

Authorization: "Bearer {dealer authorization token}"

Request Body Structure

param example type required description
id 2 integer yes (in request path) Id of the vehicle in StockLocator
status reserved string yes requested status, possible values are reserved and sold
lock_id 12ab string yes if vehicle has lock_id attr used to check lock identity, if vehicle has matching lock_id, lock is overridden and status is changed
remove_listings true boolean no when set to true vehicle is removed from all listings

Response

Request response is JSON. Vehicle details are returned under data key.

When vehicle is not found, 404 status is returned.

When lock cannot be performed (when status param is invalid or lock ids don't match), 422 status is returned.

path Parameters
id
number
Example: 16
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token sLt7a4L1ofF76GDuSAGH
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Authentication

Authentication for integration API

Authentication is implemented using the HTTP Bearer token.

Every request needs to include that token.

Example Authorization: Token abc123 - where abc123 is the token value.

header Parameters
Accept
any
Example: application/json
Content-Type
any
Example: application/json
Authorization
any
Example: Token 5ESMrk3uttnZd_4nz1ps
Request Body schema:
Schema not provided

Responses

Request samples

Content type
{
  • "vehicle": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 26,
  • "nameplate_id": 32,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2016,
  • "created_at": "2025-04-01T07:57:51.689Z",
  • "updated_at": "2025-04-01T07:57:51.697Z",
  • "msrp_price": "36144.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "approved",
  • "status": "delivery",
  • "delivery_date": "2025-04-30",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 450249,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 238,
  • "video_url": null,
  • "owner_id": 117,
  • "color_id": 40,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "36a450",
  • "interior_color": "Ebony",
  • "created_by": null,
  • "price_hidden": false,
  • "prices_type": null,
  • "model_code": null,
  • "footnote": null,
  • "config_url": null,
  • "subscribe_price": null,
  • "vehicle_batch_upload_id": null,
  • "order_number": null,
  • "metadata": {
    },
  • "locked_until": null,
  • "lock_id": null,
  • "code5000": null,
  • "price_metadata": { },
  • "manual_update_attributes": [ ],
  • "disclaimers": { },
  • "price_breakdown": false,
  • "base_price": null,
  • "total_price": null,
  • "published_at": null,
  • "number_of_seats": null
}

Create or Update a Vehicle

This endpoint allows you to create or update a vehicle in the Stock Locator system. For vehicle creation, you need to provide a set of required attributes (described below) but there are some extra, non-obligatory attributes which may be worth filling in to keep the vehicle description as complete as possible. For vehicle update, the attributes marked as required are no longer required - if they are not provided, the Stock Locator application assumes that they don't have to be updated.

One attribute which is important in this API is external_id - in general it is optional in the Stock Locator system, however in this API you should consider it as required. This attribute allows you to set an ID (you should set your own value or use value from your stock management system). The external_id is later used to identify a vehicle you may want to update od remove from the system.

Vehicle parameters (required for vehicle creation)

param example type description
color_name 'Eiger Grey' string See /colors endpoint for available colors. You can alternatively pass 'color_id' instead of the ID of the Color
nameplate_name 'F-Pace' string See /nameplates endpoint for available nameplates. You can alternatively pass nameplate_id instead with the ID of the Nameplate
version 'HSE' string Version/Trim Level name/description
drivetrain 'P300 AWD' string Drivetrain (Engine, gearbox etc) description
state 'new' enum Vehicle state. New, User or Approved
status 'stock' enum Stock status of the Vehicle
transmission 'auto' enum type of transmission, auto by default
mileage 123000 number vehicle mileage in ower company units
engine_type ['petrol', 'mhev'] array kind of engine, as a strings array
production_year 2020 integer Year when vehicle was manufacturedd
msrp_price 123000 decimal(18,2) Retailer price
external_id 'abd-3345' string External ID (of your choice) for the vehicle. Required to allow vehicle update/removal

Vehicle parameters (optional)

param example type description
short_description 'Lorem ipsum' string Short description paragraph
sale_price 120000 decimal(18,2) Sale Price
monthly_price 2500.01 decimal(18,2) Monthly price
subscribe_price 2700.00 decimal(18,2) Subscribe price
long_description 'Lorem ...' string Full description copy (potentialy HTML)
delivery_date 2020-02-02 date Date of delivery
vin 'XXX' string Vehicle Vin number
engine_capacity 1999 number engine capacity in ccm
battery_capacity 2020 number battery capacity in owner company units
power 200 number vehicle power in owner company units
video_url 'https://youtu.be/bJqimfimHjE' string youtube video url
photos ['http://site.com/1.png'] array photos url (first photo will become a cover photo)
attachment 'http://example.com/file.pdf' string attachment link
features_standard [{"code": "S1", "label": "Label1"}, ...] [Feature] array of Feature-type objects, described below
features_optional [{"code": "O1", "label": "Label2"}, ...] [Feature] array of Feature-type objects, described below
interior_color 'Snow white' string interior color
price_hidden false boolean defines if the price should be hidden for visitors (default: false)
prices_type 'incl_taxes' string defines if the price includes taxes
metadata { "some_key": "some_value" } json any metadata you'd like to set for the vehicle, not displayed in Stock Locator
listing_ids [] [integer] array of liting IDs the vehicle should be published to. Empty array unpublishes the vehicle from all listings
config_url 'https://config.url/conf213' string link to configuration of the vehicle
type DraftVehicle string ActiveVehicle (default) or DraftVehicle

Feature type objects

Each "feature" is a JSON object with 3 possible attributes:

  • code (optional)
  • label (required)
  • category (optional)

Allowed values for category are:

  • exterior
  • interior
  • lights
  • safety
  • wheels
  • seats
  • performance
  • infotainment
  • convenience
  • local_pack

Values for enums

state values

  • new
  • used
  • approved

status values

  • stock - Vehicles in stock
  • delivery - Vehicle in delivery
  • reserved - Reserved Vehicle (will be user later)
  • in_production - Vehicle in production
  • available_soon - Vehicle will be available soon
  • on_demand - Vehicle is available on demand
  • sold - Vehicle has been sold

transsmision values

  • auto
  • manual

engine_type values

  • petrol
  • diesel
  • bev - Electric Vehicle
  • hev - Hybrid
  • mhev - Mild Hybrid
  • phev - Plug-In Hybrid

prices_type values

  • incl_taxes (if the price includes taxes)
  • excl_taxes (if the prices does not include taxes)
  • null / empty - not specified
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token 4aBYBiznfESygdL7WTu3
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "vehicle": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 27,
  • "nameplate_id": 33,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2016,
  • "created_at": "2025-04-01T07:57:51.790Z",
  • "updated_at": "2025-04-01T07:57:51.799Z",
  • "msrp_price": "49367.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "new",
  • "status": "in_production",
  • "delivery_date": "2025-04-18",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 861494,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 201,
  • "video_url": null,
  • "owner_id": 119,
  • "color_id": 42,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "1ec721",
  • "interior_color": "Ebony",
  • "created_by": null,
  • "price_hidden": false,
  • "prices_type": null,
  • "model_code": null,
  • "footnote": null,
  • "config_url": null,
  • "subscribe_price": null,
  • "vehicle_batch_upload_id": null,
  • "order_number": null,
  • "metadata": {
    },
  • "locked_until": null,
  • "lock_id": null,
  • "code5000": null,
  • "price_metadata": { },
  • "manual_update_attributes": [ ],
  • "disclaimers": { },
  • "price_breakdown": false,
  • "base_price": null,
  • "total_price": null,
  • "published_at": null,
  • "number_of_seats": null
}

Delete Vehicle

path Parameters
external_id
string
Example: e38c8d21-f32d-4dcb-b52d-1678acab4c0e
query Parameters
external_id
required
string
Example: external_id=external_system_id_string

Uniq Id from integrated system alowing to find particular vehicle

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token KguJaa_4kWTFPwss8Gnu
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 28,
  • "nameplate_id": 34,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2016,
  • "created_at": "2025-04-01T07:57:51.867Z",
  • "updated_at": "2025-04-01T07:57:51.867Z",
  • "msrp_price": "26737.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "approved",
  • "status": "demo",
  • "delivery_date": "2025-04-02",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 980201,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 189,
  • "video_url": null,
  • "owner_id": 122,
  • "color_id": 43,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "e38c8d21-f32d-4dcb-b52d-1678acab4c0e",
  • "interior_color": "Ebony",
  • "created_by": null,
  • "price_hidden": false,
  • "prices_type": null,
  • "model_code": null,
  • "footnote": "Deserunt est aut iure et enim rem nobis natus consectetur.",
  • "config_url": null,
  • "subscribe_price": null,
  • "vehicle_batch_upload_id": null,
  • "order_number": null,
  • "metadata": null,
  • "locked_until": null,
  • "lock_id": null,
  • "code5000": null,
  • "price_metadata": { },
  • "manual_update_attributes": [ ],
  • "disclaimers": { },
  • "price_breakdown": false,
  • "base_price": null,
  • "total_price": null,
  • "published_at": null,
  • "number_of_seats": null
}

Companies

List Companies

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token token
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ]
}

Print Companies Tree

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token token
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": "digraph G {\n \"208\" [label=\"Ritchie-Kunde\"]\n}\n"
}

Brand

Represents Brand like Jaguar or Land Rover

Get Brands belonging to Owner

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 3e0fd2b5-a9da-466d-8179-e0817965e5ac
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [ ]
}

/brands

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: dcd58b5d-ea6f-4193-8d2d-03d64b931563
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema:
Schema not provided

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Show one brand belonging to Owner

path Parameters
id
number
Example: 3
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 92616a92-1869-48c4-ac32-3ef574c767fd
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Update Brand belonging to Owner

path Parameters
id
number
Example: 5
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: e5203d66-9ef8-4584-9a42-c72d8953fcdd
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Delete Brand belonging to Owner

path Parameters
id
number
Example: 7
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 70b2e76e-1fac-48e9-b645-5ad5f085ba8c
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

ButtonSet

Object representing ButtonSet model.

ButtonSet Attributes

attr type required example notes
label string yes "Main set" ButtonSet name
buttons array no [{"label": "Click here", ...}] Nested buttons attributes (see table below)
button_set_type string yes "extended" Can be either "standard" or "extended"
reservation_fee decimal(18,2) if extended(*) 2000.00 Reservation fee
financing_options array if extended(*) ["cash"] Multiselect - array can contain some or all of following values: ['cash', 'lease', 'rent']

(*) - reservation_fee and financing_options attributes are required only, if button_set_type value is set to extended

Button Attributes

attr type required example notes
label string yes "Click here" Button label displayed to user
target string yes "john@doe.com" Target URL, phone, code (embed) etc.
button_type enum yes "secondary" A type of a button (primary/secondary)
target_action enum yes "self" Defines what happens on button click
target_type enum yes "email" Defines a type of a target action

Button type

Button type can be either primary or secondary. Please note that only 1 primary button is allowed for a company. Secondary buttons are optional.

Target action

Defines what happens when the button is clicked. Accepted values:

  • self - executes defined action in current browser's tab
  • new_tab - executes defined action in a new tab
  • modal - executes defined action in a modal

Target type

Defines a type of a target action. Allowed values:

  • email
  • url
  • embed
  • phone

Request UUID header

All actions performed on ButtonSet objects need to happen in context of Company object.

The Company is determined based on X-Company-UUID header value. This value should contain uuid attribute of Company obejct.

If header is not present API will raise 400 - Bad Request response with information about missing header

If header is present but no Company with provided uuid values is present in the database the 404 - Not Found response is given.

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bad-uuid-value

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "errors": [
    ]
}

Get All ButtonSets

This endpoint will return a list of button sets owned by a Company specified by X-Company-UUID header.

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: d8a5a272-9c3b-4d9c-afa2-fec101606798
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ],
  • "included": [
    ]
}

/button_sets

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 947467e0-8064-4efd-9798-bd08da08daa1
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    },
  • "included": [
    ]
}

Get one ButtonSet

This endpoint will return button set with related buttons included

path Parameters
id
number
Example: 11
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bf94f457-ad80-4277-9448-b8f170bcc430
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    },
  • "included": [
    ]
}

Update ButtonSet

Owner is defined based on required X-Company-UUID header.

API does not allow for modification of Button Sets other then owned by a Company specified by X-Company-UUID header.

path Parameters
id
number
Example: 16
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 4c33a633-04e9-4591-ac15-3a131bbc503b
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    },
  • "included": [
    ]
}

Delete ButtonSet

Owner is defined based on required X-Company-UUID header.

API does not allow to delete Button Sets not owned by a Company specified by X-Company-UUID header.

path Parameters
id
number
Example: 20
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 9d4f36bf-2140-47f1-a876-258e4405f8cc
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Color

Object representing Vehicle exterior color.

Attributes

attr type reqiured example notes
name string yes "Firenze Red" Display name of the color showed to end user
canonical enum yes "red" Canonical color mapping, used for filtering

Canonical value

Brand Color name can not be very descriptive, also local retailers sometimes want to add their own colors named in local language like "Niebieski".

On the other hand customers looking for a vehicle do not want to find "Fuji White" vehicles. They are interested in selecting actuall color like brown.

Thats why all Colors in the system require to be mapped to predetermined color pallet through the canonical attribute.

This attribute is strongly validated againts list determined by system and only available options are:

  • white
  • black
  • silver
  • gray
  • red
  • green
  • bronze
  • blue
  • yellow
  • orange

Get All Colors

This endpoint will return two combined sets of Colors

  • Brand colors owned by any of the Brand objects
  • Company colors owned by a Company specified by X-Company-UUID header
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 4ea28877-13ee-4fd4-bdf2-70ad084180c6
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ]
}

/colors

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 41edd419-bbdc-42f8-82ea-93c778bca279
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Show one color

This endpoint will return color only if it is in one of the disinct sets

  • Brand colors owned by any of the Brand objects
  • Company colors owned by a Company specified by X-Company-UUID header

Note: Colors owned by other Companies will trigger 404 response.

path Parameters
id
number
Example: 3
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: c8a152d5-a63f-4210-9ab0-d0ff72782397
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Update Color

Owner is defined based on required X-Company-UUID header.

API does not allow for modification of Colors other then owned by a Company specified by X-Company-UUID header.

There is no option to modify Brand owned colors through this API.

path Parameters
id
number
Example: 5
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 6b3c9212-afd2-49f6-bc58-56fe22ee47e0
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Delete Color

Owner is defined based on required X-Company-UUID header.

API does not allow to delete Colors not owned by a Company specified by X-Company-UUID header.

This also means Brand owner colors cannot be deleted through the API.

path Parameters
id
number
Example: 7
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: b79b32af-d389-440d-9473-55219ffb5364
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Company

Represents Company data.

All API actions are to be executed in the context of selected Company.

uuid parameter

Company object is by default equiped with randomly generate uuid attribute. It's purpose is to be Company unique indentifier used in X-Company-UUID header to filter all action and resources in the API requests.

NOTE: uuid value cannot be modified directly through the api calls.

Current Company

All API Actions performed on Companies are scoped to current company instance. The current company is found based on the X-Company-UUID header value.

Due to this the some Company controller actions and URLs were changed.

Verb Old URL New URL Behaviour (after changes)
GET /companies (same) It list only current company and its Subcompanies
POST /companies (same) Creates compnany owned by current company
GET /company /companies/{id} Fetches Current Company
PATCH /company /companies/{id} Updates Current Company

For easier transition both new and old URLs are working simultanously.

Company Deleting endpoit was turned off

Request UUID header

All actions performed on Company objects need to happen in context of current Company object.

Current Company is determined based on X-Company-UUID header value. This value should contain uuid attribute of Company obejct.

If header is not present API will raise 400 - Bad Request response with information about missing header

If header is present but no Company with provided uuid values is present in the database the 404 - Not Found response is given.

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bad-uuid-value

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "errors": [
    ]
}

Get Companies in network

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: c7ecf52f-7ad4-41ec-a935-87976ea3c22a
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}

/companies

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 8cbaa728-3be8-44fb-9a9d-58ded4e7598e
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Get all Companies user has access to

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 8959d57b-7c23-4a8f-86b6-08c7dc0bf808
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [ ]
}

Get Available Time Zones

This endpoints provide option to fetch all Timezones needed to update Compane Time Zone setting.

It is possible to filter this list to only specific country based on country ISO code but list of all available 151 zones is also available.

TimeZone name and id attributes are the same value and it should be used as value for time_zone company attribute when updating data.

path Parameters
country_code
string
Example: IN
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bd1925f5-80de-4f9c-a29a-762fd354d5eb
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}

Show current company

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: e92418e5-6ea3-46cb-9fff-3686db0682f6
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Update current Company

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 42360025-bbf1-47ca-a201-db8471e1b228
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

FeatureFlagPolicies

Get array with flags for given owners

GET /feature_flag_policies/flags

Overview

This endpoint is used to get flags for owner defined in params.

Request Body Structure

param example type required description
company_uuid 1 integer yes uuid of the company
brand_ids 1 integer no ids of brands (spearated by comma)

Usage

To fetch flags only for company, we define only company_uuid paramater. If we want to get additional brand flags we have to define specific brand_ids.

Possible responses and response data

status 200

Returns array with flags for defined owners. If there is no flags array will be empty.

status 404

Company defined in params does not exist.

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 684cdd86-429d-4db0-829b-57f9c2de1e7d
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "company_uuid": "684cdd86-429d-4db0-829b-57f9c2de1e7d"
}

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": [
    ]
}

JobResults

Show one job result

GET /job_results/:job_uid

Overview

This endpoint is used to fetch the result of completed asynchronous job.

Request Body Structure

param example type required description
job_uid 1 string yes (in url) uid of the job

Possible responses and response data

status 200

Job result was found and it has follwing attributes:

job_uid - uid of the job data - data of the job result

status 404

Job result was not found

path Parameters
job_uid
string
Example: GtDyjkS5OE7432U2
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: cfd4a6b6-5c0e-4137-bd8a-c3fdeac026a5
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "job_uid": "GtDyjkS5OE7432U2",
  • "data": {
    }
}

Import vehicle data and photos from OSVD API

POST /osvd/vehicle_import

Overview

This endpoint is used to trigger vehicle mapper job to fetch data for the vehicle from OSVD API

Request Body Structure

param example type required description
vehicle_id SALVT1BG1EH795896 string yes (in url) VIN or order number of the vehicle

Response

job_uid - uid of the job vehicle_id - id of the vehicle vehicle_id_type - id type, can be 'vin' in case alphabetic characters are dected in vehicle in id or 'order_number' otherwise

header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: 6664e806-8501-4526-a90e-6bf1fd798ee8
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/json
Request Body schema: application/json
Schema not provided

Responses

Request samples

Content type
application/json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "vehicle_id": "SALVT1BG1EH795896",
  • "vehicle_id_type": "vin",
  • "job_uid": null
}

Listing

Object representing Vehicle list to be displayed on site.

Attributes

attr type reqiured example notes
title string yes "Winter Sale" Display name of the list to be displayed in system

uuid parameter

Listing object is by default equiped with randomly generate uuid attribute. It's purpose is to be Listing unique indentifier used when fetchin vehicles on external websites through the API.

NOTE: uuid value cannot be modified directly through the api calls.

Request UUID header

All actions performed on Listing objects need to happen in context of Company object.

The Company is determined based on X-Company-UUID header value. This value should contain uuid attribute of Company obejct.

If header is not present API will raise 400 - Bad Request response with information about missing header

If header is present but no Company with provided uuid values is present in the database the 404 - Not Found response is given.

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bad-uuid-value

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "errors": [
    ]
}

Get All Listings

This endpoint will return Listings owned by a Company specified by X-Company-UUID header

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: e6ca1742-6075-44e7-91e9-2fb5dff29734
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}

/listings

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 9bf30186-04de-4739-99f3-082954e7efe5
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    },
  • "included": [
    ]
}

Show one listing

This endpoint will return Listings owned by a Company specified by X-Company-UUID header.

Note: Colors owned by other Companies will trigger 404 response.

path Parameters
id
number
Example: 7
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: b542775c-3a48-4bfb-8dd5-deb4f402ca21
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    },
  • "included": [
    ]
}

Update Listing

Owner is defined based on required X-Company-UUID header.

path Parameters
id
number
Example: 9
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: d4ebfaf0-1c2c-4be2-8597-ab7b2e657863
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    },
  • "included": [
    ]
}

Delete Listing

Owner is defined based on required X-Company-UUID header.

API does not allow to delete Listings not owned by a Company specified by X-Company-UUID header.

path Parameters
id
number
Example: 11
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 1f9d3255-1cb0-4454-b24d-a75d98b6810e
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

(Un)Publishing Vehicles

Publishing controller is very simple in usage. All parameters are passed in the URLs as showed below.

  • PUT request adds vehicle to listing
  • DELETE request removes vehicle from listing

Adding or removing vehicle twice will not raise any error. The Vehicle will simply not be added/removed again and response will reflect actual state.

NOTE: Both Vehile and Listing need to be owned by the same company that is passed through X-Company-UUID header value

path Parameters
id
number
Example: 60
vehicle_id
number
Example: 249
query Parameters
id
required
number
Example: id=2

Listing ID

vehicle_id
required
number
Example: vehicle_id=2

Vehicle ID

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: d6f74aa4-8d93-41ef-919e-d33725738925
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Nameplate

Represents Nameplate like Jaguar XE or Land Rover Discovery

Note: Requires Brand association to exist

Get All Nameplates belonging to Owner brands

header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: b8e05a64-3714-4417-b214-f6d621ba9af1
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}

/nameplates

header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: 4a13f138-fa37-426c-a493-634a02b1b2db
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/json
Request Body schema: application/json
Schema not provided

Responses

Request samples

Content type
application/json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Show one nameplate belonging to Owner brands

path Parameters
id
number
Example: 39
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: 7c97f777-6e84-44c2-b0f7-a4c5df545784
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Update Nameplate belonging to Owner brands

path Parameters
id
number
Example: 42
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: 81f35cfe-ed42-4eeb-8be7-374a052e3787
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/json
Request Body schema: application/json
Schema not provided

Responses

Request samples

Content type
application/json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Delete Nameplate belonging to Owner brands

path Parameters
id
number
Example: 45
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: 9de3397c-11ea-466e-bd00-2aada9731585
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "errors": [
    ]
}

PDF Translations Config

Get Widget Translations Config

header Parameters
Accept
any
Example: application/json
Content-Type
any
Example: application/json
X-Company-UUID
any
Example: af1103f0-9fdf-4fd7-ad73-91389b6438cb
Authorization
any
Example: Bearer STUB_TOKEN_STRING

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}

Generate PDF

header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: 5a78bf53-4ed8-4f5b-86cb-d1f812293ccc
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/json
Request Body schema: application/json
Schema not provided

Responses

Request samples

Content type
application/json
Example
{
  • "type": "window_display",
  • "data": {
    }
}

Response samples

Content type
application/pdf
ASCII-8BIT stream

Photo

Get All Photos

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ]
}

/photos

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema:
Schema not provided

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Show one photo

path Parameters
id
number
Example: 10
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Update Photo

path Parameters
id
number
Example: 15
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Delete Photo

path Parameters
id
number
Example: 19
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Duplicate Photo

Overview

Use this endpoint ot duplicate photos

Request Body Structure

param example type required description
photo_ids [1, 2, 3] array yes ids of photos to be duplicated, order of array determined response order

Response

data section - contains data of photo copies in jsonapi format

metadata section - contains mapping of old photos to their copies

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "photo_ids": [
    ]
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Sidekiq

Show one job result

GET /sidekiq/:id

Overview

This endpoint is used to get a status of the sidekiq job.

Request Body Structure

param example type required description
id 991c3dc1a0bcf01ce93ae34 string yes (in url) id of the job

Response data

job_id - id of the job status - status of the job, possible values are queued, working, complete, failed, interrupted, when value is null it means job does not exist

path Parameters
id
string
Example: cd836c9b0a8b89be954473f5
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: e82d3419-d05b-4cab-a175-a0389e4d4233
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "job_id": "cd836c9b0a8b89be954473f5",
  • "status": "complete"
}

VehicleBatchUploads

Stores files and data (photo status and vehicle errors) associated with vehicle batch uploads. It tracks status of upload job.

Show Vehicle Batch Upload

path Parameters
id
number
Example: 1
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 65da30da-7d49-43d4-a9aa-24d961e14500
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Create Vehicle Batch Upload

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: fa844734-7966-4431-a34a-77a509fdbaf6
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: multipart/form-data; boundary=----------XnJLe9ZIbbGUYtzPQJ16u1
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
"{\n \"file\": {\n \"filename\": \"valid_file.csv\",\n \"type\": \"text/csv\",\n \"name\": \"file\",\n \"tempfile\": \"#<File:0x00007f514c08ec48>\",\n \"head\": \"content-disposition: form-data; name=\\\"file\\\"; filename=\\\"valid_file.csv\\\"\\r\\ncontent-type: text/csv\\r\\ncontent-length: 3666\\r\\n\"\n }\n}"

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": {
    }
}

Shows pending upload id

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 8b8f9520-d224-4b5e-bc7d-b71009b3cca6
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "pending_upload_id": null
}

Vehicle Operation Requests

Pagination

Vehicles list is always paginated.

By default API will return up to 20 items but it can be overriden using items parameter. Here we use items=2 bo brevity but it's optional and set to 20 by default.

Paginated results include pagination metadata in the meta object like this:

 "meta": {
    "pagination": {
      //URL template to fetch additonal pages (PAGE_NUM) should be replaced by page number
      "scaffold_url": "...?items=2&page=PAGE_NUM",
      "count": 50,  // Overall amount of vehicles in collection
      "page": 3,    // Current page number
      "items": 2,   // Amount of items page page
      "pages": 25,  // Amount of all pages
      "last": 25,   // Last page number
      "from": 5,    // index of first item on current page
      "to": 6,      // index of last item on current page
      "prev": 2,    // previous page number, null if no previous page
      "next": 4     // next page number, null if no next page
    }
  }
query Parameters
page
required
number
Example: page=2

Pagination page to be requested (default: 1)

items
required
number
Example: items=3

Amount of items per page (default: 20)

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bf1e8e06-62b3-473b-94e1-e918a4ec28a2
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Filtering

Filtering mechanism utilises quite powerful Ransack gem engine

prefilters

Prefilters are parameters used to filter vehicles before any counting or dynamic filtering takes place. They are simple filters without any predicates. There are two perfilters:

forced_brands_names - filters vehicles by brand names separated by comma, ex. forced_brands_names=Land Rover,Jaguar forced_dealer_codes - filters vehicles by owner dealer codes, separated by comma, ex. forced_dealer_codes=50001,50002 forced_statuses - filters vehicles by statuses, separated by comma, ex. forced_dealer_codes=reserved,sold

filter attribute

To filter results one should use filter[] GET parameter object with each search/filter criteria as a separate parameter entry.

this parameters entries should adher to format of filter[:attribute_filtered:_:matcher_operator:]=value1.

attribute_filter part

In general it's possible to filter by all object parameters that can be seen in a typical API response. For vehicles it includes version, drivetrain, production_year etc. However, there's one non-standard attribute that you can filter by - display_price. It filters/sorts vehicles by the actual Vehicle price (so it checks whether a vehicle has sale_price value - if not, it takes msrp_price for that vehicle as the current price).

On top of that one can filter based on selected related models by concatenating relationship name and related obejct attribute. For example Nameplate name is not stored in the Vehicle model but it can ge used as filter parameter as nameplate_name.

This kind of relationship searches can go deeper. Since Brand is related to Nameplate not Vechile itself, to filter vehicles by Brand name we should user nameplate_brand_name attributes.

matcher part

Full list of all available matcher operators can be seen here: https://github.com/activerecord-hackery/ransack#search-matchers

Most usefull and important ones are:

Matcher Description
_eq Equality
_gt Greater then
_gteq Greater than or equal
_lt Less then
_lteq Less than or equal
_start Starts with
_i_cont Contains value with (case insensitive)
_cont Contains value with (case sensitive)
_in Match any values separated by comma Eg: filter[name_in]=Bob,Alice

Multiple attribute filters

To return vehicles which match one of multiple filters, or operator has to be used. For example, to search for vehicles which vin or order_number start with some value filter should looke like this:

filter[vin_or_order_number_start]=123

Engine Types

engine_types and owner_dealers_codes are specific parameters due to the fact they are stored as array in the database so simple string-based cont predicates will not work. To filter based on this array content new predicate _includes was added. So to filter for all "Petrol" powered vehicles request should look like this:

filter[engine_type_includes]=petrol

This will return both hybrid and non-hybrid Vehicles as long as they also include petrol in engine_type array

Multiple engine types can be searched separated by comma:

filter[engine_type_includes]=petrol,bev

Will return petrol as well as bev engines

Financing options

financing options is a specific parameter based on scope and does not have any predicates. To use it chosen values separated by comma have to be provided:

filter[financing_options]=cash,lease,rent

Status

status filter is based on two attributes. It filters vehicles by status attribute and also checks lock_id which indicates that vehicle is soft-locked. In case it is soft-locked it is searched as it would be of reserved status. Because of that status filter is processed outside ransack and accepts _eq and _in predicates only.

Examples

To Search Vechiles with production year beetween 2015 and 2018:

filter[production_year_gteq]=2015&filter[production_year_lteq]=2018

To Search all Jaguars

filter[nameplate_brand_name_eq]=Jaguar

To Search all Vechiles with HSE in version

filter[version_i_cont]=HSE
query Parameters
filter
required
object
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 9a8219b0-bf14-4cb7-a246-20eb9642cdf4
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ],
  • "meta": {
    }
}

Sorting

Sorting

Simliast to Filtering the sorting mechanism utilises quite powerful Ransack gem engine

sort attribute

To sort results one should use sort GET parameter as a list of collumns that records should be sorted by.

Ascending and Descending orders

By default sorting works in natura ascending order. To use the ascending order (usefull for prices) column name should be predicated with minus (-, U+002D HYPHEN-MINUS) character

Examples

To Sort Vechiles in ascending order by msrp_price

sort=msrp_price

To Sort Vechiles in descending order by msrp_price

sort=-msrp_price

To Sort Vechiles in ascending order by production year and then in descending order by msrp_price

sort=production_year,-msrp_price
query Parameters
sort
required
string
Example: sort=status_sort

Comma separated list of columns to sort VehicleOperationRequest by

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 9390c4d2-e323-4b0b-a25d-e04c6f672c93
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ],
  • "meta": {
    }
}

Show vehicle operation request with vehicle data

path Parameters
id
number
Example: 107
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: b6c1adf1-7879-4c46-a014-1f44e3c17e2f
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": {
    }
}

Sellect All Vehicle Operation Requests for Publications lists

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: d0d42aad-b783-464c-b207-d81edf27ad5c
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Sellect All Vehicle Operation Requests for Stock Transfer

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 261cc425-da58-4401-af51-9c0b2415994e
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [ ],
  • "meta": {
    }
}

Approve Vehicle Operation Requests

path Parameters
id
number
Example: 123
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 8c6ff034-ce29-4d59-bcbf-fa7ef989ff4e
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Reject Vehicle Operation Requests

path Parameters
id
number
Example: 126
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 43018d8a-79f8-42ec-93eb-52e357751e8a
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Show all Log Entries

path Parameters
id
number
Example: 127
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: fadc40b2-fcef-4bd6-8b2f-7858bf9fc73d
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}

See details of a Vehicle related to operation request

path Parameters
id
number
Example: 130
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 06790984-2ce1-4c03-84da-e46e51d1c223
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    },
  • "included": [
    ]
}

Vehicle Batch Actions

Sellect All Vehicles ids

Returns ids and count of all vehicles. (works with filters and sorting)

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 76e2a23c-2bdc-4106-b8d1-24a5c92e6149
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "ids": [
    ],
  • "count": 1
}

Returns data for selected vehicles

path Parameters
ids
string
Example: 383,384
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 0acb7a8a-b86e-45a8-ac1e-c6faeb443c9e
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ]
}

Delete vehicles with selected

path Parameters
ids
string
Example: 395,396
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 104b5592-8ba4-436b-b166-40c5d289edea
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [ ]
}

Update selected vehicles and return updated data

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: b0cc2f73-ac06-4fcd-85a2-6d315e8723a7
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": [
    ]
}

Vehicle

Request UUID header

All actions performed on Vehicle objects need to happen in context of Company object.

The Company is determined based on X-Company-UUID header value. This value should contain uuid attribute of Company obejct.

If header is not present API will raise 400 - Bad Request response with information about missing header

If header is present but no Company with provided uuid values is present in the database the 404 - Not Found response is given.

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bad-uuid-value

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "errors": [
    ]
}

Features Objects

Vehicle features lists

Vehicle Standard and optional feature lists are stored in separate attributes (features_standard and features_optional) as validated JSON array.

Validation happens based on JSON Schema defined like this:

{
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "label"
    ],
    "properties": {
      "code": {
        "type": "string"
      },
      "label": {
        "type": "string",
        "minLength": 1

      },
      "category": {
        "type": "string",
        "enum": [
          "exterior",
          "interior",
          "lights",
          "safety",
          "wheels",
          "seats",
          "performance",
          "infotainment",
          "convenience"
        ]
      }
    },
    "additionalProperties": false
  }
}

To put it more clearly each feature shoudl be simple object with string properties. Only one property is required (label). Properties code and category are optional. label needs to contain at least 1 character, meaning it cannot be emoty string!

category values are expected to come from closed list of values:

"exterior", "interior", "lights", "safety", "wheels", "seats", "performance", "infotainment", "convenience"

Valid features examples:

[
  {
    "code": "XXX123",
    "label": "Heated Windshield",
    "category": "convenience"
  },
  {
    "label": "22' Bespoke Wheels",
    "category": "wheels"
  },
  {
    "code": "YYYZZZ",
    "label": "Custom Paint"
  },
]

Validation

Each JSON Schema validation error will be returned as a separate validation error with human readable description message.

Validation Example can be seen bellow in test cases.

NOTE: Those messages should not be presented to the end user. Their intent is to be used for debuging purposes only!

path Parameters
id
number
Example: 399
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: f6a65298-c51c-4875-836e-59c9f930f5ad
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Filtering

Filtering mechanism utilises quite powerful Ransack gem engine

prefilters

Prefilters are parameters used to filter vehicles before any counting or dynamic filtering takes place. They are simple filters without any predicates. There are two perfilters:

forced_brands_names - filters vehicles by brand names separated by comma, ex. forced_brands_names=Land Rover,Jaguar forced_dealer_codes - filters vehicles by owner dealer codes, separated by comma, ex. forced_dealer_codes=50001,50002 forced_statuses - filters vehicles by statuses, separated by comma, ex. forced_dealer_codes=reserved,sold

filter attribute

To filter results one should use filter[] GET parameter object with each search/filter criteria as a separate parameter entry.

this parameters entries should adher to format of filter[:attribute_filtered:_:matcher_operator:]=value1.

attribute_filter part

In general it's possible to filter by all object parameters that can be seen in a typical API response. For vehicles it includes version, drivetrain, production_year etc. However, there's one non-standard attribute that you can filter by - display_price. It filters/sorts vehicles by the actual Vehicle price (so it checks whether a vehicle has sale_price value - if not, it takes msrp_price for that vehicle as the current price).

On top of that one can filter based on selected related models by concatenating relationship name and related obejct attribute. For example Nameplate name is not stored in the Vehicle model but it can ge used as filter parameter as nameplate_name.

This kind of relationship searches can go deeper. Since Brand is related to Nameplate not Vechile itself, to filter vehicles by Brand name we should user nameplate_brand_name attributes.

matcher part

Full list of all available matcher operators can be seen here: https://github.com/activerecord-hackery/ransack#search-matchers

Most usefull and important ones are:

Matcher Description
_eq Equality
_gt Greater then
_gteq Greater than or equal
_lt Less then
_lteq Less than or equal
_start Starts with
_i_cont Contains value with (case insensitive)
_cont Contains value with (case sensitive)
_in Match any values separated by comma Eg: filter[name_in]=Bob,Alice

Multiple attribute filters

To return vehicles which match one of multiple filters, or operator has to be used. For example, to search for vehicles which vin or order_number start with some value filter should looke like this:

filter[vin_or_order_number_start]=123

Engine Types

engine_types and owner_dealers_codes are specific parameters due to the fact they are stored as array in the database so simple string-based cont predicates will not work. To filter based on this array content new predicate _includes was added. So to filter for all "Petrol" powered vehicles request should look like this:

filter[engine_type_includes]=petrol

This will return both hybrid and non-hybrid Vehicles as long as they also include petrol in engine_type array

Multiple engine types can be searched separated by comma:

filter[engine_type_includes]=petrol,bev

Will return petrol as well as bev engines

Financing options

financing options is a specific parameter based on scope and does not have any predicates. To use it chosen values separated by comma have to be provided:

filter[financing_options]=cash,lease,rent

Status

status filter is based on two attributes. It filters vehicles by status attribute and also checks lock_id which indicates that vehicle is soft-locked. In case it is soft-locked it is searched as it would be of reserved status. Because of that status filter is processed outside ransack and accepts _eq and _in predicates only.

Examples

To Search Vechiles with production year beetween 2015 and 2018:

filter[production_year_gteq]=2015&filter[production_year_lteq]=2018

To Search all Jaguars

filter[nameplate_brand_name_eq]=Jaguar

To Search all Vechiles with HSE in version

filter[version_i_cont]=HSE
query Parameters
filter
required
object
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 51d22139-b873-4ab9-9d77-62a8eab394da
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Sorting

Sorting

Simliast to Filtering the sorting mechanism utilises quite powerful Ransack gem engine

sort attribute

To sort results one should use sort GET parameter as a list of collumns that records should be sorted by.

Ascending and Descending orders

By default sorting works in natura ascending order. To use the ascending order (usefull for prices) column name should be predicated with minus (-, U+002D HYPHEN-MINUS) character

Examples

To Sort Vechiles in ascending order by msrp_price

sort=msrp_price

To Sort Vechiles in descending order by msrp_price

sort=-msrp_price

To Sort Vechiles in ascending order by production year and then in descending order by msrp_price

sort=production_year,-msrp_price
query Parameters
sort
required
string
Example: sort=msrp_price

Comma separated list of columns to sort vehicles by

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 9a72f339-1650-4816-8476-442ad5460a61
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Pagination

Vehicles list is always paginated.

By default API will return up to 20 items but it can be overriden using items parameter. Here we use items=2 bo brevity but it's optional and set to 20 by default.

Paginated results include pagination metadata in the meta object like this:

 "meta": {
    "pagination": {
      //URL template to fetch additonal pages (PAGE_NUM) should be replaced by page number
      "scaffold_url": "...?items=2&page=PAGE_NUM",
      "count": 50,  // Overall amount of vehicles in collection
      "page": 3,    // Current page number
      "items": 2,   // Amount of items page page
      "pages": 25,  // Amount of all pages
      "last": 25,   // Last page number
      "from": 5,    // index of first item on current page
      "to": 6,      // index of last item on current page
      "prev": 2,    // previous page number, null if no previous page
      "next": 4     // next page number, null if no next page
    }
  }
query Parameters
page
required
number
Example: page=2

Pagination page to be requested (default: 1)

items
required
number
Example: items=3

Amount of items per page (default: 20)

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: c4f0e83f-5f00-49d3-8975-bacff66b9c6e
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Attach Photos to Vehicle

Photos relationship

Photos are attached through relationship to Vehicle like in example below.

Photos order in request will be maintained.

Photos can be assigne during Vehicle creation and update actions.

Photo removal (warning)

Previously assigned photos will be deleted if their ids are ommited from relationship payload.

If payload photos section is empty then photos collection will be emptied!

To not make any changes to photos attached to vehicles it's relationship section in payload should be removed completly.

including photos in response

To inluce photos into the response additional parameter need to be passed in the url. Photos object will be added in separate included array in the payload as shown on the last example.

include=photos
path Parameters
id
number
Example: 516
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: c204a269-f1e2-4d20-a283-4c70546377f7
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Include Operation Requests to Vehicle

path Parameters
id
number
Example: 521
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 8599c86f-eeec-4e6b-ba37-b36f1cc44b33
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    },
  • "included": [
    ]
}

Get All Vehicles

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bb301f20-15d4-486d-a839-5ba633d8d317
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ],
  • "meta": {
    }
}

/vehicles

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 911efa2e-da96-4f1b-9c3c-2d01d6c8f2d8
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Show one vehicle

path Parameters
id
number
Example: 524
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: b7809333-fce7-4d8a-95f7-a016ba48b5fa
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Update Vehicle

path Parameters
id
number
Example: 527
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: c37420c2-b1bb-457f-9940-589283bc96f2
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Delete Vehicle

path Parameters
id
number
Example: 535
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 5b261a10-2a30-4e23-8eb0-809042e690a5
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Duplicate one vehicle

This endpoint will return duplicated data for a Vehicle based on the Vehicle with :id passed in the url.

This endpoint returns only data, it will not create new Vehicle record in database.

The exchanged data/relationships listed below will be omitted

  • short_description
  • video_url
  • vin
  • attachment
  • listings
  • all relation added with feature flags
path Parameters
id
number
Example: 526
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 5d981ae7-67fe-4817-b180-6679d84be8a4
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Export Vehicles

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 88943e14-1ea2-4a5f-915e-edb83cb45c52
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
text/csv
Example
ID,VIN,Order Number,Added date,Publication date,Number of images,Owner account name,Vehicle type,Car State,Car Status,Price,Model,Version,Fuel Type,Engine capacity,Engine power,Transmission,Exterior Color,Interior Color,Sale price,Monthly price,Created by,Configuration link

Fetch Vehicle data

path Parameters
uuid
string
Example: ee0e1df5-4206-4e92-8b73-a8b4bb333b43
vehicle_id
number
Example: 29
header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

VistaFile

/vista_files/features

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bad-uuid-value
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    },
  • "included": [ ]
}

Vocabulary

Represents vocabulary (and translations) stored in the database and used in feature suggestions. In fact, the database representation of Vocabulary is FeatureSuggestion but to make it more adjusted to the actual needs of the Vocabulary tab of the application, it is a separate resource in the API with separate data structure definition.

Pagination

Vocabulary list is always paginated.

By default API will return up to 20 items.

Paginated results include pagination metadata in the meta object like this:

 "meta": {
    "pagination": {
      //URL template to fetch additonal pages (PAGE_NUM) should be replaced by page number
      "scaffold_url": "...?page=PAGE_NUM",
      "count": 50,  // Overall amount of vehicles in collection
      "page": 3,    // Current page number
      "items": 20,   // Amount of items page page
      "pages": 3,  // Amount of all pages
      "last": 3,   // Last page number
      "from": 20,    // index of first item on current page
      "to": 30,      // index of last item on current page
      "prev": 2,    // previous page number, null if no previous page
      "next": 4     // next page number, null if no next page
    }
  }
query Parameters
page
required
number
Example: page=2

Pagination page to be requested (default: 1)

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 648ca945-f03d-4b4c-8d90-f09f4fddaab1
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "meta": {
    },
  • "data": [ ]
}

Search

Filtering mechanism utilises quite powerful Ransack gem engine

filter attribute

To filter results one should use filter[] GET parameter object with each search/filter criteria as a separate parameter entry.

this parameters entries should adher to format of filter[:attribute_filtered:_:matcher_operator:]=value1.

attribute_filter part

In general it's possible to filter by all object parameters that can be seen in a typical API response. For vocabulary it includes code, category, brand_code etc.

matcher part

Full list of all available matcher operators can be seen here: https://github.com/activerecord-hackery/ransack#search-matchers

Most usefull and important ones are:

Matcher Description
_eq Equality
_gt Greater then
_gteq Greater than or equal
_lt Less then
_lteq Less than or equal
_start Starts with
_i_cont Contains value with (case insensitive)
_cont Contains value with (case sensitive)
_in Match any values in an array. Eg: filter[name_in][]=Alice&filter[name_in][]=Bob

search alias

search allows you to filter objects by several attributes at once category, code, original_description, label or brand_code

It should be pair with macher from above for example filter[search_cont]=mazda

query Parameters
filter[search_cont]
required
string
Example: filter[search_cont]=020BE

Filtred items to be requested

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 3a1c50d0-f87d-4047-91bf-5dfae09be8f6
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ],
  • "meta": {
    }
}

Get All Vocabulary entries

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: b6d683a3-3039-4677-9136-4e38a56eb6ac
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Vocabulary resource

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 34b2c74e-60bc-4099-9686-c1432d5ec0df
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Destroy Vocabulary entry

path Parameters
id
number
Example: 147
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 763e2626-3c03-4f3c-8b07-14ed2a9b7f9a
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

/vocabulary/{code}

path Parameters
code
string
Example: A1
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 5a0f3280-775c-4c36-8a36-ecb667cc78e0
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Vehicle

Request UUID header

All actions performed on Vehicle objects need to happen in context of Company object.

The Company is determined based on X-Company-UUID header value. This value should contain uuid attribute of Company obejct.

If header is not present API will raise 400 - Bad Request response with information about missing header

If header is present but no Company with provided uuid values is present in the database the 404 - Not Found response is given.

header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bad-uuid-value

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "errors": [
    ]
}

Features Objects

Vehicle features lists

Vehicle Standard and optional feature lists are stored in separate attributes (features_standard and features_optional) as validated JSON array.

Validation happens based on JSON Schema defined like this:

{
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "label"
    ],
    "properties": {
      "code": {
        "type": "string"
      },
      "label": {
        "type": "string",
        "minLength": 1

      },
      "category": {
        "type": "string",
        "enum": [
          "exterior",
          "interior",
          "lights",
          "safety",
          "wheels",
          "seats",
          "performance",
          "infotainment",
          "convenience"
        ]
      }
    },
    "additionalProperties": false
  }
}

To put it more clearly each feature shoudl be simple object with string properties. Only one property is required (label). Properties code and category are optional. label needs to contain at least 1 character, meaning it cannot be emoty string!

category values are expected to come from closed list of values:

"exterior", "interior", "lights", "safety", "wheels", "seats", "performance", "infotainment", "convenience"

Valid features examples:

[
  {
    "code": "XXX123",
    "label": "Heated Windshield",
    "category": "convenience"
  },
  {
    "label": "22' Bespoke Wheels",
    "category": "wheels"
  },
  {
    "code": "YYYZZZ",
    "label": "Custom Paint"
  },
]

Validation

Each JSON Schema validation error will be returned as a separate validation error with human readable description message.

Validation Example can be seen bellow in test cases.

NOTE: Those messages should not be presented to the end user. Their intent is to be used for debuging purposes only!

path Parameters
id
number
Example: 399
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: f6a65298-c51c-4875-836e-59c9f930f5ad
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Filtering

Filtering mechanism utilises quite powerful Ransack gem engine

prefilters

Prefilters are parameters used to filter vehicles before any counting or dynamic filtering takes place. They are simple filters without any predicates. There are two perfilters:

forced_brands_names - filters vehicles by brand names separated by comma, ex. forced_brands_names=Land Rover,Jaguar forced_dealer_codes - filters vehicles by owner dealer codes, separated by comma, ex. forced_dealer_codes=50001,50002 forced_statuses - filters vehicles by statuses, separated by comma, ex. forced_dealer_codes=reserved,sold

filter attribute

To filter results one should use filter[] GET parameter object with each search/filter criteria as a separate parameter entry.

this parameters entries should adher to format of filter[:attribute_filtered:_:matcher_operator:]=value1.

attribute_filter part

In general it's possible to filter by all object parameters that can be seen in a typical API response. For vehicles it includes version, drivetrain, production_year etc. However, there's one non-standard attribute that you can filter by - display_price. It filters/sorts vehicles by the actual Vehicle price (so it checks whether a vehicle has sale_price value - if not, it takes msrp_price for that vehicle as the current price).

On top of that one can filter based on selected related models by concatenating relationship name and related obejct attribute. For example Nameplate name is not stored in the Vehicle model but it can ge used as filter parameter as nameplate_name.

This kind of relationship searches can go deeper. Since Brand is related to Nameplate not Vechile itself, to filter vehicles by Brand name we should user nameplate_brand_name attributes.

matcher part

Full list of all available matcher operators can be seen here: https://github.com/activerecord-hackery/ransack#search-matchers

Most usefull and important ones are:

Matcher Description
_eq Equality
_gt Greater then
_gteq Greater than or equal
_lt Less then
_lteq Less than or equal
_start Starts with
_i_cont Contains value with (case insensitive)
_cont Contains value with (case sensitive)
_in Match any values separated by comma Eg: filter[name_in]=Bob,Alice

Multiple attribute filters

To return vehicles which match one of multiple filters, or operator has to be used. For example, to search for vehicles which vin or order_number start with some value filter should looke like this:

filter[vin_or_order_number_start]=123

Engine Types

engine_types and owner_dealers_codes are specific parameters due to the fact they are stored as array in the database so simple string-based cont predicates will not work. To filter based on this array content new predicate _includes was added. So to filter for all "Petrol" powered vehicles request should look like this:

filter[engine_type_includes]=petrol

This will return both hybrid and non-hybrid Vehicles as long as they also include petrol in engine_type array

Multiple engine types can be searched separated by comma:

filter[engine_type_includes]=petrol,bev

Will return petrol as well as bev engines

Financing options

financing options is a specific parameter based on scope and does not have any predicates. To use it chosen values separated by comma have to be provided:

filter[financing_options]=cash,lease,rent

Status

status filter is based on two attributes. It filters vehicles by status attribute and also checks lock_id which indicates that vehicle is soft-locked. In case it is soft-locked it is searched as it would be of reserved status. Because of that status filter is processed outside ransack and accepts _eq and _in predicates only.

Examples

To Search Vechiles with production year beetween 2015 and 2018:

filter[production_year_gteq]=2015&filter[production_year_lteq]=2018

To Search all Jaguars

filter[nameplate_brand_name_eq]=Jaguar

To Search all Vechiles with HSE in version

filter[version_i_cont]=HSE
query Parameters
filter
required
object
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 51d22139-b873-4ab9-9d77-62a8eab394da
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Sorting

Sorting

Simliast to Filtering the sorting mechanism utilises quite powerful Ransack gem engine

sort attribute

To sort results one should use sort GET parameter as a list of collumns that records should be sorted by.

Ascending and Descending orders

By default sorting works in natura ascending order. To use the ascending order (usefull for prices) column name should be predicated with minus (-, U+002D HYPHEN-MINUS) character

Examples

To Sort Vechiles in ascending order by msrp_price

sort=msrp_price

To Sort Vechiles in descending order by msrp_price

sort=-msrp_price

To Sort Vechiles in ascending order by production year and then in descending order by msrp_price

sort=production_year,-msrp_price
query Parameters
sort
required
string
Example: sort=msrp_price

Comma separated list of columns to sort vehicles by

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 9a72f339-1650-4816-8476-442ad5460a61
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Pagination

Vehicles list is always paginated.

By default API will return up to 20 items but it can be overriden using items parameter. Here we use items=2 bo brevity but it's optional and set to 20 by default.

Paginated results include pagination metadata in the meta object like this:

 "meta": {
    "pagination": {
      //URL template to fetch additonal pages (PAGE_NUM) should be replaced by page number
      "scaffold_url": "...?items=2&page=PAGE_NUM",
      "count": 50,  // Overall amount of vehicles in collection
      "page": 3,    // Current page number
      "items": 2,   // Amount of items page page
      "pages": 25,  // Amount of all pages
      "last": 25,   // Last page number
      "from": 5,    // index of first item on current page
      "to": 6,      // index of last item on current page
      "prev": 2,    // previous page number, null if no previous page
      "next": 4     // next page number, null if no next page
    }
  }
query Parameters
page
required
number
Example: page=2

Pagination page to be requested (default: 1)

items
required
number
Example: items=3

Amount of items per page (default: 20)

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: c4f0e83f-5f00-49d3-8975-bacff66b9c6e
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Attach Photos to Vehicle

Photos relationship

Photos are attached through relationship to Vehicle like in example below.

Photos order in request will be maintained.

Photos can be assigne during Vehicle creation and update actions.

Photo removal (warning)

Previously assigned photos will be deleted if their ids are ommited from relationship payload.

If payload photos section is empty then photos collection will be emptied!

To not make any changes to photos attached to vehicles it's relationship section in payload should be removed completly.

including photos in response

To inluce photos into the response additional parameter need to be passed in the url. Photos object will be added in separate included array in the payload as shown on the last example.

include=photos
path Parameters
id
number
Example: 516
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: c204a269-f1e2-4d20-a283-4c70546377f7
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Include Operation Requests to Vehicle

path Parameters
id
number
Example: 521
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 8599c86f-eeec-4e6b-ba37-b36f1cc44b33
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    },
  • "included": [
    ]
}

Get All Vehicles

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bb301f20-15d4-486d-a839-5ba633d8d317
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ],
  • "meta": {
    }
}

/vehicles

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 911efa2e-da96-4f1b-9c3c-2d01d6c8f2d8
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Show one vehicle

path Parameters
id
number
Example: 524
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: b7809333-fce7-4d8a-95f7-a016ba48b5fa
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Update Vehicle

path Parameters
id
number
Example: 527
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: c37420c2-b1bb-457f-9940-589283bc96f2
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json
Request Body schema: application/vnd.api+json
Schema not provided

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Delete Vehicle

path Parameters
id
number
Example: 535
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 5b261a10-2a30-4e23-8eb0-809042e690a5
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Duplicate one vehicle

This endpoint will return duplicated data for a Vehicle based on the Vehicle with :id passed in the url.

This endpoint returns only data, it will not create new Vehicle record in database.

The exchanged data/relationships listed below will be omitted

  • short_description
  • video_url
  • vin
  • attachment
  • listings
  • all relation added with feature flags
path Parameters
id
number
Example: 526
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 5d981ae7-67fe-4817-b180-6679d84be8a4
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Export Vehicles

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 88943e14-1ea2-4a5f-915e-edb83cb45c52
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
text/csv
Example
ID,VIN,Order Number,Added date,Publication date,Number of images,Owner account name,Vehicle type,Car State,Car Status,Price,Model,Version,Fuel Type,Engine capacity,Engine power,Transmission,Exterior Color,Interior Color,Sale price,Monthly price,Created by,Configuration link

Fetch Vehicle data

path Parameters
uuid
string
Example: ee0e1df5-4206-4e92-8b73-a8b4bb333b43
vehicle_id
number
Example: 29
header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": {
    }
}

Brands

Represents Brand like Jaguar or Land Rover

Get All Brands

header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ]
}

Get Nameplates by Brand

path Parameters
id
number
Example: 94
header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ]
}

CompanyConfig

Is used to store config for origin urls.

It contains config_type attribute with possible values default, cash, lease, subscription and additional. Each origin can have single config per each type.

Get All Company Configs

GET /public_api/company_config/all

Overview

This endpoint is used to fetch configs for declared origin. By default it returns all configs for that origin.

Origin Header

To fetch config for the specific origin, it has to be declared in Company-Config header . For example:

Company-Config: 'https://jaguar.com'

Request Body Structure

param example type required description
config_type additional,cash string no used to filter config types, multiple types have to be separated by comma

Response data

Response is an array of configs for origin declared in the header. Each of the contains attributes data and config_type

header Parameters
Accept
any
Example: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}

Get Company Config

GET /public_api/company_config/(:config_type)

Overview

This endpoint is used to fetch a specific config for declared origin. By default it returns default config for that origin.

Origin Header

To fetch config for the specific origin, it has to be declared in Company-Config header . For example:

Company-Config: 'https://jaguar.com'

Request Body Structure

param example type required description
config_type additional string no used to fetch config of specific type

Response data

Response is an config object containing attributes data and config_type

header Parameters
Accept
any
Example: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

Vehicles

Overview

/public_api section is intended to be freely used on all websites and provide data to StockLocator widgets.

Its behaviour is mostly modeled based on private /vehicles controller but lacks authorization, returns only active vehicles and is optimized for typical website usecases.

Basic required attribute to use it is Listing object uuid value. As far as I know this value is currently not displayed on the SL frontend (to be fixed) so ask Badyl for it if you need one :)

Config data

query Parameters
config_url
required
string
header Parameters
Accept
any
Example: application/json
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": {
    }
}

Filtering

Filtering mechanism utilises quite powerful Ransack gem engine

prefilters

Prefilters are parameters used to filter vehicles before any counting or dynamic filtering takes place. They are simple filters without any predicates. There are two perfilters:

forced_brands_names - filters vehicles by brand names separated by comma, ex. forced_brands_names=Land Rover,Jaguar forced_dealer_codes - filters vehicles by owner dealer codes, separated by comma, ex. forced_dealer_codes=50001,50002 forced_statuses - filters vehicles by statuses, separated by comma, ex. forced_dealer_codes=reserved,sold

filter attribute

To filter results one should use filter[] GET parameter object with each search/filter criteria as a separate parameter entry.

this parameters entries should adher to format of filter[:attribute_filtered:_:matcher_operator:]=value1.

attribute_filter part

In general it's possible to filter by all object parameters that can be seen in a typical API response. For vehicles it includes version, drivetrain, production_year etc. However, there's one non-standard attribute that you can filter by - display_price. It filters/sorts vehicles by the actual Vehicle price (so it checks whether a vehicle has sale_price value - if not, it takes msrp_price for that vehicle as the current price).

On top of that one can filter based on selected related models by concatenating relationship name and related obejct attribute. For example Nameplate name is not stored in the Vehicle model but it can ge used as filter parameter as nameplate_name.

This kind of relationship searches can go deeper. Since Brand is related to Nameplate not Vechile itself, to filter vehicles by Brand name we should user nameplate_brand_name attributes.

matcher part

Full list of all available matcher operators can be seen here: https://github.com/activerecord-hackery/ransack#search-matchers

Most usefull and important ones are:

Matcher Description
_eq Equality
_gt Greater then
_gteq Greater than or equal
_lt Less then
_lteq Less than or equal
_start Starts with
_i_cont Contains value with (case insensitive)
_cont Contains value with (case sensitive)
_in Match any values separated by comma Eg: filter[name_in]=Bob,Alice

Multiple attribute filters

To return vehicles which match one of multiple filters, or operator has to be used. For example, to search for vehicles which vin or order_number start with some value filter should looke like this:

filter[vin_or_order_number_start]=123

Engine Types

engine_types and owner_dealers_codes are specific parameters due to the fact they are stored as array in the database so simple string-based cont predicates will not work. To filter based on this array content new predicate _includes was added. So to filter for all "Petrol" powered vehicles request should look like this:

filter[engine_type_includes]=petrol

This will return both hybrid and non-hybrid Vehicles as long as they also include petrol in engine_type array

Multiple engine types can be searched separated by comma:

filter[engine_type_includes]=petrol,bev

Will return petrol as well as bev engines

Financing options

financing options is a specific parameter based on scope and does not have any predicates. To use it chosen values separated by comma have to be provided:

filter[financing_options]=cash,lease,rent

Status

status filter is based on two attributes. It filters vehicles by status attribute and also checks lock_id which indicates that vehicle is soft-locked. In case it is soft-locked it is searched as it would be of reserved status. Because of that status filter is processed outside ransack and accepts _eq and _in predicates only.

Examples

To Search Vechiles with production year beetween 2015 and 2018:

filter[production_year_gteq]=2015&filter[production_year_lteq]=2018

To Search all Jaguars

filter[nameplate_brand_name_eq]=Jaguar

To Search all Vechiles with HSE in version

filter[version_i_cont]=HSE
path Parameters
uuids
string
Example: f30e8808-56f8-473a-9245-21e8647cc273
query Parameters
filter
required
object
header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Show companies

Action is used to fetch ONLY lowest-level companies from listings owners hierarchies (leaves) ordered by name.

Request Path

GET /public_api/listing/{listing_uuids separated by comma}/companies

Request Body Structure

param example type required source in configurator json description
uuids "dea07f,dc4cd" string yes (in request path) not present Ids of listings containing requested vehicles separated by comma (no comma needed for single listing)

Response

Response JSON contains ordered array with companies.

path Parameters
uuids
string
Example: 7b36d721-a421-4f36-b922-f1d0f58414ed
query Parameters
uuids
required
string
Example: uuids=d6af041b-8a7b-4560-bfaa-d5b8f502710c

Listing UUID values

header Parameters
Accept
any
Example: application/json
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ]
}

Show retailers

Action is used to fetch ONLY lowest-level companies (retailers) from listings owners hierarchies (leaves) ordered by name.

Request Path

GET /public_api/listing/{listing_uuids separated by comma}/retailers

Request Body Structure

param example type required source in configurator json description
uuids "dea07f,dc4cd" string yes (in request path) not present Ids of listings containing requested vehicles separated by comma (no comma needed for single listing)

Response

Response JSON contains ordered array with companies.

path Parameters
uuids
string
Example: 489e7cf5-c15f-425a-bf2e-da774c07ba87
query Parameters
uuids
required
string
Example: uuids=d6af041b-8a7b-4560-bfaa-d5b8f502710c

Listing UUID values

header Parameters
Accept
any
Example: application/json
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ]
}

Sorting

Sorting

Simliast to Filtering the sorting mechanism utilises quite powerful Ransack gem engine

sort attribute

To sort results one should use sort GET parameter as a list of collumns that records should be sorted by.

Ascending and Descending orders

By default sorting works in natura ascending order. To use the ascending order (usefull for prices) column name should be predicated with minus (-, U+002D HYPHEN-MINUS) character

Examples

To Sort Vechiles in ascending order by msrp_price

sort=msrp_price

To Sort Vechiles in descending order by msrp_price

sort=-msrp_price

To Sort Vechiles in ascending order by production year and then in descending order by msrp_price

sort=production_year,-msrp_price
path Parameters
uuids
string
Example: 4405b851-752f-4bcb-a567-64a2dc4d70a6
query Parameters
sort
required
string
Example: sort=msrp_price

Comma separated list of columns to sort vehicles by

header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Pagination

Vehicles list is always paginated.

By default API will return up to 20 items but it can be overriden using items parameter. Here we use items=2 bo brevity but it's optional and set to 20 by default.

Paginated results include pagination metadata in the meta object like this:

 "meta": {
    "pagination": {
      //URL template to fetch additonal pages (PAGE_NUM) should be replaced by page number
      "scaffold_url": "...?items=2&page=PAGE_NUM",
      "count": 50,  // Overall amount of vehicles in collection
      "page": 3,    // Current page number
      "items": 2,   // Amount of items page page
      "pages": 25,  // Amount of all pages
      "last": 25,   // Last page number
      "from": 5,    // index of first item on current page
      "to": 6,      // index of last item on current page
      "prev": 2,    // previous page number, null if no previous page
      "next": 4     // next page number, null if no next page
    }
  }
path Parameters
uuids
string
Example: ed01df23-ed7a-4474-ab2d-d7aa1e445647
query Parameters
page
required
number
Example: page=2

Pagination page to be requested (default: 1)

items
required
number
Example: items=3

Amount of items per page (default: 20)

header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Get All Vehicle for Listing

Overview

This endpoint inherits a lot of behaviour and data format from private /vehicles endpoint but some details were adapted to better match publich "widget" use case. Differences are

  • only photos and lisitings relationships are listed. owner, color, nameplate etc are ommitted
  • meta includes max/min values for msrp_price and mileage values.
  • no option to include photos in all vehicles listing
  • vehicles from multiple listings can be fetched by providing their uuids separated by comma
path Parameters
uuids
string
Example: 4706acfc-799d-42f4-98fe-bf1a060231df
query Parameters
uuid
required
string
Example: uuid=d6af041b-8a7b-4560-bfaa-d5b8f502710c

Listing UUID value

header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Show matcing vehicles

This endpoint fetches vehicles with similar specification with this passed in query params.

Make sure to pass brand and nameplate in query params, this two params are required.

Request Query Params

param example type required description
brand Jaguar string yes Brand name
nameplate XE string yes Vehicle nameplate
specpack R-Dynamic SE string no Vehicle version
bodystyle 'LWB' enum no Vehicle bodystyle (LWB, Long Wheelbase, Standard Wheelbase', 'SWB')
engine 'P200' string no Vehicle engine
fuel_type 'P' enum no Vehicle fuel type (P, D)

You can add all filters and sort option for example:

/public_api/listing/:uuid/matching_vehicles?brand=Jaguar&nameplate=XE&filter[state_eq]=new

This request will return all vehicles with brand and nameplate match and with state set to 'new'

path Parameters
uuids
string
Example: 57bd9fd8-fe86-4c93-bbc7-1d0a7efea1a6
query Parameters
uuid
required
string
Example: uuid=d6af041b-8a7b-4560-bfaa-d5b8f502710c

Listing UUID value

header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Show one Vehicle

Overview

This endpoint inherits a lot of behaviour and data format from private /vehicles/:id endpoint but some details were adapted to better match publich "widget" use case. Differences are:

  • only photos and lisitings relationships are listed. owner, color, nameplate etc are ommitted
  • photos are included by default
path Parameters
uuids
string
Example: d27271a6-eec8-4550-8003-8cae34bb9ec2
vehicle_id
number
Example: 237
query Parameters
uuid
required
string
Example: uuid=d6af041b-8a7b-4560-bfaa-d5b8f502710c

Listing UUID value

vehicle_id
required
number
Example: vehicle_id=12

Vehicle ID

header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    },
  • "meta": {
    },
  • "included": [
    ]
}

Show Vehicle's OSVD Data

This endpoint fetches Vehicle info from OSVD API and tries to generate a configurator URL for that Vehicle. To make it work properly, the Vehicle should have proper values of either VIN or Order Number.

If some values are null, it means that the endpoint was not able to fetch the requested data from one of the APIs.

path Parameters
uuids
string
Example: 7e448402-ab75-4663-a2fa-547c934b0dae
vehicle_id
number
Example: 243
query Parameters
uuid
required
string
Example: uuid=d6af041b-8a7b-4560-bfaa-d5b8f502710c

Listing UUID value

vehicle_id
required
number
Example: vehicle_id=12

Vehicle ID

header Parameters
Accept
any
Example: application/vnd.api+json
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{}

DynamicContent

Get namplates counters inside Listing

path Parameters
uuids
string
Example: d8f7b7d7-6717-405e-9ad3-8387935928fb
query Parameters
uuids
required
string
Example: uuids=d6af041b-8a7b-4560-bfaa-d5b8f502710c

Listing UUID value

header Parameters
Accept
any
Example: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "d8f7b7d7-6717-405e-9ad3-8387935928fb": [
    ]
}

CompanyConfigMazda

Is used to store config for origin urls.

It contains config_type attribute with possible values default, cash, lease, subscription and additional. Each origin can have single config per each type.

Get All Company Configs (for Mazda)

GET /public_api/company_config/all

Overview

This endpoint is used to fetch configs for declared origin. By default it returns all configs for that origin.

Origin Header

To fetch config for the specific origin, it has to be declared in Company-Config header . For example:

Company-Config: 'https://jaguar.com'

Request Body Structure

param example type required description
config_type additional,cash string no used to filter config types, multiple types have to be separated by comma

Response data

Response is an array of configs for origin declared in the header. Each of the contains attributes data and config_type

header Parameters
Accept
any
Example: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}

Get Company Config

GET /public_api/company_config/(:config_type)

Overview

This endpoint is used to fetch a specific config for declared origin. By default it returns default config for that origin.

Origin Header

To fetch config for the specific origin, it has to be declared in Company-Config header . For example:

Company-Config: 'https://jaguar.com'

Request Body Structure

param example type required description
config_type additional string no used to fetch config of specific type

Response data

Response is an config object containing attributes data and config_type

header Parameters
Accept
any
Example: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

StockMatchingConfig

Is used to store configs for stock matching.

It contains data attribute to store config and keys array to identify config

Get Stock Matching Config

GET /public_api/sl_configurator_journey_configs/:key

Overview

This endpoint is used to fetch a specific stock matching config by its key.

Request Body Structure

param example type required description
key first string yes (in url) used to fetch config

Response data

Response is an config object containing attributes data

path Parameters
key
string
Example: third
header Parameters
Accept
any
Example: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

WidgetTranslationsConfig

Is used to store configs for widget translations.

It contains data attribute to store config and keys array to identify config

Get Widget Translations Config

GET /public_api/widget_translations_configs/:key

Overview

This endpoint is used to fetch a specific widget translations config by its key.

Request Body Structure

param example type required description
key first string yes (in url) used to fetch config

Response data

Response is an config object containing attributes data

path Parameters
key
string
Example: second
header Parameters
Accept
any
Example: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type
any
Example: application/json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": {
    }
}

FeatureSuggestions

Overview

FeatureSuggestions are dictionary suggestions entries which are inteded to be used as suggestions for user filling out the Vechile form features section either while adding or editing the Cars.

The FeatureSuggestions list is updated each time Vehicle is saved to database (created or updated). Thay are not designed to be manipulated through the API directly.

NOTE: Due to this behaviour X-Comapny-UUID header is required to filter suggestions based on Company ownership.

As their intended used is a table with Vehicle features they always contain label attrbiute and optionally can contain code and category attributes as well depending on the data filed in the vehicle.

Get Suggestions by Code

path Parameters
code_query
string
Example: A12
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 3377846e-dafd-40e2-8713-afedd06b2cf1
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ]
}

Get Suggestions by Label

path Parameters
label_query
string
Example: word
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: ca8c9e01-4e21-4c97-aa2a-b7e1d30d44cd
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
{
  • "data": [
    ]
}

SimpleSuggestions

Overview

SimpleSuggestions are simple string based dictionary suggestions which are inteded to be used as suggestions for user filling out the Vechile form either while adding or editing the Cars

The SimpleSuggestions list is updated each time Vehicle is saved to database (created or updated). Thay are not designed to be manipulated through the API directly.

Suggestions are inherited through the companies hierarchy. If Importer already has one Suggestion in the database the Dealers will see this Suggestion as well and it will not be automatically duplicated when adding a Vehicle

NOTE: Due to this behaviour X-Comapny-UUID header is required to filter suggestions based on Company ownership.

SimpleSuggestion will handle only drivetrain and version fields.

Get Version Suggestions

Versions suggestions are accessed through /suggestions/versions endpoint.

Simply calling this endpoint will return all version suggestions available for a Company

To filter only to some selected values the endpoint should be called with URL like this:

/suggestions/versions/Value

This will only list Suggestions with case insensitive "value" string inside content column

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 744e1830-1bce-44a5-8d8d-7e9f41c26a47
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}

Get Drivetrains Suggestions

Drivetrains suggestions are accessed through /suggestions/drivetrains endpoint.

Simply calling this endpoint will return all drivetrain suggestions available for a Company

To filter only to some selected values the endpoint should be called with URL like this:

/suggestions/drivetrains/Petrol

This will only list Suggestions with case insensitive "Petrol" string inside content column

header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 46cf38d6-15a6-4aa0-abb8-4ebc4fc8cf48
Authorization
any
Example: Bearer STUB_TOKEN_STRING
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json; charset=utf-8
Example
{
  • "data": [
    ]
}