Advertisement

Advertisements or ads are the main resource on the Marktplaats API. You can create, update and delete them, change the status and get a list of your ads. Through the API you only have access to your own ads. Ads from other advertisers are not accessible.

How to know an advertisement json model

The json model to POST an advertisement consists of two parts, common fields and category-specific fields. You can find an overview of the common fields (such as price, and sellerName) below.

To look up the category-specific fields, please do the v1/categories call to get the Ids of the category you want to post in. For example, for Volkswagen, you will find that the Ids are 91/157, 91 being the level-1 id for cars, and 157 the level-2 for Volkswagen.

Next, you can do an attributes call for this category: v1/categories/91/157/attributes. The attributes you can supply in the json are those with “writable”: true (for posting a new advertisement) and “updateable”: true (for updating an advertisement).

The endpoint will also tell you acceptable values for each attribute. As an example, on category 157 you will find trim as a writable attribute. This means that in your advertisement json, you can simply add a json field “trim” : “trim goes here”.

It is not necessary to call the attributes endpoint for every ad post. We only change attributes a few times per year, and usually in a backwards compatible way (e.g. add new car models). If we make a backwards incompatible change or another change that will have major impact on your business we will inform you by e-mail ahead of time.

User-dependent attribute statuses

Please be aware that the status of certain attributes may depend on the user.

For many categories, the fields manufacturerTradename, manufacturerAddress, manufacturerEmail are required for any business user that is a DSA trader. This is the case if they allow on-platform transactions. This is a legal requirement due to the GPSR (General Product Safety Regulation). Sellers are legally responsible for providing correct data. To make things easier for yourself as an API partner, we recommend marking these fields required on your side for all of your users. That way, ad inserts/updates will keep working even if an existing user’s DSA trader status changes.

If you want to know which fields are mandatory for a specific user, make sure to call the attributes endpoint with their USER token rather than a CLIENT token.

Automotive advertisements

Advertisements placed in any of the automotive categories are special in that, if a valid license plate is provided, they will be enriched with data from a third party partner after posting. This process is asynchronous and it can take some time for this data to show up as attributes of an advertisement.

If you provide the values for these fields yourself in the HTTP POST then this data is used instead of the data we receive as part of the enrichment process.

Please note that specifically for cars, we have some fields that are editable only by API partners that are configured on our side as “Car Dealer API partner”. If you are signed up as an API partner for other categories and would like to start advertising cars, please contact us.

Another important point:

• The categoryId field will decide in which brand category your ad is posted
• the model attribute contains a different list of acceptable values for each brand and decides the model search filter.
• The makeDescription and modelDescription are free text fields that will show on the advertisement page but are not used for search.

For the best visibility of ads, we recommend you supply all of them.

The available attributes are somewhat different for vans (bestelauto’s), please check the attributes endpoint for details.

Fields

Each advertisement has a unique identifier by which it can be retrieved and a set of required fields, like title, description (or translations for multilingual Ads) and priceModel. An advertisement also has a set of optional fields, which are depending on the categoryId in which the advertisement is placed. To get a list of the optional fields for an advertisement (which are not listed below), the category-attributes could be used.

field	type	constraints	default	Req	W	U
itemId	string	–		no	no	no
categoryId	int	positive		yes	yes	yes
title	string	max. 60 chars		yes	yes	yes
description	string	max. 65535 chars		yes	yes	yes
startDate	ISO 8601 string	–		no	no	no
closeDate	ISO 8601 string	–		no	no	no
priceModel	Price Model	one of supported price models.		yes	yes	yes
licensePlate	string	6 chars or 8 chars		no	yes	yes
seller	object	–		no	yes	yes
seller.sellerId	int	positive		no	no	no
seller.sellerName	string	max. 30 chars (60 for API partner)		no	yes	yes
seller.phoneNumber	string	max. 12 chars, has to be valid		no	yes	yes
seller.acceptPaypal	boolean	true or false (default false)		no	yes	yes
seller.kvkNumber	long	a positive number greater than 0		no	yes	yes
seller.vestiging	string	can contain numbers and letters		no	yes	yes
seller.showEmail	boolean	true or false (default true)		no	yes	yes
location	object	–		yes	yes	no
location.postcode	string	max. 6 chars		yes	yes	no
location.cityName	string	max. 60 chars (not all chars allowed)		no	yes	no
url	string	valid URL		no	yes	yes
stickerText	string	max 18 chars		no	yes	yes
videoUrl	string	max 150 chars		no	yes	yes
showOnMap	boolean	true or false (default false)		no	yes	yes
status	string	online or deactivated		no	no	no
<property>	undefined	–		no	yes	yes
partNumber	string	max 25 chars		no	yes	yes
renewPossible	boolean	–		no	no	no
locale	string	for Marktplaats only nl-NL allowed, for 2dehands: nl-BE and fr-BE allowed		no	yes	yes
reserved	boolean	–		no	yes	yes

