Overview

The Marktplaats API is a RESTful API to place ads on Marktplaats. You can interact with the api by navigating to The api explorer.

The content is provided in JSON format in UTF–8 encoding.

Accept Headers

Each call to resources of the Marktplaats API needs accept headers set. One part in that is the Media Type, as defined above. An additional part is necessary for allowing OAuth errors to be returned, in regular JSON. We recommend usage of accept headers as follows:

<Media Type>, application/json

In case of absence of the ‘application/json’ part, an OAuth error such as ‘401: Token Expired’ will not be possible to be returned since the accepted content type does not match, resulting in a ‘406: Not accepted’ error, obfuscating the underlying issue. Our examples will also demonstrate the recommended usage.

Authentication

Authentication is provided using OAuth2 to allow easy integration with existing libraries. For more information please have a look at the OAuth 2.0 website.

Dates and Times

All date/time values are specified in ISO 8601 Combined date and time in UTC format.

Prices and Currencies

All monetary amounts like prices and budgets are currently in Euros and stored as euro cents. Currencies are specified as three character ISO 4217 code.

HTTP Response Codes and Error Handling

To retrieve, update and delete resources with the Marktplaats API you use the standard HTTP verbs GET, PUT and DELETE. If the resource exists and the request was successful the server responds with 200 OK. If the resource does not exist the server responds with 404 Not Found.

To create a new resource you perform a POST request to which the server responds with 201 Created and a Location header containing the URL of the new resource.

All requests are validated before they are being executed by the server. If the validation fails the server responds with 400 Bad Request and an error response which contains a list of the errors. More information can be found under Error Handling.

Field definitions

Field definitions of resources follow a standard table pattern.

column name meaning
field the name of the field (when writing)
type the type of the field
constraints any constraints that apply to this field that you should know about
Req is this field required
W is this field writable (first time write (POST))
U is this field editable (PUT/PATCH)

HTTP PATCH Methods

When an HTTP PATCH method is called, the body should be formatted according to the JSON Patch RFC. The document structure of such a requests has the following structure:

[{"op":"<operation>", "path":"<path>", "value":"<value>"}]

The operation can either be add, remove, replace, move, copy or test. In the Marktplaats API, mainly add, remove, and replace are supported.

The path is the name of the field the operation should be applied to. For example, if one wants to change the _title_ field, the path should be /title. Note the beginning forward slash, which is an indication that this should be applied to the top level field of the document.

The value should be the value for the field. Value should only be specified for replace, add and test. For move and copy, a field called from should be used to specify the source of the operation.

Errors

http error code description
400 invalid-patch-operation The patch operation sent in the patch request is not valid. It should be one of ‘add’, ‘remove’, ‘replace’, ‘move’, ‘copy’, ‘test’