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 7aWzXHiHkZE-R8AEVjNY
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 gabDCGZLsmXsui_cwA7x
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": 361,
  • "msrp_price": "23969.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-10-10T08:27:46.778Z",
  • "updated_at": "2024-10-10T08:27:46.816Z",
  • "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-10-14",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 840416,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "video_url": null,
  • "features_standard": null,
  • "model_year": null,
  • "external_id": "2c3e8d",
  • "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
}

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 5Bi2B_wDc9sy8mrgH9K5
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 s7QpxhWeokoMFJi_oaRU
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 bb9zxm-ui24j8ghg1nqB
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 rwDpSFy3EDPdVPbqm11y
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-10-10T08:27:48.201Z",
  • "updated_at": "2024-10-10T08:27:48.222Z",
  • "msrp_price": "46313.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "new",
  • "status": "stock",
  • "delivery_date": "2024-10-18",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 297114,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 401,
  • "video_url": null,
  • "owner_id": 116,
  • "color_id": 39,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "20153c",
  • "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
}

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 hnHuSjQwbextbbrxmC-E
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-10-10T08:27:48.430Z",
  • "updated_at": "2024-10-10T08:27:48.458Z",
  • "msrp_price": "31680.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": "reserved",
  • "delivery_date": "2024-10-23",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 128887,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 153,
  • "video_url": null,
  • "owner_id": 118,
  • "color_id": 41,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "16510d",
  • "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
}

Delete Vehicle

path Parameters
external_id
string
Example: 3c5f4901-d5d4-4216-8844-da5dd1855653
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 y22VcxwzHV3i86Gpjx1i
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-10-10T08:27:48.598Z",
  • "updated_at": "2024-10-10T08:27:48.598Z",
  • "msrp_price": "44823.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "new",
  • "status": "in_production",
  • "delivery_date": "2024-10-13",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 553032,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 240,
  • "video_url": null,
  • "owner_id": 121,
  • "color_id": 42,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "3c5f4901-d5d4-4216-8844-da5dd1855653",
  • "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
}

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 gZxMzt9GyTxCdJr7hBti

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 pUdPELzUZxQtSUB8FPFs
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 msUWemC_ySLpWtWL2TU8

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 ynP7hxuCPAbkGzwEEdiH
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 7aWzXHiHkZE-R8AEVjNY
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 gabDCGZLsmXsui_cwA7x
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": 361,
  • "msrp_price": "23969.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-10-10T08:27:46.778Z",
  • "updated_at": "2024-10-10T08:27:46.816Z",
  • "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-10-14",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 840416,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "video_url": null,
  • "features_standard": null,
  • "model_year": null,
  • "external_id": "2c3e8d",
  • "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
}

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 5Bi2B_wDc9sy8mrgH9K5
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 s7QpxhWeokoMFJi_oaRU
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 bb9zxm-ui24j8ghg1nqB
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 rwDpSFy3EDPdVPbqm11y
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-10-10T08:27:48.201Z",
  • "updated_at": "2024-10-10T08:27:48.222Z",
  • "msrp_price": "46313.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "new",
  • "status": "stock",
  • "delivery_date": "2024-10-18",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 297114,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 401,
  • "video_url": null,
  • "owner_id": 116,
  • "color_id": 39,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "20153c",
  • "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
}

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 hnHuSjQwbextbbrxmC-E
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-10-10T08:27:48.430Z",
  • "updated_at": "2024-10-10T08:27:48.458Z",
  • "msrp_price": "31680.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": "reserved",
  • "delivery_date": "2024-10-23",
  • "transmission": "manual",
  • "vin": null,
  • "mileage": 128887,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 153,
  • "video_url": null,
  • "owner_id": 118,
  • "color_id": 41,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "16510d",
  • "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
}

Delete Vehicle

