# API

The VirtualCar360 API allows customers to retrieve vehicle gallery data, image sets, hotspots and video links. It is intended for integrations that want to use VirtualCar360 data in a custom website, CRM, administrative system, classified portal or dealer tool.

The API can be used to:

- build offer listings,
- retrieve vehicle photos for a website,
- archive vehicle photos,
- import gallery data into administrative systems,
- integrate with CRM or DMS systems,
- feed external tools such as WebWizard or other customer systems,
- retrieve video links,
- retrieve hotspots and additional photos,
- build a custom vehicle gallery interface.


Tip
If you only want to embed a ready-made vehicle presentation, use the Player. If you want to retrieve photos and build a custom view, use the API.

## Base URL

Production API base URL:

```txt
https://img-out.virtualcar360.pl/api/v6.0/virtual-360
```

## Authorization

API access requires the `key` query string parameter.

```txt
https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=YOUR_API_KEY
```

The key can be assigned to one location or multiple locations as a group key. See **API Authorization** for details.

Security
For direct API calls, do not expose the API key in frontend code. Use a backend proxy whenever possible.

## Core concepts

### Gallery

A gallery represents a vehicle photo session. A single vehicle can have more than one gallery, for example when it was photographed at different times or in different standards.

A basic gallery record contains:

- `id`,
- `name`,
- `vin`,
- `numberPlates`,
- `createdAt`,
- `type`.


The `id` field is used as `carId` in the `/image-set` endpoint.

### Image set

An image set contains the data needed to build a custom gallery view, including photo URLs, 1080p photos, hotspots, video information and metadata.

### Hotspot

A hotspot marks a specific point on a vehicle photo. It can indicate an equipment element, damage, scratch, body detail or inspection feature.

### Video

If video is available for a gallery, the API can return the `video` field. This field may be a JSON string containing links to platforms such as Vimeo and YouTube.

## Endpoints

| Method | Endpoint | Description |
|  --- | --- | --- |
| `GET` | `/vin/{vin}` | Retrieves the latest gallery by VIN. |
| `GET` | `/numberplates/{numberplates}` | Retrieves the latest gallery by registration number. |
| `GET` | `/list/vin/{vin}` | Retrieves all galleries assigned to a VIN. |
| `GET` | `/list/numberplates/{numberplates}` | Retrieves all galleries assigned to a registration number. |
| `GET` | `/image-set` | Retrieves image sets, hotspots and video data for a gallery. |
| `GET` | `/idsWithNames` | Searches galleries by filters such as VIN, registration number and creation date. |
| `POST` | `/add-announcement` | Adds an announcement. Intended for integrations exporting data. |


## API Reference grouping

The OpenAPI file groups endpoints according to the documentation structure:

| API Reference section | Endpoints | Use case |
|  --- | --- | --- |
| **Gallery search** | `/idsWithNames` | Search galleries by filters. |
| **Gallery lists** | `/list/vin/{vin}`, `/list/numberplates/{numberplates}` | Retrieve all galleries for a vehicle. |
| **Latest gallery** | `/vin/{vin}`, `/numberplates/{numberplates}` | Retrieve the latest gallery for a vehicle. |
| **Images** | `/image-set` | Retrieve image sets, hotspots, video data and 1080p photos. |
| **Announcements** | `/add-announcement` | Export or add announcement data. |


## Typical API flow

### Step 1 — Get the latest gallery

By VIN:

```http
GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=YOUR_API_KEY
```

By registration number:

```http
GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/numberplates/WW4433E?key=YOUR_API_KEY
```

Example response:

```json
{
  "id": 10209937,
  "name": "WBA1234567890_skodaplus",
  "vin": "WBA1234567890",
  "numberPlates": "WW4433E",
  "createdAt": "2026-04-21T10:42:30.3038179",
  "type": "3000_2250_8_JPG_SKODAPLUS"
}
```

Use the returned `id` as `carId` in the next request.

### Step 2 — Retrieve image sets

```http
GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/image-set?carId=10209937&key=YOUR_API_KEY
```

The endpoint returns the full gallery object with image sets, hotspots and video links.

## Pagination and sorting

List endpoints support:

| Parameter | Description |
|  --- | --- |
| `Sorting` | Sort direction. `1` means ASC, `-1` means DESC. |
| `Page` | Page number. Default: `1`. |
| `PageSize` | Number of results per page. Range: `1–100`, default: `20`. |


## The `/image-set` endpoint

`/image-set` is the main endpoint for retrieving photos and gallery data.

It can return:

- `id`,
- `vin`,
- `numberPlates`,
- `type`,
- `inspection`,
- `video`,
- `hotspots`,
- `carImageSets`,
- `carImageSets1080p`.


## The `type` field

The `type` field describes the technical photo standard. Example:

```txt
3000_2250_8_JPG_SKODAPLUS
```

It can include photo width, height, number of photos, file format and standard name.

## Error codes

| Code | Meaning |
|  --- | --- |
| `200` | Request completed successfully. |
| `400` | Invalid request parameters. |
| `404` | No data found for the provided criteria. |
| `500` | Server error. Contact VirtualCar360 support. |


## Best practices

- Use a backend proxy and do not expose the API key in frontend code.
- Use `/image-set` directly when `carId` is known.
- Use VIN or registration number to find the latest gallery first.
- Use pagination for list endpoints.
- Handle missing video and hotspots.
- Cache API responses in your backend when possible.