itemId

Unique reference to the Marktplaats advertisement, needs to be omitted in a POST action.

categoryId

The category in which the advertisement is placed.

An integer value from the category list. Must be a L2 category (see categories).

In some cases the categoryId can be updated as well as written.

The rules for moving a category are:

• An L2 category can only be moved within the same L1
• MUST have a special privilege allowing category changes in the system
• Can only change the category of an advertisement once
• Can only change it in a specific time period (usually 7 days) of the startdate of the advertisement

title

Any string with a minimum of 3 characters, up to 60 characters. Urls are not allowed as part of the title.

description

The description field of the ad. All HTML elements except for the ones below will be removed:

<i> <em> <b> <strong> <ul> <li> <u> <br/>

The description can also contain Wiki-formatting. It is recommended to not rely on this feature, since it is probably going to change in the future. But since it has impact on how the description is rendered, it is mentioned here.

We support the following Wikiformatting:

• Bold: **bold**

• Italic: //italic//

• Underline: __underline__

• Lists:

  * item1
  * item2
  

The result of this support is that it is currently not possible to add the character combinations needed for the Wiki formatting literally in the description. So for example, there is currently no way of including **hi** in a description, because this will be rendered as bold.

startDate

The date the advertisement has been published.

closeDate

The date the advertisement will be closed.

seller

The seller is inferred from the currently authenticated user.

seller.phoneNumber

A phone number has to meet the following requirements:

• Dutch phone numbers (mobile or land lines) have a maximum length of between 10 and 21 digits and should start with a 0.
• International phone numbers numbers should start with a ‘+’, followed by a countrynumber and should be between 8 and 19 digits.
• Phone numbers starting with 0909, 0906, 080x or 090x are not allowed.

Examples of valid phone number:

• 0615420879 - Valid Dutch mobile phone number.
• 0308767261 - Valid Dutch land line.
• 0971492918 - Valid Dutch mobile phone number for tablets and similar devices.
• +31615587981 - Valid Dutch phone number, with Dutch country code.
• +49699511440 - Valid German phone number, with country code.

Examples of invalid phone numbers:

• 0900998877 - Dutch information number.
• 0906292818 - Dutch chat number.
• 08001777 - Dutch information number.
• 061122 - Too short for being a valid number.
• 003233883399 - Invalid international number, it should start with + instead of 00.

seller.acceptPaypal

Accept bank or creditcard payments via PayPal

seller.showEmail

Enable/disable the ability of a user to contact seller by email

location.postcode

Either provide postcode or cityName, if both are provided, the cityName is used and postcode ignored. For example:

"location":{"postcode":"1097DN"}

Will result in an advertisement with the postcode 1097 DN and cityName “Amsterdam”.

"location":{"cityName":"Amsterdam"}

Will result in an advertisement with no postcode, cityName “Amsterdam” and extra remark “Buitenland” (Dutch for abroad).

"location":{"postcode":"1097DN","cityName":"Amsterdam"}

Will result in an advertisement with the postcode 1097 DN and cityName “Amsterdam”. This is because the provided cityName matches with the given postcode.

"location":{"postcode":"1097DN","cityName":"Utrecht"}

Will result in an advertisement with no postcode, cityName “Utrect” and extra remark “Buitenland” (Dutch for abroad). This is because the postcode does not match the given cityName, which will cause the system to ignore the postcode and take the supplied cityName.

The examples above work for both POST request as well as PUT request. When updating an advertisement using PATCH the most reliable way to change the postcode is using the following request:

[
    {"op":"remove", "path":"/location/cityName"},
    {"op":"replace","path":"/location/postcode","value":"8388MA"}
]

This will first remove the cityName, followed by updating the postcode. The system will then automatically add the correct cityName to the advertisement based on the given postcode.

location.cityName

Either provide postcode or cityName, if both are provided, the cityName is used and postcode ignored. This should only be done when the postcode is really unknown, since if only a cityName is provided, it is assumed that the location of the seller is abroad, and as a result, the advertisement will not be displayed on the map. The city may only contain letters, numbers, dashes, underscores and commas.

url

The URL to be displayed with the advertisement - Will only be displayed on Marktplaats if the URL feature is active. For the URL http, https and ftp protocols allowed. See Advertisement features and Buy advertisement feature.