path Parameters
external_id
string
Example: 3c5f4901-d5d4-4216-8844-da5dd1855653
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 y22VcxwzHV3i86Gpjx1i
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-10-10T08:27:48.598Z",
  • "updated_at": "2024-10-10T08:27:48.598Z",
  • "msrp_price": "44823.0",
  • "sale_price": null,
  • "monthly_price": null,
  • "long_description": "Id laborum perferendis eaque illo repellendus autem quo aut iste enim explicabo doloremque voluptas alias suscipit culpa hic aut non.",
  • "state": "new",
  • "status": "in_production",
  • "delivery_date": "2024-10-13",
  • "transmission": "auto",
  • "vin": null,
  • "mileage": 553032,
  • "engine_capacity": null,
  • "battery_capacity": null,
  • "engine_type": [
    ],
  • "power": 240,
  • "video_url": null,
  • "owner_id": 121,
  • "color_id": 42,
  • "features_standard": null,
  • "features_optional": null,
  • "model_year": null,
  • "external_id": "3c5f4901-d5d4-4216-8844-da5dd1855653",
  • "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
}

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: 347c8cad-3f14-4186-8c55-440288cae245
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: b9cc1bb3-9aa9-4a8f-9b15-a60501025195
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: 6578992d-a842-4246-9ce2-50366562faec
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: ce616325-8f1b-41ad-b519-de5c897c1e21
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: 0b231d23-158f-462d-8965-2abf18c60a89
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: d33cfe37-5380-42ee-a3e2-f1872ee5bff5
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: 46e23500-cd2e-469d-8a01-92aca4506aea
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: 9fe0cf1d-85c1-44ce-963d-e91e88f37409
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: e9716fa5-66df-4b26-9334-c2ae2f0f382a
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: fa73ed9c-9406-44ec-aea0-ed31c06ed41d
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: e3a8c615-1f26-460e-9f3f-32c568cd47c7
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: c38d0591-b809-47b8-9be6-7cf85da819bf
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: ac12a56c-8e04-40eb-8129-49cd96580557
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: 4aef6381-81ea-45ae-9678-1777f0fd6524
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: 474104ef-1000-4a14-8d34-0f4c71f965a8
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: 6401cbc6-7c03-4575-9ac6-c989b96a427b
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: 86daf8c7-43c0-45f0-b9ac-756b77063595
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: c4765112-3f87-4318-814e-143dbbeabf29
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: 9cd2e28c-145d-4ab2-94ef-859ba390c2ef
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: bde4f383-a990-439f-9036-fb2b48929ed5
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: 454eb17f-7cfb-45b0-876f-fca2f08fdbab
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: 824c780b-7f31-421a-bc4b-7ed1e37eb91c
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": "824c780b-7f31-421a-bc4b-7ed1e37eb91c"
}

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: Yk8TrwMBbwScfHmS
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: 85260d4b-482a-4910-9869-d6876fed633e
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": "Yk8TrwMBbwScfHmS",
  • "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: e5738c63-5369-4651-82a4-1de846611328
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: f519b0a2-e6d3-48c4-98cd-b0bbb6314c5e
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: 750ca386-d36a-4d47-874b-dc1dcc2cc42e
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: 4a42856c-ca22-46fb-bb8f-29805a2698f1
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: df0f106a-7aaa-4086-a0c1-a00297495652
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: b2fbf380-fbdc-4809-b5bf-363f1b16991c
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: 55
vehicle_id
number
Example: 230
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: 2bf0ba60-5d65-4693-a332-be6c5ce853a4
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: fc0275a9-19e9-41c1-af31-083deb663383
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: 0db5a719-a683-4164-81de-068987bf1475
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: adced92b-96ae-40d8-9970-8053c49e9c7c
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: 0c590ee2-ad83-4da9-ad53-1bf079ad03ba
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: 301d0811-5250-4dbf-bed0-bbe3f43e388a
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": [
    ]
}

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: 817f751d11c4aecc4a05f4fc
header Parameters
Accept
any
Example: application/json
X-Company-UUID
any
Example: 528e677a-b03b-4579-b597-e3a74877c90c
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": "817f751d11c4aecc4a05f4fc",
  • "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: a22dc60c-4e50-4ee5-ac6c-13008b241e11
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: 1fc11009-45ab-4610-b06a-8967f81a0c53
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:0x00007fa0b8cded48>\",\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: 85558289-8df8-4d90-b557-64ab49a122a7
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: a7bfb773-7656-48fa-a6e1-65d3d85fbde1
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: 51a871e7-3042-4c4a-aef5-562835a52d50
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: 71e5e07c-b0ce-44ac-a993-3ac1d6a22d9c
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: 4402756b-5675-4667-af93-0c9addc75d17
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: d4724375-c049-4565-b751-e033a0bf1fa6
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: 8ec3945a-6dbe-4a84-8e8a-2b5ba8c92c21
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: 77c9c26c-13c8-442a-adbb-a39c8676b94c
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: cd3c224a-fe06-4cb8-a981-97ead43a496f
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: 064e3954-f806-43fb-bafc-1240cdecd816
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: b342f87f-d35d-4689-a4e9-150689c26271
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: 8ec72d83-f168-4e88-b444-8832b75e29a5
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: 364,365
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 738bfadd-58a5-4ee8-afd8-3742c0021f36
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: 376,377
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 7419ac06-856b-4f0b-9795-a3972e397073
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: a4ec41e7-e7de-4aac-bb72-3776dcf736cc
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: 380
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 784eb5f0-43cf-48c6-9b81-c5ee2763a59b
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: 55b17fe2-964b-44d1-8955-91f2b4235857
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: c767050d-de33-4678-95dc-3fabc63edc17
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: 6c2cd3c7-5fee-4b05-b692-3c74e1553dd2
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: 497
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 326403c5-bf5f-4626-8241-451296ae301c
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: 502
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 4d412800-b9a1-4a2d-b0db-3ffd68253722
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: 49f57d61-afb0-4e4d-a098-48932c135f0e
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: 33d07417-2cf3-4d9b-975d-c018b476d121
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: 505
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: dc626e09-9024-4277-849b-56167e628fa3
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: 508
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bfb96fa8-a7d4-46d1-8a74-9a26a2679569
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: 516
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: eb62079f-2530-439f-82b0-bdba8bf56e2f
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: 507
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 2ebaf3a8-08d7-4e24-84f9-d24b314f6fda
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": {
    }
}

