API docs by Redocly

API Documentation (1.0)

Download OpenAPI specification:Download

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 uZvzeFosstwWMT9FTXSW
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

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

Update Vehicle

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

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "status": "reserved",
  • "nameplate_id": 20,
  • "owner_id": 103,
  • "color_id": 27,
  • "power": 294,
  • "msrp_price": "30767.0",
  • "base_price": null,
  • "features_optional": null,
  • "id": 20,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2015,
  • "created_at": "2024-11-20T08:09:20.899Z",
  • "updated_at": "2024-11-20T08:09:20.915Z",
  • "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": "2024-12-10",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 197093,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "video_url": null,
  • "features_standard": null,
  • "model_year": null,
  • "external_id": "b19533",
  • "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
}

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: 3
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token ixbm76cX7GmRfsD3aoLa
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: 10
lock_id
string
Example: lock-id
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token pVzuQSi5YnLLF-Ldyrzz
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: 15
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token 1vuN-3S2t7mRkiV1vF5h
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 G1yAksxvfJ6odw2o2BU4
Request Body schema:
Schema not provided

Responses

Request samples

Content type
{
  • "vehicle": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 25,
  • "nameplate_id": 31,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2015,
  • "created_at": "2024-11-20T08:09:21.375Z",
  • "updated_at": "2024-11-20T08:09:21.382Z",
  • "msrp_price": "22222.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": "in_production",
  • "delivery_date": "2024-11-24",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 42789,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 327,
  • "video_url": null,
  • "owner_id": 116,
  • "color_id": 39,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "24d6c7",
  • "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
}

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 5sE6psgQtmseo_QEwnkL
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": 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": 2015,
  • "created_at": "2024-11-20T08:09:21.465Z",
  • "updated_at": "2024-11-20T08:09:21.472Z",
  • "msrp_price": "34956.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": "used",
  • "status": "on_demand",
  • "delivery_date": "2024-12-01",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 326590,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 348,
  • "video_url": null,
  • "owner_id": 118,
  • "color_id": 41,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "8f62e1",
  • "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
}

Delete Vehicle

path Parameters
external_id
string
Example: 50fa005d-4179-47d4-9895-fc6063076a0a
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 zaT7chKa6-1zkvTofTyq
Content-Type
any
Example: application/vnd.api+json

Responses

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": 2015,
  • "created_at": "2024-11-20T08:09:21.526Z",
  • "updated_at": "2024-11-20T08:09:21.526Z",
  • "msrp_price": "38753.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": "available_soon",
  • "delivery_date": "2024-12-05",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 96333,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 273,
  • "video_url": null,
  • "owner_id": 121,
  • "color_id": 42,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "50fa005d-4179-47d4-9895-fc6063076a0a",
  • "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
}

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 Xu7ZwRHzT5HEczS5Mtn_

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 RrLmcExC23ViMMsLkRvr
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 HXg4m3_cJqvxJQmDA7f_

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 9x_is5WcRiqSsFk-A7Mr
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 uZvzeFosstwWMT9FTXSW
Content-Type
any
Example: application/vnd.api+json

Responses

Response samples

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

Update Vehicle

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

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "status": "reserved",
  • "nameplate_id": 20,
  • "owner_id": 103,
  • "color_id": 27,
  • "power": 294,
  • "msrp_price": "30767.0",
  • "base_price": null,
  • "features_optional": null,
  • "id": 20,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2015,
  • "created_at": "2024-11-20T08:09:20.899Z",
  • "updated_at": "2024-11-20T08:09:20.915Z",
  • "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": "2024-12-10",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 197093,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "video_url": null,
  • "features_standard": null,
  • "model_year": null,
  • "external_id": "b19533",
  • "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
}

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: 3
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token ixbm76cX7GmRfsD3aoLa
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: 10
lock_id
string
Example: lock-id
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token pVzuQSi5YnLLF-Ldyrzz
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: 15
header Parameters
Accept
any
Example: application/vnd.api+json
Authorization
any
Example: Token 1vuN-3S2t7mRkiV1vF5h
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 G1yAksxvfJ6odw2o2BU4
Request Body schema:
Schema not provided

Responses

Request samples

Content type
{
  • "vehicle": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 25,
  • "nameplate_id": 31,
  • "version": "Crisis On Infinite Earths",
  • "drivetrain": "The Sinestro Corps War",
  • "short_description": "Blanditiis quia laudantium numquam voluptate et eos earum quaerat quae.",
  • "production_year": 2015,
  • "created_at": "2024-11-20T08:09:21.375Z",
  • "updated_at": "2024-11-20T08:09:21.382Z",
  • "msrp_price": "22222.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": "in_production",
  • "delivery_date": "2024-11-24",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 42789,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 327,
  • "video_url": null,
  • "owner_id": 116,
  • "color_id": 39,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "24d6c7",
  • "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
}

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 5sE6psgQtmseo_QEwnkL
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": 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": 2015,
  • "created_at": "2024-11-20T08:09:21.465Z",
  • "updated_at": "2024-11-20T08:09:21.472Z",
  • "msrp_price": "34956.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": "used",
  • "status": "on_demand",
  • "delivery_date": "2024-12-01",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 326590,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 348,
  • "video_url": null,
  • "owner_id": 118,
  • "color_id": 41,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "8f62e1",
  • "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
}

