# Pro Import API

# Description

The Pro Import API  allows you to manage your Blocket ads programmatically. This document describes how to create, update and delete ads, by invoking a REST API. It also describes how to get information about the state of your ads.

The Pro Import API should only be used for managing ads on Blocket and Bytbil, not for powering websites or similar. API users must keep a record of ads in their own system. Any changes made directly in Blocket Admin will not be reflected when retrieving the ad via the API. The API only exposes data that was created or updated through the API itself. For consistency and data integrity, all ad modifications should preferably be performed via the API.

Are you migrating from legacy file imports? Pay attention to the [chapter on migration](#migrating-to-the-api).

# Changelog

### 4.0.0

* V4 API introduced — new endpoints at `/v4/ad` (replaces `/v3/ad` for new integrations).
* Four vehicle categories re-enabled as **full registered vehicles** with complete field support (brand, model, mileage, powertrain, physics, equipment, etc.). These categories previously only supported simple ASL ads in V3:
  * 🛵 **Moped** (`1121`)
  * 🚐 **Camper / Motorhome** (`1102`)
  * 🏕️ **Caravan** (`1101`)
  * 🪝 **Trailer** (`1045`)
* New migration endpoint: `POST /v4/ad/{source_id}/migrate` — allows in-place migration of V3 legacy ads to V4 schema for the categories above, preserving ad ID and history.
* V4 endpoints are backward compatible: GET and DELETE work for both V3 and V4 ads. Compatible categories (Car, Motorcycle, etc.) are automatically converted to V4 when updated via `/v4/ad`.
* V3 endpoints remain fully supported — migration is optional.

### 3.1.0

* The API now supports categories for registered vehicles, previously only managed via Blocket Admin (or the legacy ftp file import). There are differences between the Blocket Admin categories and the Blocket only categories, these differences will be specified in this documentation and the OpenAPI documentation.  
* Improved state on Ad  
* Improved action and state on LogMessages  
* If you are using old file imports, you can read more about migrating in section [Migration from file imports via FTP](#migration-from-file-imports-via-ftp)  
* The API now supports new fields `warranty`, `return_policy`, `service_history`, `product_declaration`, `home_delivery`.

### 3.0.0

* API now represents Ads instead of "APIMessages"  
* All dates/times are now stored and returned in UTC  
* Renamed and restructured fields for creating ads  
* New hosting location and database \- separate history from earlier versions  
* New authentication system \- new tokens required  
* New states on Ad

# Caveats

* By using the API, you cannot publish ads outside registered vehicles manually and pay by invoice.  
* Ad body doesn’t support certain characters \- these will be replaced by “-”. Currently the affected characters are: “<”, “>”.  
* Terminology about *dealers* and *dealer\_groups* originates from mobility customers, but applies to other types of customers too.  
* Not all category specific fields are yet supported.

# OpenAPI documentation

The API documentation is available at the following URLs:

| Service | URL |
| :---- | :---- |
| Swagger | [https://api.blocket.se/pro-import-api/docs/swagger-ui/](https://api.blocket.se/pro-import-api/docs/swagger-ui/) |
| ReDoc | [https://api.blocket.se/pro-import-api/docs/redoc/](https://api.blocket.se/pro-import-api/docs/redoc/) |

# The workflow

The API allows you to create, update, renew and delete ads. After making a request it will be processed asynchronously, and you will be able to check the progress and result by looking at the action logs associated with the ad, and the final state of the ad.

The common procedure to create an ad is as follows:

1. Submit an ad by performing an HTTP POST to the API with all the ad data.  
2. Perform a HTTP GET to the API, in order to get the current status for the ad creation.

If everything went well, the response from the HTTP GET will contain info on all state transitions performed during the workflow execution (`logs` field), as well as a Blocket store ID and Blocket ad ID for the newly created Blocket ad and Bytbil ad ID for registered vehicles.

All **actions** made on the ad while processing it will have its own state. By inspecting the ad logs you will be able to track the actions made on the ad and the state of these. All actions start with the state processing and transition into done when completed. If there was an error while processing, the action will end up in state error.

The ad itself will have a **state** indicating if the ad was created or deleted. While this means that the ad was successfully created in the API, there could be more information in the ad logs which could indicate that there was an issue with a specific action.

##### **Ad actions**

| Name | Type | Description |
| :---- | :---- | :---- |
| `create` | string | Action for creating the ad within the API |
| `update` | string | Action for updating the ad |
| `bump` | string | Action for renewing the ad on marketplaces |
| `handle_media` | string | Action for handling media on the ad (uploading images, removing previous images etc) |
| `publish` | string | Action for publishing the ad on marketplaces  |
| `delete` | string | Action for removing the ad |
| `unpublish` | string | Action for unpublishing the ad on marketplaces |

##### 

##### **Ad log states**

| Name | Type | Description |
| :---- | :---- | :---- |
| `processing` | string | Ad action is being processed |
| `done` | string | Ad action completed successfully |
| `error` | string | There were error(s) while processing the action |

##### 

**Ad states**

| Name | Type | Description |
| :---- | :---- | :---- |
| `created` | string | Ad is created (possibly visible=false on marketplace, or other marketplace error could cause the ad not to be published, see log messages) |
| `deleted` | string | Ad is deleted |

##### 

# Authentication

All invocations to the API require a JWT token sent as a 'X-Auth-Token' request header. You can get one from customer support by contacting [butikssupport@blocket.se](mailto:butikssupport@blocket.se). The token can provide access for two types of scopes:

* `dealer_group` \- Provides access to a customer group  
* `dealer_code` \- Provides access to a single customer

API base URL V3 (legacy, still supported): **https://api.blocket.se/pro-import-api/v3/**

API base URL V4 (current, recommended for new integrations): **https://api.blocket.se/pro-import-api/v4/**

# Renewal of ads

It is also possible to **renew** a Blocket ad. This invocation is also asynchronous and initialized as described below, without any JSON body. A renewal of an ad will make it appear as new \- first in the listing (charges apply).

* `GET /v3/ad/{source_id}/bump`  
  initiates a renewal of a Blocket ad

For registered vehicles, you can choose to exclude either Blocket or Bytbil by passing exclude\_bytbil=true or exclude\_blocket=true.

# Endpoints

## /ad

The POST, PUT, PATCH and DELETE API invocations are asynchronous. This means you will get a prompt response, but the operation will be executed afterwards. The only synchronous operation is the GET invocation (except /bump and /pole_position).

### POST /ad \- Create an ad {#post-/ad---create-an-ad}

Use this endpoint to create an ad. The creation will happen asynchronously and you will need to check the status/result of the operation with a GET request.

Refer to the [OpenAPI documentation](#openapi-documentation) for more detailed information about all fields.

#### Noteworthy fields:

| Name | Type | Required | Description |
| :---- | :---- | :---- | :---- |
| `source_id` | string | Yes | Client’s reference ID. See `source_id` section. |
| `dealer_code` | string | If auth scope is dealer\_group | The dealer\_code for which to create the ad. Not needed if auth scope is dealer\_code. |
| `category_id` | int | Yes | See `category_id` section |
| `title` | string | Yes (except for registered vehicle categories) | Ad title |
| `body` | string | Yes | Ad body text |
| `price` | array of objects | Yes | See `price` section |
| `image_urls` | array of strings | No | See `image_urls` section |
| `url` | string | No | URL to page at the seller’s website with more info about the ad. |
| `url_title` | string | No | Deprecated and no longer used. |
| `video_url` | string | No | URL to Youtube or Vimeo video that is shown on the ad page. |
| `location` | object | No | See `location` section. |
| `contact` | object | Yes | See `contact` section |
| `category_fields` | object | Yes (except for non-registered vehicles) | See `category_fields` section |
| `dont_publish_on_failed_images` | boolean | No | `Default=false`. Set to true if you don’t want to publish the ad if any of the images have an error. |
| `product_declaration` | string | No | URL to a hosted “varudeklaration” in PDF format. |

##### `source_id`

Your ID for the ad. Each ad has to have an unique `source_id`, since it will be used to create, update, get and delete the ad.  
We recommend using a UUID here to ensure uniqueness.

##### `category_id`

> ✨ **V4 note:** Categories marked with **✨ V4** require the `/v4/ad` endpoint for full registered vehicle support (brand, model, mileage, powertrain, physics, etc.). These categories are only available as simple ads via the legacy `/v3/ad` endpoint.

| ID | Path / Name | Category specific fields |
| :---- | :---- | :---: |
| `1020` | Vehicles > Cars | Yes |
| `1021` | Vehicles > Vans | Yes |
| `1045` | Vehicles > Trailer | ✨ V4 |
| `1101` | Vehicles > Caravan | ✨ V4 |
| `1102` | Vehicles > Motorhome | ✨ V4 |
| `1121` | Vehicles > Mopeds & A-Tractors > Mopeds | ✨ V4 |
| `1140` | Vehicles > Motorcycle | Yes |
| `1143` | Vehicles > ATV | Yes |
| `1180` | Vehicles > Snowmobile | Yes |
| `1041` | Vehicles > Car Parts & Accessories > Car Stereo |  |
| `1042` | Vehicles > Car Parts & Accessories > Tyres & Rims |  |
| `1043` | Vehicles > Car Parts & Accessories > GPS |  |
| `1044` | Vehicles > Car Parts & Accessories > Spare Parts |  |
| `1046` | Vehicles > Car Parts & Accessories > Roof Boxes & Roof Racks |  |
| `1047` | Vehicles > Car Parts & Accessories > Other |  |
| `1061` | Vehicles > Boats > Motorboat | Yes |
| `1062` | Vehicles > Boats > Sailboat | Yes |
| `1063` | Vehicles > Boats > Inflatable / RIB Boat |  |
| `1064` | Vehicles > Boats > Dinghy / Rowboat |  |
| `1065` | Vehicles > Boats > Kayak / Canoe |  |
| `1066` | Vehicles > Boats > Jet Ski |  |
| `1067` | Vehicles > Boats > Other |  |
| `1081` | Vehicles > Boat Parts & Accessories > Engine & Propeller |  |
| `1082` | Vehicles > Boat Parts & Accessories > GPS & Navigation |  |
| `1083` | Vehicles > Boat Parts & Accessories > Moorings & Storage |  |
| `1084` | Vehicles > Boat Parts & Accessories > Trailer |  |
| `1085` | Vehicles > Boat Parts & Accessories > Other |  |
| `1103` | Vehicles > Caravans & Motorhomes > Accessories |  |
| `1122` | Vehicles > Mopeds & A-Tractors > A-Tractors | Yes |
| `1123` | Vehicles > Mopeds & A-Tractors > Accessories |  |
| `1161` | Vehicles > Motorcycle Parts & Accessories > Tyres & Rims |  |
| `1162` | Vehicles > Motorcycle Parts & Accessories > Spare Parts |  |
| `1163` | Vehicles > Motorcycle Parts & Accessories > Helmets / Protection / Clothing |  |
| `1164` | Vehicles > Motorcycle Parts & Accessories > Other |  |
| `1200` | Vehicles > Snowmobile Parts & Accessories |  |
| `1221` | Vehicles > Trucks, Machinery & Construction > Truck & Bus |  |
| `1222` | Vehicles > Forestry & Agricultural Machinery > Agricultural Machinery |  |
| `1223` | Vehicles > Trucks, Machinery & Construction > Construction Machinery |  |
| `1224` | Vehicles > Trucks, Machinery & Construction > Truck & Material Handling |  |
| `1225` | Vehicles > Forestry & Agricultural Machinery > Forestry Machinery |  |
| `1226` | Vehicles > Forestry & Agricultural Machinery > Ground Care Machinery |  |
| `2021` | Home > Building & Garden > Bathroom / WC / Sauna |  |
| `2022` | Home > Building & Garden > Building Materials |  |
| `2023` | Home > Building & Garden > Fireplace & Heating |  |
| `2024` | Home > Building & Garden > Kitchen |  |
| `2025` | Home > Building & Garden > Garden & Outdoor |  |
| `2026` | Home > Tools |  |
| `2027` | Home > Building & Garden > Other |  |
| `2028` | Home > Building & Garden > Garden Machinery |  |
| `2041` | Home > Furniture & Interior > Antiques & Art |  |
| `2042` | Home > Furniture & Interior > Lighting |  |
| `2043` | Home > Furniture & Interior > Tables & Chairs |  |
| `2044` | Home > Furniture & Interior > Rugs & Carpets |  |
| `2045` | Home > Furniture & Interior > Shelves & Storage |  |
| `2046` | Home > Furniture & Interior > Home Textiles & Décor |  |
| `2047` | Home > Furniture & Interior > Bed & Bedroom |  |
| `2048` | Home > Furniture & Interior > Sofa / Armchair / Suite |  |
| `2049` | Home > Furniture & Interior > TV & Stereo Furniture |  |
| `2050` | Home > Furniture & Interior > Other |  |
| `2061` | Home > Appliances > Dishwasher |  |
| `2062` | Home > Appliances > Fridge & Freezer |  |
| `2063` | Home > Appliances > Kitchen Accessories & Tableware |  |
| `2064` | Home > Appliances > Stove & Microwave |  |
| `2065` | Home > Appliances > Washing Machine & Dryer |  |
| `2066` | Home > Appliances > Other |  |
| `4020` | Personal > Children's Clothing & Shoes (not yet supported) |  |
| `4041` | Personal > Baby & Toys > Children's Furniture |  |
| `4042` | Personal > Baby & Toys > Prams & Accessories |  |
| `4043` | Personal > Baby & Toys > Car Seats |  |
| `4044` | Personal > Baby & Toys > Toys |  |
| `4045` | Personal > Baby & Toys > Other |  |
| `4061` | Personal > Accessories & Watches > Watches |  |
| `4062` | Personal > Accessories & Watches > Jewellery |  |
| `4063` | Personal > Accessories & Watches > Bags |  |
| `4064` | Personal > Accessories & Watches > Other |  |
| `4080` | Personal > Clothing & Shoes (not yet supported) |  |
| `5021` | Electronics > Computers & Gaming > Desktop Computers |  |
| `5022` | Electronics > Computers & Gaming > Laptops |  |
| `5023` | Electronics > Computers & Gaming > Computer Accessories & Software |  |
| `5024` | Electronics > Computers & Gaming > PC Games & Online Games |  |
| `5025` | Electronics > Computers & Gaming > Video Games |  |
| `5026` | Electronics > Computers & Gaming > Other |  |
| `5027` | Electronics > Computers & Gaming > Tablets |  |
| `5041` | Electronics > Audio & Video > Movies & Music |  |
| `5042` | Electronics > Audio & Video > Photo & Video Cameras |  |
| `5043` | Electronics > Audio & Video > MP3 Players |  |
| `5044` | Electronics > Audio & Video > Stereo & Surround |  |
| `5045` | Electronics > Audio & Video > Video & DVD Players |  |
| `5046` | Electronics > Audio & Video > TV & Projector |  |
| `5047` | Electronics > Audio & Video > Other |  |
| `5061` | Electronics > Phones & Accessories > Phones |  |
| `5062` | Electronics > Phones & Accessories > Accessories |  |
| `6021` | Leisure & Hobbies > Experiences & Entertainment > Concert |  |
| `6022` | Leisure & Hobbies > Experiences & Entertainment > Theatre & Show |  |
| `6023` | Leisure & Hobbies > Experiences & Entertainment > Gift Cards |  |
| `6025` | Leisure & Hobbies > Experiences & Entertainment > Sport |  |
| `6026` | Leisure & Hobbies > Experiences & Entertainment > Other |  |
| `6031` | Leisure & Hobbies > Experiences & Entertainment > Train Tickets |  |
| `6032` | Leisure & Hobbies > Experiences & Entertainment > Package, Charter & Theme Trips |  |
| `6034` | Leisure & Hobbies > Experiences & Entertainment > Flight Tickets |  |
| `6035` | Leisure & Hobbies > Experiences & Entertainment > Hotels & Accommodation |  |
| `6040` | Leisure & Hobbies > Books & Student Literature |  |
| `6061` | Leisure & Hobbies > Bicycles > Women's Bicycles |  |
| `6062` | Leisure & Hobbies > Bicycles > Men's Bicycles |  |
| `6063` | Leisure & Hobbies > Bicycles > Children's Bicycles |  |
| `6064` | Leisure & Hobbies > Bicycles > Mountain Bike |  |
| `6065` | Leisure & Hobbies > Bicycles > Road Bike |  |
| `6066` | Leisure & Hobbies > Bicycles > Other Bicycles |  |
| `6067` | Leisure & Hobbies > Bicycles > Accessories |  |
| `6081` | Leisure & Hobbies > Animals > Dog |  |
| `6082` | Leisure & Hobbies > Animals > Cat |  |
| `6083` | Leisure & Hobbies > Animals > Rodents & Rabbits |  |
| `6084` | Leisure & Hobbies > Animals > Reptile |  |
| `6085` | Leisure & Hobbies > Animals > Bird |  |
| `6086` | Leisure & Hobbies > Animals > Fish |  |
| `6087` | Leisure & Hobbies > Animals > Other Animals |  |
| `6088` | Leisure & Hobbies > Animals > Accessories |  |
| `6089` | Leisure & Hobbies > Animals > Cat & Dog Accessories |  |
| `6090` | Leisure & Hobbies > Animals > Farm Animals |  |
| `6101` | Leisure & Hobbies > Hobbies & Collectibles > Stamps & Coins |  |
| `6102` | Leisure & Hobbies > Hobbies & Collectibles > Hobby Vehicles |  |
| `6103` | Leisure & Hobbies > Hobbies & Collectibles > Remote Control & Model |  |
| `6104` | Leisure & Hobbies > Hobbies & Collectibles > Comic Books |  |
| `6105` | Leisure & Hobbies > Hobbies & Collectibles > Sewing Machine & Textiles |  |
| `6106` | Leisure & Hobbies > Hobbies & Collectibles > Historical Items |  |
| `6107` | Leisure & Hobbies > Hobbies & Collectibles > Other |  |
| `6121` | Leisure & Hobbies > Horses & Equestrian > Horses |  |
| `6122` | Leisure & Hobbies > Horses & Equestrian > Equipment |  |
| `6123` | Leisure & Hobbies > Horses & Equestrian > Feed & Stable |  |
| `6124` | Leisure & Hobbies > Horses & Equestrian > Co-rider & Feed Host |  |
| `6125` | Leisure & Hobbies > Horses & Equestrian > Trailer & Transport |  |
| `6126` | Leisure & Hobbies > Horses & Equestrian > Other |  |
| `6127` | Leisure & Hobbies > Horses & Equestrian > Pony |  |
| `6141` | Leisure & Hobbies > Hunting & Fishing > Hunting | Yes |
| `6142` | Leisure & Hobbies > Hunting & Fishing > Fishing |  |
| `6143` | Leisure & Hobbies > Hunting & Fishing > Other |  |
| `6161` | Leisure & Hobbies > Music Equipment > Guitar / Bass / Amplifier |  |
| `6162` | Leisure & Hobbies > Music Equipment > Piano & Keyboard |  |
| `6163` | Leisure & Hobbies > Music Equipment > Accordion |  |
| `6164` | Leisure & Hobbies > Music Equipment > Wind Instruments |  |
| `6165` | Leisure & Hobbies > Music Equipment > Drums & Percussion |  |
| `6166` | Leisure & Hobbies > Music Equipment > Studio & Stage Equipment |  |
| `6167` | Leisure & Hobbies > Music Equipment > Other |  |
| `6181` | Leisure & Hobbies > Sports & Leisure Equipment > Ball Sports |  |
| `6182` | Leisure & Hobbies > Sports & Leisure Equipment > Camping & Outdoor |  |
| `6183` | Leisure & Hobbies > Sports & Leisure Equipment > Diving & Water Sports |  |
| `6184` | Leisure & Hobbies > Sports & Leisure Equipment > Golf |  |
| `6185` | Leisure & Hobbies > Sports & Leisure Equipment > Fitness & Health |  |
| `6186` | Leisure & Hobbies > Sports & Leisure Equipment > Winter Sports |  |
| `6187` | Leisure & Hobbies > Sports & Leisure Equipment > Other |  |
| `7021` | Business > Business Transfers > Shop |  |
| `7022` | Business > Business Transfers > Domains & Websites |  |
| `7023` | Business > Business Transfers > Hair Salon |  |
| `7024` | Business > Business Transfers > Restaurant & Café |  |
| `7025` | Business > Business Transfers > Other |  |
| `7041` | Business > Fixtures & Machinery > Shop & Checkout |  |
| `7042` | Business > Fixtures & Machinery > Hair & Beauty Salon |  |
| `7043` | Business > Fixtures & Machinery > Office |  |
| `7044` | Business > Fixtures & Machinery > Industrial Machinery |  |
| `7045` | Business > Fixtures & Machinery > Restaurant & Café |  |
| `7046` | Business > Fixtures & Machinery > Wholesale & Liquidation Stock |  |
| `7047` | Business > Fixtures & Machinery > Other |  |
| `7061` | Business > Premises & Properties > Shops |  |
| `7062` | Business > Premises & Properties > Industry & Workshop |  |
| `7063` | Business > Premises & Properties > Warehouse & Storage |  |
| `7064` | Business > Premises & Properties > Office |  |
| `7066` | Business > Premises & Properties > Other |  |
| `8020` | Other > Wanted Ads |  |
| `8040` | Other > Other |  |

##### `price`

Array of objects representing prices for the ad. For registered vehicles, you can choose to send in price as leasing. Please see the [OpenAPI documentation](#openapi-documentation) for details.

Example value:

| `[     {"type": "list", "amount": 7000} ]` |
| :---- |

##### `image_urls`

Array of strings containing URLs to images for the ad. Accepted formats are JPG and PNG and you can send maximum 38 image URLs.

Example value:

| `[     "http://www.somewhere.com/my_image_1.jpg",     "http://www.somewhere.com/my_image_2.jpg" ]` |
| :---- |

#### 

##### `location`

Object with location parameters. There are three alternatives available for setting ad location. zip code, lkf or coordinates (latitude \+ longitude). Leave this field out or set it to `null` to make ad appear in all regions.

| Parameter name | Type | Required | Description |
| :---- | :---- | :---- | :---- |
| `zipcode` | string | No | zip/postal code without spaces |
| `lkf` | string | No | See `lkf` section |
| `latitude` | string | No | Decimal latitude |
| `longitude` | string | No | Decimal longitude |

Example value:

| `{     "latitude": 59.53485752244251,     "longitude": 16.71093897174057 }` |
| :---- |

Example value:

| `{     "lkf": "0680" }` |
| :---- |

Example value:

| `{     "zipcode": "12133" }` |
| :---- |

###### `lkf`

LKF is a Swedish abbreviation for "län, kommun, församling" (region, municipality, parish), and is a four or six digit area code (LK vs full LKF). Either the four or six digit version of the LKF can be used, where the latter increases location accuracy further and is particularly relevant to increase accuracy for ads located in Stockholm, Göteborg and Malmö. For example, the LK and full LKF for Vaksala in the city of Uppsala is:

`LK code: 0380`  
`LKF code: 038004`

Where the LK code 0380 refers to the greater Uppsala-area and the six digit LKF code 038004 refers to Vaksala specifically. A complete list of LKF codes can be found [here](https://www.scb.se/contentassets/13ec5841d80045498d960d456e87ea78/fors2020_justerad.xls).

Please note that Blocket does not show exact coordinates, but resolves to a predefined geographical area.

##### `contact`

Object with contact information. Will override store information.

Contact is not relevant for registered vehicles.

| Parameter name | Type | Required | Description |
| :---- | :---- | :---- | :---- |
| `name` | string | Yes | Sellers name |
| `phone` | string | Yes | Phone number (only digits) |
| `email` | string | Yes | Email address |

Example value:

| `{     "name": "Sir Henry Williamsworth III"     "phone": "0700000000",     "email": "email@example.com" }` |
| :---- |

#### 

##### `category_fields`

Some categories have extra fields available that only apply to that category, for example registration number and sales person.

Please refer to the [OpenAPI documentation](#openapi-documentation).

### GET /ad \- List ads

Use this endpoint to list your ad-requests and see progress/result of previous POST/PUT/DELETE operations. Each POST/PUT/DELETE on a certain `source_id` will appear as an individual entry. Log messages can be included with the help of the `include` field but only the last 100 messages will be provided. To get older log messages \- see the endpoint for getting ad logs.

#### Parameters

| Name | Type | Description |
| :---- | :---- | :---- |
| `state` | Filter | Values available: created deleted |
| `source_id` | Filter | Client’s reference ID |
| `source_id__in` | Filter | Comma separated list of IDs to include. |
| `dealer_code` | Filter | Customer identifier |
| `search` | Filter | Freetext search |
| `blocket_store_id` | Filter | Store ID on Blocket |
| `blocket_ad_id` | Filter | Ad ID on Blocket |
| `registration_number` | Filter | Registration number of the vehicle. Only works for registered vehicles. |
| `created__gt` | Filter | Format:"YYYY-MM-DD HH:MM:SS" |
| `created__lt` | Filter | Format:"YYYY-MM-DD HH:MM:SS" |
| `updated__gt` | Filter | Format:"YYYY-MM-DD HH:MM:SS" |
| `updated__lt` | Filter | Format:"YYYY-MM-DD HH:MM:SS" |
| `limit` | Setting | Limit results |
| `offset` | Setting | Offset results |
| `ordering` | Setting | Values available: \-created created updated \-updated |
| `fields` | Setting | Comma separated fields to include in response |
| `include` | Setting | Comma separated fields to include other than the defaults. Fields excluded by default in this endpoint are: `log.` **Note: only the 100 latest log messages are included.** To view more messages use `/ad/source_id/log` endpoint. |

#### Example request

| `GET /ad?state=deleted` |
| :---- |

## 

### GET /ad/`<source_id>`

Look up a specific ad based on source ID. Only includes the last 100 log messages.

### GET /ad/`<source_id>`/log

Look up all log messages for an ad.. This endpoint provides a paginated list of all log messages for an ad.

| `GET /ad/{source_id}/log` |
| :---- |

#### Parameters

| Name | Type | Description |
| :---- | :---- | :---- |
| `action` | Filter | Values available: create update bump delete handle\_media publish unpublish |
| `state` | Filter | Values available: processing done error |
| `limit` | Setting | Limit results |
| `offset` | Setting | Offset results |
| `ordering` | Setting | Values available: \-created created |

### PUT /ad/`<source_id>` \- Update an ad

Use this endpoint to update an ad. Same signature as ad creation except for `source_id` which is provided in the path instead of the body. The ads contents will be updated but it will not appear as new. To renew an ad \- see /ad/`<source_id>`/bump endpoint.

You can use the PUT method to revive a deleted ad in unregistered vehicle categories (not e.g. cars & vans)..

### PATCH /ad/`<source_id>` \- Update part of an ad

Use this endpoint to update part of an ad. Same signature as ad creation except for `source_id` which is provided in the path instead of the body. The ads contents will be updated but it will not appear as new. To renew an ad \- see /ad/`<source_id>`/bump endpoint.

You can use the PATCH method to revive a deleted ad in unregistered vehicle categories (not e.g. cars & vans).

### DELETE /ad/`<source_id>` \- Delete an ad

Request to delete an ad. The result / progress can be obtained just like for create/update requests \- by performing a GET request on the `source_id`.

### GET /ad/`<source_id>`/bump \- Renew an ad

Calling this endpoint will make the ad appear as new again. Charges apply.

### GET /ad/`<source_id>`/pole_position \- Set pole position on an ad

Calling this endpoint will make the ad appear first in the search result. If several ads with pole position match the end user’s search filter, only one is shown. Pole position lasts for 3 days. Currently, ads on pole position cannot be bumped/renewed. More information [here](https://www.blocket.se/for-foretag/fordon/pole-position). Charges apply. 

## /vehicle

Use this endpoint to find which values are available for certain fields within registered vehicles. Refer to the [OpenAPI documentation](#openapi-documentation) for more detailed information.

GET /v3/vehicle/brands  
Retrieve brands for registered vehicles.

GET /v3/vehicle/models  
Retrieve models for a brand for registered vehicles.

### GET /v3/vehicle/body\_types

Retrieve body types for registered vehicles.

GET /v3/vehicle/fuels  
Retrieve fuels for registered vehicles.

# V4 API — New in Version 4

> **Use `/v4/ad` for new integrations.** All V3 endpoints (`/v3/ad`) remain fully supported.

## V4 Endpoint Overview

| Method | Path | Description |
| :---- | :---- | :---- |
| `POST` | `/v4/ad` | Create new ad (V4) |
| `GET` | `/v4/ad` | List ads (returns both V3 and V4 ads) |
| `GET` | `/v4/ad/{source_id}` | Get specific ad |
| `PUT` | `/v4/ad/{source_id}` | Full update |
| `PATCH` | `/v4/ad/{source_id}` | Partial update |
| `DELETE` | `/v4/ad/{source_id}` | Delete ad |
| `GET` | `/v4/ad/{source_id}/log` | Get ad logs |
| `POST` | `/v4/ad/{source_id}/migrate` | Migrate V3 ad to V4 |

## V4 Backward Compatibility

When using V4 endpoints on existing V3 ads:

| Operation | Compatible categories (Car, MC, etc.) | Incompatible categories (Moped, Camper, Caravan, Trailer) |
| :---- | :---- | :---- |
| **GET** | ✅ Works | ✅ Works |
| **DELETE** | ✅ Works | ✅ Works |
| **PUT / PATCH** | ✅ Auto-converts ad to V4 | ❌ Blocked — use `/migrate` endpoint |
| **POST (new)** | ✅ Creates V4 ad | ✅ Creates V4 ad with full field support |

## POST /v4/ad/`<source_id>`/migrate — Migrate V3 ad to V4

Use this endpoint to convert an existing V3 ad for Moped, Camper, Caravan or Trailer to a V4 ad **in-place**, without deleting it. The ad ID, source ID and history are preserved.

**When to use this endpoint:**

* You have an existing V3 ad for Moped (`1121`), Camper (`1102`), Caravan (`1101`) or Trailer (`1045`)
* You want to keep the same `source_id` and ad ID
* You want to add full vehicle data (brand, model, mileage, powertrain, etc.)

**Alternative:** You can also `DELETE` the V3 ad and `POST` a new V4 ad with the same `source_id` — this achieves the same result but does not preserve the original ad ID.

**Requires:** A complete V4 payload with all required `category_fields` for the category.

# Migration from file imports via FTP {#migration-from-file-imports-via-ftp}

The Import-API is very different from the legacy file imports where you send a file via FTP with the entire stock and wait for that file to be imported. The imports via FTP require you to send all the stock information on every update, and images are sent separately either as raw image files or via URLs in json-files. 

The API is a modern replacement to the previous file imports via FTP which is now being deprecated.

### **Test Environment**

There is no separate test environment. All API integrations must be developed and tested directly in the **production environment**.

To avoid publishing test ads on the marketplaces, you can set `visible: false` when creating ads. These ads will:

* Not be published on any marketplaces  
* Be accessible only within **Blocket Admin** and the **API**  
* **Not incur any charges**, as they are not publicly listed on the marketplaces

This approach allows you to test the integration during development without impacting live listings.

There is also a /v3/ad/validate endpoint that can be used to validate the input data, without saving anything.

### **Migrating to the API** {#migrating-to-the-api}

When migrating to the API, all existing ads currently managed in **Blocket Admin** must be re-submitted to the API using `POST` requests. This is necessary to establish the `source_id` relationship between the API-managed ad and the corresponding ad in Blocket Admin. Matching is based on licence plate, including Q based licence plates allocated automatically when the ad was created manually in Blocket Admin.

During this initial migration, you are also required to provide a list of image URLs via the `image_urls` field. Below follows a short recap and caveats you need to be aware of when migrating from legacy file imports or building a new integration.

**Source ID**

As described in the documentation above, every ad needs a source_id, this is your identifier when updating or deleting the ad after creation. The source_id needs to be unique within the customer it belongs to. The source_id can be any string of choice.

**Images**

As described in the documentation above, images are sent as a list of URLs in the ad payload under the field named image\_urls. The images will be downloaded by the API when creating or updating the ad. There is no possibility to upload raw image files to the API, you need to provide URLs to your own publicly accessible image storage or CDN.

The sort order of the images is the order of the image\_urls list. Every time you want to update images, you need to send the complete list of image\_urls and it will replace the previous list. Already uploaded images that match an existing checksum will be internally reused. 

Example:

“image\_urls” : \[

    “https://cdn.io/image1/”,  
    “https://cdn.io/image2/”,  
    “https://cdn.io/image3/”,  
\]

#### **Overwriting Data**

All data submitted through the API will **overwrite** the existing data in Blocket Admin. Unlike the previous file import system, there is **no concept of import locks**—any ad data submitted via the API is considered the source of truth.

#### **One-Way Sync**

Any changes made directly in Blocket Admin **will not** be reflected when retrieving the ad via the API. The API only exposes data that was created or updated through the API itself. For consistency and data integrity, **all ad modifications should preferably be performed via the API**.

#### **File Imports Deprecated**

Once the migration to the API is complete, the legacy file import functionality will be **shut down**.

#### **Step by step guide**

1. Stop sending legacy import files.  
2. Send a POST request with source_id, licence\_plate etc for each existing ad to connect the existing ads to the API. See [POST /ad section](#post-/ad---create-an-ad).  
3. Manage all existing and new ads through the API.