stickerText

The custom “opvalsticker” (or “microtip”) to be displayed with the advertisement - Will only be displayed on Marktplaats if the microtip feature is active in the user’s bundle/package.

See Advertisement features

videoUrl

The URL of the video to be displayed with the advertisement. This can only be set when you are a dealer with the scope for dealer_video. When the dealer bought the video feature, it will be visible in the search pages that there is a video added to this advertisement. See Advertisement features and Buy advertisement feature. The URL should have marktplaats.carviewer.nl or marktplaats.movieplayer.nl as hostname.

showOnMap

Enable/disable the display of an advertisement on the map.

status

The status of the advertisement, deactivated advertisements are not visible on the site

<property>

Optional fields for an advertisement (attributes). The field name (key) of a property is always a camel cased word. For example: “jaarOorspr” for the field which is on the website displayed as: “Jaar (Oorspr.)”. A list of all the allowed fields and the type of the field can be retrieved by getting the category-attributes. The type of the field is depending on the field, see the list of allowed fields for the type.

partNumber

A manufacturer part number is a series of numbers and/or letters that has been given to a part by the manufacturer. An MPN identifies the part as belonging to and originating from that one manufacturer.

renewPossible

Shows if advertisement can be renewed with the renew operation.

locale

Locale (language) of the Ad. Mainly Title and description. This is only relevant for advertisements on the 2dehands platform.

reserved

Whether the ad has been reserved by the seller. This will replace the deprecated reserved Price Model Currently, if set to true, this will override the advertisement Price Model and set it to reserved.

Attributes (Optional fields)

Attributes are non-standard fields which are part of an advertisement and define properties of both the item for sale in the advertisement, as well as properties of the advertisement itself. Attributes are a normal field, where the value can either be a single string, an integer or an array of multiple strings.

Only a predefined set of attributes are possible for an advertisement in a given category. The values of an attribute are also predefined, and when writing an attribute, only the allowed values can be used. If a unknown value is used, an error will be returned.

As an API user, an attribute looks like a normal property of an advertisement. It is just a field with a key and a value, where the value can be an array of multiple values. It will never be a Json Object (complex type).

invalid-field-value

This code is used to indicate that the specified value is not valid. For fields which accept only a single value, this means that the given value is not part of the list of valid attribute values. For fields which accept multiple values, this means that one or more values are not valid.

For fields which are numeric, the specified value is not within the range of accepted values. The valid range is given in the value field of the error details.

Relations

name	availability	embedded	cardinality
mp:category	always	no	1
mp:seller	always	no	1
mp:advertisement-features	always	no	1
mp:advertisement-images	always	yes	1
mp:advertisement-statistics	always	no	1
mp:bids	always	no	1
mp:advertisement-transactions	always	no	1
mp:upcall-confirmations	Client credentials are provided and confirm_upcall has been granted	no	1
mp:advertisement-website-link	always	no	1

Reference

GET /v1/advertisements/{itemId}

Retrieve a single advertisement with the given itemId.

PATCH /v1/advertisements/{itemId}

Modify an existing advertisement, using the Json Patch format. See updating-advertisements for details.

PUT /v1/advertisements/{itemId}

Modify an existing advertisement, by supplying the entire updated advertisement Json. See updating-advertisements for details.

Errors

http	error code	description
404	advertisement-not-found	The advertisement with the provided itemId does not exist.
409	conflicting-state	When trying to patch an advertisement, this error is returned when the patch is not possible. For example, when trying to replace a field which does not exists.
400	incorrect-content-type	The used content-type for the request-body is not supported. At the moment we only support application/json
500	internal-server-error	Oops! Sorry, something went wrong on our side.
400	invalid-item-id	The item id provided does not match [a-z][0-9]*
400	invalid-json	The provided json is invalid (it is not json)
400	validation-failure	Validation of the advertisement failed. There should be more information in the field errors

Field errors