Delete Vehicle

path Parameters
external_id
string
Example: 50fa005d-4179-47d4-9895-fc6063076a0a
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 zaT7chKa6-1zkvTofTyq
Content-Type
any
Example: application/vnd.api+json

Responses

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": 2015,
  • "created_at": "2024-11-20T08:09:21.526Z",
  • "updated_at": "2024-11-20T08:09:21.526Z",
  • "msrp_price": "38753.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": "available_soon",
  • "delivery_date": "2024-12-05",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 96333,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 273,
  • "video_url": null,
  • "owner_id": 121,
  • "color_id": 42,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "50fa005d-4179-47d4-9895-fc6063076a0a",
  • "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
}

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 \"207\" [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: ec1d4bed-ba07-474d-8d53-4d8f79cb237a
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: 68bdce63-a125-4151-a230-ee141ba9463a
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: 76947efe-d65a-4d47-9d46-ba11522f4d71
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: 04f6bea1-544e-44ac-bb8f-9fc29a06882a
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: 3e2b894e-05c4-42d4-8cbc-65d7d6d83890
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: ac219870-6bb1-478b-9f96-c7a3c167f33e
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: 6ee95fc0-a54a-46f9-8e93-9b906ac35549
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: 497cfa12-96de-456f-b4dc-f6b7826aed8f
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: 99d18106-ef09-48b3-896b-8a8a1a582f5f
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: ad50a9a3-b8f7-437e-8752-f91ed81224b2
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: 9af4d67c-acb1-448f-ad56-a6cfba5aab11
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: c2c9f4ff-28f3-4740-a944-33a0ef2bdaba
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: e5c4850d-b75b-45a8-9967-c98574ee481e
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: 7b8fc501-e424-4a51-b6c0-15f26839f006
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: 770b1978-a207-4811-93e4-60a889dce29a
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: d8ab794d-8150-4a7e-91a1-e2db64285dbe
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: a84b4382-a99f-4b86-b206-2eb3878cbc0a
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: 88952e01-94a0-4405-b02c-ad8be47fe5f0
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: 95bafc70-356f-4a62-898a-41823dd55dfa
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: 64d5e24c-1e34-4fa0-bac4-7996d92a3f88
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: cfdccc69-ed4a-45e9-8308-8bd78d4b732f
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: 37a6830f-0f45-40de-8919-d533c3cf80a0
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": "37a6830f-0f45-40de-8919-d533c3cf80a0"
}

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: 21Oe47coUo8LDLQi
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: fb42b759-6f57-4eef-8a7e-03edbeeb62d3
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": "21Oe47coUo8LDLQi",
  • "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: f1d95945-89cb-4c9e-b5e6-8dee84772ab3
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: 6dfbc2ad-a16a-48e5-a452-4cd5a210718e
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: 878390ef-d949-4d8f-b1c6-eb1ed760f2f0
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: 1cd17248-0fba-4910-b1d0-7849ac8379b3
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: 4445776c-5eb0-46bb-b7b8-041147a35de7
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: 850d6f79-1cf8-4c71-803b-60a01df442ba
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: 57
vehicle_id
number
Example: 232
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: 077714ac-4b45-465c-91f8-7b0210130a79
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: 55c0bc80-529e-4974-8cdb-3797793fc28e
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: d608b642-76a1-440e-ab5b-de6704a86c95
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: 38
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: b5741ad4-30c7-4067-a9be-a14be447b840
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: 41
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: e7045123-f95f-4e9f-9377-3b5579c1d804
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: 44
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: c72498a6-f540-497e-8876-8a53c5d2a456
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: e55d7ff4-11a3-4aeb-8847-9e6c3633e2a5
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: 99cbb96a-ff61-48c1-816c-e8f6de4e0f66
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

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: a3f3b2d44021a96d7fc05607
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: 35c8a6fc-d44c-40f0-b45c-3e2d3e524e76
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": "a3f3b2d44021a96d7fc05607",
  • "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: 0dc79b34-0ac5-4304-97a1-c37e68fa2350
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: eccf8cfa-8b4e-4534-b9bd-f35b8b2bb242
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:0x00007fe69e124328>\",\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: 5cfa082f-4f21-4386-a5fd-8df0f987e690
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: 6a431e67-8904-4544-9745-6f5d815ccae8
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: b71ef9aa-fda2-4cad-8951-7e15aebafd70
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: 15d94b60-0b4e-4e48-aaf8-714e45186124
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: 22a58fd4-82f4-4a45-b204-616f2ea99bde
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: 8ad75bbe-7bdf-4ddf-85be-5ceca08ae701
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: 5e941d20-a64e-416b-9566-27db5a395092
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: a959452f-301b-4859-9977-3f6e92d1cf23
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: 1b845760-6467-4803-a230-2dc6af45503c
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: 7591f2d8-10fa-4ae6-9a43-9d2d57d4376d
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: f839c25e-c77d-43d7-b08e-c25e1f988ea8
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: 9b1cae94-9ad0-400a-9bb3-6ee936e067ad
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: 366,367
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 03b743b5-fefe-4ebe-9c0f-a625fbb8a872
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: 378,379
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 9734f1e4-3c98-44be-92b9-b0f0a3404a9d
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: 09d9865e-c1d1-455d-bc54-eda82c599668
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: 382
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 02e55e24-f7c8-4bf6-b7e4-46a5fec5be9f
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: ddc17b52-0275-40c6-9128-4f77cc98cb99
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: 8df09b29-0b56-466e-87d8-e2d27e396e8e
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: a0c624e5-78f5-432a-8fa0-d200cfa0a58b
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: 499
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 4076c9a5-4a00-4440-977b-6d32558c449c
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: 504
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 83ef47eb-5648-4838-b593-9dcd27c73bb0
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: 8580d07e-d1a2-4a1c-999f-cb48d5e2ce65
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: e14b5961-b19d-4fc9-a095-943146cb2e26
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: 507
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 367d22e6-3f8d-419a-9d98-0609eac62e0a
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: 510
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: cb784f30-c07f-453a-96d3-0fcc41c4ecdd
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: 518
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 4e37ed74-7b71-40f3-8bd3-2b36831b54cf
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: 509
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 848692a7-947a-4d3b-8f9a-28c9e22db1cd
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: ef726f66-a68f-4393-b30a-6082ba9b1f06
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