Fetch Vehicle data

path Parameters
uuid
string
Example: b0beafd8-5966-4a91-a922-5aa57319343b
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: f6f98f9c-daea-48e0-af25-71dbf866a6e3
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: 57aea988-77e7-41c2-ac9f-28bff5fad3e4
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: c37bf91d-cc94-495d-b629-745f57024d11
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: d42f5376-45d1-4d84-af6f-2235f586b9f4
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: 1e3563ac-d363-4998-8deb-11e489cfb5dd
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: f3afeabb-3738-49f3-a5da-1463d5d816b4
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: 380
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 784eb5f0-43cf-48c6-9b81-c5ee2763a59b
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: 55b17fe2-964b-44d1-8955-91f2b4235857
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: c767050d-de33-4678-95dc-3fabc63edc17
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: 6c2cd3c7-5fee-4b05-b692-3c74e1553dd2
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: 497
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 326403c5-bf5f-4626-8241-451296ae301c
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: 502
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 4d412800-b9a1-4a2d-b0db-3ffd68253722
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: 49f57d61-afb0-4e4d-a098-48932c135f0e
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: 33d07417-2cf3-4d9b-975d-c018b476d121
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: 505
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: dc626e09-9024-4277-849b-56167e628fa3
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: 508
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: bfb96fa8-a7d4-46d1-8a74-9a26a2679569
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: 516
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: eb62079f-2530-439f-82b0-bdba8bf56e2f
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: 507
header Parameters
Accept
any
Example: application/vnd.api+json
X-Company-UUID
any
Example: 2ebaf3a8-08d7-4e24-84f9-d24b314f6fda
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": {
    }
}

Fetch Vehicle data

path Parameters
uuid
string
Example: b0beafd8-5966-4a91-a922-5aa57319343b
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: 8a54bf33-9af9-449b-80bf-cdace488f535
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: 157ea2a5-36da-41c1-bc67-e20ac26b3dab
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: ea24634c-2106-4978-8469-b6c18d492c56
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: 2c1b5f76-2c64-4794-a003-21569ffbe3ce
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: 788a62f2-548f-48cd-a8a9-0e272569e037
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: fe50b831-c3b9-40dc-9642-aafc47dd9e34
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: 11481192-3999-4a04-8385-8aea30c3aa09
vehicle_id
number
Example: 219
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: 9551faa8-23dd-4e16-ad87-b3a1900f0e1b
vehicle_id
number
Example: 224
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: b5ad1840-c93e-4f34-8190-50f3b23f87ac
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
{
  • "b5ad1840-c93e-4f34-8190-50f3b23f87ac": [
    ]
}

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: 60198ff2-1066-4769-94a8-fe284840fc31
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: d454bf78-1033-494f-aa2e-6c66af9f1658
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: a311ea72-7190-4e3c-82df-6f829e7162e3
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: 0c29d777-93c4-46b6-99ef-101bcf21cfe2
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": [
    ]
}