field	error code	error value	description
categoryId	ad-change-or-placement-not-allowed		Not allowed to change or place ad in category.
categoryId	category-change-not-allowed		Not allowed to change the category of an advertisement. Categories can only be changed when you have a special privilege, it can be changed only once and only within a specific time period since starting the advertisement
<field name>	field-not-editable		The specified field may not be edited by the current authenticated user.
<field name>	field-value-out-of-range	The allowed range for the field.	The specified field value is out of range. This only happens with numeric values.
<field name>	input-invalid	The allowed values.	The value for this field is invalid. Most of the time, this is because the field only accept a value of a predefined set of values or there are constraints on the value. For example, in the title field, URLs are not allowed.
<field name>	input-not-allowed		It is not allowed to set this field given the other fields. This message is returned when you try to set for example an ``askingPrice`` for a ``priceModel`` which doesn’t support that.
<field name>	input-not-numeric		It is not allowed to give a non-numeric value for fields which are numeric.
<field name>	input-too-long	The maximum allowed length.	The length of the supplied value exceeds the maximum allowed length for this field
<field name>	input-too-short	The minimum required length.	The length of the supplied value is less then the minimum required length for this field
<field name>	missing-required-field		A required field is missing or empty (while that is not allowed).
<field name>	too-many-field-values		There are too many values given for the field.
<field name>	unknown-field		The specified field does not exist or is not allowed for the given category.

Examples

Retrieving an advertisement :

Request :

GET /v1/advertisements/m1 HTTP/1.1
Host: api.marktplaats.nl

Response :

HTTP/1.1 200 OK
Content-Type: application/json

{
  "_links": {
    "self": { "href": "/v1/advertisements/m1" },
    "mp:advertisement-images": { "href": "/v1/advertisements/m1/images" }
  },
  "_embedded": {
    "mp:advertisement-images": {
      "_links": {
        "self": {
          "href": "/v1/advertisements/m4/images"
        }
      },
      "_embedded": {
        "mp:advertisement-image": [
          {
            "_links": {
              "self": {
                "href": "/v1/images/a64976eb-4adb-4af6-aa0f-3756740d8556"
              },
              "mp:image-blob": {
                "href": "/v1/images/a64976eb-4adb-4af6-aa0f-3756740d8556/{size}/blob",
                "templated": true
              },
              "mp:image-meta": {
                "href": "/v1/images/a64976eb-4adb-4af6-aa0f-3756740d8556/{size}/meta",
                "templated": true
              }
            },
            "imageId": 1764,
            "mediaId": "a64976eb-4adb-4af6-aa0f-3756740d8556",
            "status": "available"
          }
        ]
      }
    }
  },
  "description": "Brand new bike",
  "title": "test advertisement",
  "location": {
    "postcode": "1097DN"
  },
  "categoryId": 2,
  "priceModel" : {
    "modelType" : "fixed",
    "askingPrice" : 1550
  }
}

Deleting an advertisement :

Request :

DELETE /v1/advertisements/m1 HTTP/1.1
Host: api.marktplaats.nl

Response :

HTTP/1.1 200 OK

Updating an advertisement

In order to modify an existing advertisement, the PATCH or PUT method should be used on an advertisement.

If you use PUT, the body is the same as for the POST call. You need to provide the full advertisement.

For a PATCH, you only need to provide the fields you want to change. The body of the request should be a document according to the JSON Patch RFC. This means that even when only one field is changed, an array of objects should be supplied in the JSON, where the array will only contain a single element. We currently support the _operations_ replace, add, copy, move and remove for the following fields:

• title (remove and move are meaningless on these, because title is mandatory)
• description (remove and move are meaningless on these, because description is mandatory)
• priceModel
• all optional fields (attributes)

The test operation will not be supported for the time being.

It is possible to modify multiple fields with one PATCH request. This is done by sending an array with individual JSON Patch documents.

A successful PATCH call returns OK (200) with the advertisement as body.

Note

Officially, the content-type for a PATCH call which is formatted according to the JSON Patch RFC, should be application/json-patch+json. The Marktplaats API accepts this, but also accept PATCH calls with content-type application/json.

Example

Updating the title and description for an advertisement with itemId m1372:

Request :

PATCH /v1/advertisements/m1372 HTTP/1.1
Host: api.marktplaats.nl
Content-Length: 326
Content-Type: application/json-patch+json

[
  { "op":"replace", "path":"/title", "value":"new title" },
  { "op":"replace", "path":"/description", "value":"new description" },
  { "op":"replace", "path":"/priceModel/modelType", "value":"buy it now" },
  { "op":"add", "path":"/priceModel/shippingCosts", "value":695 },
  { "op":"replace", "path":"/seller/showEmail", "value":false }
]

Updating an advertisement by sending the full ad :

Request :

PUT /v1/advertisements/m1372 HTTP/1.1
Host: api.marktplaats.nl
Content-Type: application/json

{
  "description": "Brand new bike",
  "title": "test advertisement",
  "categoryId": 2,
  "location": {
    "postcode": "1097DN"
  },
  "priceModel" : {
    "modelType" : "fixed",
    "askingPrice" : 1550
  }
}