Fetch Vehicle data

path Parameters
uuid
string
Example: 9f0849e3-998e-4f05-bea5-723b329e763b
vehicle_id
number
Example: 28
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: 6e71d9fc-96ad-467f-80ac-c5b39e327f6c
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: 84bf1335-e885-4758-830f-8ce614e8d780
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: 04412506-c21c-4a30-b298-9ab58f34abc2
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: c28faf8f-1feb-4182-888f-d5d0cbdaf125
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: 53a8bc55-c5f4-47c4-8246-a4c4b16a7a26
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: f31e497c-5171-4661-af66-d510fa02b5ed
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: 382
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 02e55e24-f7c8-4bf6-b7e4-46a5fec5be9f
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: ddc17b52-0275-40c6-9128-4f77cc98cb99
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: 8df09b29-0b56-466e-87d8-e2d27e396e8e
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: a0c624e5-78f5-432a-8fa0-d200cfa0a58b
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: 499
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 4076c9a5-4a00-4440-977b-6d32558c449c
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: 504
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 83ef47eb-5648-4838-b593-9dcd27c73bb0
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: 8580d07e-d1a2-4a1c-999f-cb48d5e2ce65
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: e14b5961-b19d-4fc9-a095-943146cb2e26
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: 507
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 367d22e6-3f8d-419a-9d98-0609eac62e0a
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: 510
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: cb784f30-c07f-453a-96d3-0fcc41c4ecdd
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: 518
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 4e37ed74-7b71-40f3-8bd3-2b36831b54cf
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: 509
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 848692a7-947a-4d3b-8f9a-28c9e22db1cd
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: ef726f66-a68f-4393-b30a-6082ba9b1f06
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

Fetch Vehicle data

path Parameters
uuid
string
Example: 9f0849e3-998e-4f05-bea5-723b329e763b
vehicle_id
number
Example: 28
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: 92
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

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

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: c91c6e63-b126-49d2-a5ab-c7ce115d0d70
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: 249a84a5-0217-4589-bbe7-3873f56fe3e4
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: 7f382aaf-8772-4c35-b142-97b88ed44334
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: e5e14b98-b703-41a9-9811-8f259d6b04e3
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: 8b8125b6-2d82-4490-84f5-a6d1ffa96e90
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: 3888b69c-e219-4656-bd60-317f72f12fb6
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: 0568c941-6ce1-4de1-ad51-8f5e5d24fb39
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: 8a629f07-39e4-42fb-b390-82e627ed670b
vehicle_id
number
Example: 222
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: 5862df6a-6dc6-4e98-b075-aa5b998f744b
vehicle_id
number
Example: 227
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: e62ec798-656e-41dc-bc98-950d3fffa12e
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

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "e62ec798-656e-41dc-bc98-950d3fffa12e": [
    ]
}

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

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

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

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

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: 5b9e7134-c50e-47f0-9d75-6a4e10ef2484
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: b7085733-debd-4e3e-b8e4-6525fffa89de
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: c1a8a14c-256b-420b-8518-8bb3e9ff72c4
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: ef7a0981-f349-4dc8-8719-00f73da5e1cf
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": [
    ]
}