Ads
This endpoint can be used to get, create, update and remove advertisements
Reference
GET /ads/
Retrieve one or more ads associated with this client
POST /ads/
Create a new advertisement.
PUT /ads/
Update an existing advertisement.
PATCH /ads/
Patch an existing advertisement.
PATCH /ads/batch
Patch multiple advertisements
DELETE /ads/<adId>
Remove an advertisement. Please note: removing an advertisement does not unpublish the advertisement from any portal.
Use unpublish to remove an advertisement from one or more portals before deleting it from GoedGeplaatst.
DELETE /ads/batch/
Remove multiple advertisements. Please note: removing an advertisement does not unpublish the advertisement from any portal.
Use unpublish to remove an advertisement from one or more portals before deleting it from GoedGeplaatst.
General search parameters
| field | type | description/constraints | Req | W | U |
|---|---|---|---|---|---|
| useCache | boolean | Use API caching module | No | No | No |
| page | int | Show page x from resultset (default: 1) | No | No | No |
| itemsPerPage | int | Number of items per page (default 25) | No | No | No |
| Minimum: 1 item | |||||
| Maximum with simple = false: 25 items | |||||
| Maximum with simple = true: 500 items | |||||
| order | array | List of order-objects | No | No | No |
| adId | int / array / string | When searching for ads, adId can be: | No | No | No |
| - a single integer | |||||
| - an array of integers | |||||
| - a string value where adId's are seperated by a comma. | |||||
| simple | boolean | Only return a simple resultset containing the most essential information | No | No | No |
| Use this option to get a | |||||
| The following fields are not available in the resultset when simple is set to true: | |||||
| - attributes | |||||
| - contact | |||||
| - settings | |||||
| - images Only the primary image is returned in the resultset, not the complete imagelist. |
Fields order
| field | type | constraints | Req | W | U |
|---|---|---|---|---|---|
| field | string | Available options: | Yes | No | No |
| - price | |||||
| - closeDate | |||||
| - created (default) | |||||
| - updated | |||||
| - title | |||||
| descending | boolean | If set to true: ordering is done descending instead of ascending | No | No | No |
Fields
| field | type | constraints | Req | W | U | S | P |
|---|---|---|---|---|---|---|---|
| searchkeyword | string | search/filter by keyword | No | No | No | Yes | No |
| searchportal | string | search/filter by portal. Only show ads who are currently active on the specified portal. | No | No | No | Yes | No |
| Use an exclamation mark before the value to create an inverted search. | |||||||
| (e.g. !marktplaats: find items not published to marktplaats) | |||||||
| Available options: | |||||||
| - marktplaats | |||||||
| - tweedehands | |||||||
| - website | |||||||
| searchattributes | array | search/filter by a list of searchattributes. | No | No | No | Yes | No |
| Field: categoryId is mandatory when using this search-option. | |||||||
| searchmanufacturer | boolean | true: find ads where manufacturer has been set and attributes are available for the specified category | No | No | No | Yes | No |
| false: find ads where manufacturer has not been set and attributes are available for the specified category | |||||||
| adId | int | No | No | No | Yes | No | |
| created | datetime | creationdate of this ad | No | No | No | No | No |
| updated | datetime | updatedate of this ad | No | No | No | No | No |
| userId | int | The userId for this advertisement | Yes | Yes | No | Yes | No |
| contactId | int | The contactId to use for this ad to overrule the default contact information associated with this user. | No | Yes | Yes | No | No |
| folderId | int | The folder to use for this ad. | No | Yes | Yes | Yes | No |
| status | string | Available options: | Yes | Yes | Yes | Yes | Yes |
| - draft | |||||||
| - concept | |||||||
| - active (default) | |||||||
| - archive | |||||||
| Please note: status archive does not unpublish the advertisement from any portal. | |||||||
| Use unpublish to remove an advertisement from one or more portals before moving it to archive. | |||||||
| externalAdId | int | The external adid in the clients backend Mandatory for partners only. |
Yes | Yes | No | No | No |
| type | string | Available options: | Yes | Yes | Yes | Yes | No |
| - supply | |||||||
| - demand | |||||||
| title | string | min 5 characters max 60 characters |
Yes | Yes | Yes | Yes | No |
| imagetext | string | Imagetext to be displayed in the primary image. Max. 18 characters. Marktplaats/Tweedehands: opvalsticker |
No | Yes | Yes | No | No |
| description | text | Description of the advertisement. | Yes | Yes | Yes | Yes | No |
| min 5 characters | |||||||
| max 65.536 characters | |||||||
| Available HTML tags: | |||||||
<p> </p> |
|||||||
<b> </b> |
|||||||
<strong> </strong> |
|||||||
<u> </u> |
|||||||
<ul> </ul> |
|||||||
<li> </li> |
|||||||
<br /> <br/> |
|||||||
| groupId | int | The main-categoryId. | No | No | No | Yes | No |
| groupDescription | string | The description of the group | No | No | No | Yes | No |
| categoryId | int | The categoryId. See also: categories | Yes | Yes | No | Yes | No |
| categoryDescription | string | The description of the category | No | No | No | Yes | No |
| attributes | array | List of attributes-objects For a list of available attributes see chapter: Attributes |
Yes | Yes | Yes | No | No |
| url | string | Direct link to this object on a website. | No | Yes | Yes | No | No |
| price | object | The price-type | Yes | Yes | Yes | No | No |
| prices | object | prices-object for adding this ad to the available portals. | No | No | No | No | No |
| Not to be confused with the previous field 'price' which are the prices of the object for sale. | |||||||
| settings | array | List of settings-objects for this advertisement. | No | Yes | Yes | No | No |
| images | array | List of image-objects | No | No | No | No | No |
| misc | object | miscellaneous fields | No | Yes | Yes | No | No |
Fields searchattributes
| field | type | constraints | Req | W | U |
|---|---|---|---|---|---|
| portal | string | Use attributes of the following portal to search/filter | Yes | No | No |
| Available options: | |||||
| - marktplaats | |||||
| - tweedehands | |||||
| locale | string | nl_NL | Yes | No | No |
| key | string | The keyfield | Yes | No | No |
| value_equals | any | Value must match exactly | Yes/No | No | No |
| value_equals_list | array | Values must match exactly. | Yes/No | No | No |
Use with attributes like accessories where multiple options can be selected |
|||||
| value_lessequal | int/float | Value must be equal or less then the provided value | Yes/No | No | No |
| value_greaterequal | int/float | Value must be equal greater then the provided value | Yes/No | No | No |
| Either value_equals is mandatory or value_lessequal or value_greaterequal | |||||
| Use both value_lessequal and value_greaterequal to search for items matching a range of values. |
Fields: attributes
| field | type | constraints | Req | W | U |
|---|---|---|---|---|---|
| portal | string | Yes | Yes | Yes | |
| locale | string | Yes | Yes | Yes | |
| values | array | List of attribute-objects to submit | Yes | Yes | Yes |
Fields: attribute
| field | type | constraints | Req | W | U |
|---|---|---|---|---|---|
| key | string | Yes | Yes | Yes | |
| value | string | Yes | Yes | Yes | |
| label | string | No | No | No |
Fields price
From April 17th 2025 Marktplaats and 2dehands will remove the following price models:
- to be discussed
- by request
- trade
- buy it now
The remaining (valid) price-models are:
- fixed
- bidding
- see description
- reserved
Existing advertisements using the absolete price models will be converted to see description
New advertisements with these absolete price models will be rejected.
| field | type | constraints | Req | W | U |
|---|---|---|---|---|---|
| model | string | Available options: | Yes | Yes | Yes |
| - fixed | |||||
| - bidding | |||||
| - see description | |||||
| - reserved | |||||
| - to be discussed (removed) | |||||
| - by request (removed) | |||||
| - trade (removed) | |||||
| - buy it now (removed) | |||||
| price | int | The price in cents Mandatory for model: bidding, fixed and buy it now |
Yes/No | Yes | Yes |
| minimumBid | int | The minimal bid when model is set to: bidding | Yes/No | Yes | Yes |
| shippingCosts | int | The shipping costs when model is set to: buy it now | No | Yes | Yes |
| retail | int | The retail price of the object. | No | Yes | Yes |
Fields prices
| field | type | description/constraints | Req | W | U |
|---|---|---|---|---|---|
| marktplaats | array | List of price-objects | Yes | No | No |
| tweedehands | array | List of price-objects | No | No | No |
Fields settings
| field | type | constraints | Req | W | U |
|---|---|---|---|---|---|
| portal | string | Available options: | Yes | Yes | Yes |
| - marktplaats | |||||
| - tweedehands | |||||
| showcontact | boolean | Whether or not to enable contact-information in the advertisement | No | Yes | Yes |
| autoreplace | boolean | Auto re-publish the advertisement at the end of its duration. Default: false |
No | Yes | Yes |
| video | string | The URL to a video (mp4-format) to include in the advertisement | No | Yes | Yes |
Fields: misc
| field | type | constraints | Req | W | U |
|---|---|---|---|---|---|
| licensePlate | string | max 8 charachters. Only applicable for automotive categories. | No | Yes | Yes |
Example creating ad
Request
POST /ads/ HTTP/2
{
"status": "draft",
"externalAdId": 2,
"userId": 13023,
"contactId": 1,
"type": "supply",
"title": "Title for the new advertisement",
"imagetext": "AANBIEDING!",
"description": "Description of the advertisement with <strong>HTML Markup</strong><br>And some more information here...",
"categoryId": 2317,
"attributes": [
{
"portal": "marktplaats",
"locale": "nl_NL",
"values": [
{
"key": "numberOfSleepingPlaces",
"value": "tot en met 4"
},
{
"key": "bodyLength",
"value": "4 tot 5 meter"
},
{
"key": "constructionYear",
"value": 2016
},
{
"key": "accessories",
"value": "Disselslot"
},
{
"key": "accessories",
"value": "Ladder"
},
{
"key": "accessories",
"value": "Serviceluik"
},
{
"key": "accessories",
"value": "Zonnepaneel"
}
]
}
],
"url": "https://webshop-domain.nl/products/1000-product-title.html",
"price": {
"model": "fixed",
"price": 1995,
"minimumBid": 0,
"shippingCosts": 0,
"retail": 2500
},
"provider": {
"name": "Alternative companyname",
"address": "Streetname",
"houseNumber": "1A",
"postalCode": "1721PJ",
"city": "Broek op Langedijk",
"county": "NH",
"country": "NL",
"phone": "0226-111111"
},
"settings": [
{
"portal": "marktplaats",
"showcontact": true,
"autoreplace": false,
"video": "https://media.taggle.nl/238934/283928382.mp4"
}
],
"misc": {
"licensePlate": "TY-03-XS"
}
}
Response
{
"result": true,
"errors": [],
"data": {
"adId": 664608,
"created": "2024-09-06 11:45:54",
"updated": "2024-09-13 10:20:46",
"userId": 13023,
"contactId": 1,
"folderId": 0,
"status": "draft",
"externalAdId": 2,
"type": "supply",
"title": "Title for the new advertisement",
"imagetext": "AANBIEDING!",
"description": "Description of the advertisement with <strong>HTML Markup</strong><br>And some more information here...",
"groupId": 8,
"groupDescription": "Caravans en Kamperen",
"categoryId": 2317,
"categoryDescription": "Caravans",
"attributes": [
{
"portal": "marktplaats",
"locale": "nl_NL",
"attributes": [
{
"key": "numberOfSleepingPlaces",
"value": "tot en met 4",
"label": "Aantal slaapplaatsen"
},
{
"key": "bodyLength",
"value": "4 tot 5 meter",
"label": "Opbouw lengte"
},
{
"key": "constructionYear",
"value": 2016,
"label": "Bouwjaar"
},
{
"key": "accessories",
"value": "Disselslot",
"label": "Accessoires"
},
{
"key": "accessories",
"value": "Ladder",
"label": "Accessoires"
},
{
"key": "accessories",
"value": "Serviceluik",
"label": "Accessoires"
},
{
"key": "accessories",
"value": "Zonnepaneel",
"label": "Accessoires"
}
]
}
],
"url": "webshop-domain.nl/products/1000-product-title.html",
"price": {
"model": "fixed",
"price": 1995,
"minimumBid": 0,
"shippingCosts": 0,
"retailPrice": 2500
},
"prices": {
"marktplaats": [
{
"action": "plaatsen",
"priceInternal": 500,
"priceExternal": 1350,
"priceTotal": 1850,
"priceNative": 3203
},
{
"action": "omhoogplaatsen",
"priceInternal": 30,
"priceExternal": 170,
"priceTotal": 200,
"priceNative": 0
},
{
"action": "blikvanger",
"priceInternal": 30,
"priceExternal": 4360,
"priceTotal": 4390,
"priceNative": 0
},
{
"action": "dagtopper",
"priceInternal": 30,
"priceExternal": 200,
"priceTotal": 230,
"priceNative": 0
},
{
"action": "topadvertentie",
"priceInternal": 30,
"priceExternal": 1070,
"priceTotal": 1100,
"priceNative": 0
}
],
"tweedehands": [
{
"action": "plaatsen",
"priceInternal": 30,
"priceExternal": 1499,
"priceTotal": 1529,
"priceNative": 0
}
]
},
"contact": false,
"settings": [
{
"portal": "marktplaats",
"showcontact": true,
"autoreplace": false,
"video": "media.taggle.nl/238934/283928382.mp4"
},
{
"portal": "tweedehands",
"showcontact": false,
"autoreplace": false,
"video": ""
}
],
"images": false,
"portals": [
{
"portal": "marktplaats",
"publish": {
"pending": false,
"pendingDate": "0000-00-00 00:00:00",
"processing": false,
"processingDate": "0000-00-00 00:00:00",
"error": false,
"active": false,
"online": false,
"startDate": "0000-00-00 00:00:00",
"closeDate": "0000-00-00 00:00:00",
"remoteAdId": 0,
"clientResult": false,
"queueResult": false
},
"features": false
},
{
"portal": "tweedehands",
"publish": {
"pending": false,
"pendingDate": "0000-00-00 00:00:00",
"processing": false,
"processingDate": "0000-00-00 00:00:00",
"error": false,
"active": false,
"online": false,
"startDate": "0000-00-00 00:00:00",
"closeDate": "0000-00-00 00:00:00",
"remoteAdId": 0,
"clientResult": false,
"queueResult": false
},
"features": false
},
{
"portal": "website",
"publish": {
"pending": false,
"pendingDate": "0000-00-00 00:00:00",
"processing": false,
"processingDate": "0000-00-00 00:00:00",
"error": false,
"active": false,
"online": false,
"startDate": "0000-00-00 00:00:00",
"remoteAdId": 0
},
"features": false
}
],
"misc": {
"licensePlate": "TY-03-XS"
}
}
}
Example retrieving ads
Request
GET /rest/v1/ads/?userId=13023&status=draft&useCache=0&page=1&itemsPerPage=25&order%5B0%5D%5Bfield%5D=created&order%5B0%5D%5Bdescending%5D=1" HTTP/2
Response
{
"result": true,
"fromCache": false,
"totalItems": 2,
"totalInSet": 2,
"page": 1,
"itemsPerPage": 25,
"speed": 0.010261058807373047,
"data": [
{
"adId": 664608,
"created": "2024-09-06 11:45:54",
"updated": "2024-09-13 10:20:46",
"userId": 13023,
"contactId": 1,
"folderId": 0,
"status": "draft",
"externalAdId": 2,
"type": "supply",
"title": "Title for the new advertisement",
"imagetext": "AANBIEDING!",
"description": "Description of the advertisement with <strong>HTML Markup</strong><br>And some more information here...",
"groupId": 8,
"groupDescription": "Caravans en Kamperen",
"categoryId": 2317,
"categoryDescription": "Caravans",
"attributes": [
{
"portal": "marktplaats",
"locale": "nl_NL",
"attributes": [
{
"key": "numberOfSleepingPlaces",
"value": "tot en met 4",
"label": "Aantal slaapplaatsen"
},
{
"key": "bodyLength",
"value": "4 tot 5 meter",
"label": "Opbouw lengte"
},
{
"key": "constructionYear",
"value": 2016,
"label": "Bouwjaar"
},
{
"key": "accessories",
"value": "Disselslot",
"label": "Accessoires"
},
{
"key": "accessories",
"value": "Ladder",
"label": "Accessoires"
},
{
"key": "accessories",
"value": "Serviceluik",
"label": "Accessoires"
},
{
"key": "accessories",
"value": "Zonnepaneel",
"label": "Accessoires"
}
]
}
],
"url": "webshop-domain.nl/products/1000-product-title.html",
"price": {
"model": "fixed",
"price": 1995,
"minimumBid": 0,
"shippingCosts": 0,
"retailPrice": 2500
},
"prices": {
"marktplaats": [
{
"action": "plaatsen",
"priceInternal": 500,
"priceExternal": 1350,
"priceTotal": 1850,
"priceNative": 3203
},
{
"action": "omhoogplaatsen",
"priceInternal": 30,
"priceExternal": 170,
"priceTotal": 200,
"priceNative": 0
},
{
"action": "blikvanger",
"priceInternal": 30,
"priceExternal": 4360,
"priceTotal": 4390,
"priceNative": 0
},
{
"action": "dagtopper",
"priceInternal": 30,
"priceExternal": 200,
"priceTotal": 230,
"priceNative": 0
},
{
"action": "topadvertentie",
"priceInternal": 30,
"priceExternal": 1070,
"priceTotal": 1100,
"priceNative": 0
}
],
"tweedehands": [
{
"action": "plaatsen",
"priceInternal": 30,
"priceExternal": 1499,
"priceTotal": 1529,
"priceNative": 0
}
]
},
"contact": false,
"settings": [
{
"portal": "marktplaats",
"showcontact": true,
"autoreplace": false,
"video": "media.taggle.nl/238934/283928382.mp4"
},
{
"portal": "tweedehands",
"showcontact": false,
"autoreplace": false,
"video": ""
}
],
"images": false,
"misc": {
"licensePlate": "TY-03-XS"
}
},
{
"adId": 664607,
"created": "2024-09-06 11:17:39",
"updated": "2024-09-06 11:17:39",
"userId": 13023,
"contactId": 1,
"folderId": 0,
"status": "draft",
"externalAdId": 1,
"type": "supply",
"title": "Title for the new advertisement",
"imagetext": "AANBIEDING!",
"description": "Description of the advertisement with <strong>HTML Markup</strong><br>And some more information here...",
"groupId": 8,
"groupDescription": "Caravans en Kamperen",
"categoryId": 2317,
"categoryDescription": "Caravans",
"attributes": [
{
"portal": "marktplaats",
"locale": "nl_NL",
"attributes": [
{
"key": "numberOfSleepingPlaces",
"value": "tot en met 4",
"label": "Aantal slaapplaatsen"
},
{
"key": "bodyLength",
"value": "4 tot 5 meter",
"label": "Opbouw lengte"
},
{
"key": "constructionYear",
"value": 2016,
"label": "Bouwjaar"
},
{
"key": "accessories",
"value": "Disselslot",
"label": "Accessoires"
},
{
"key": "accessories",
"value": "Ladder",
"label": "Accessoires"
},
{
"key": "accessories",
"value": "Serviceluik",
"label": "Accessoires"
},
{
"key": "accessories",
"value": "Zonnepaneel",
"label": "Accessoires"
}
]
}
],
"url": "webshop-domain.nl/products/1000-product-title.html",
"price": {
"model": "fixed",
"price": 1995,
"minimumBid": 0,
"shippingCosts": 0,
"retailPrice": 2500
},
"prices": {
"marktplaats": [
{
"action": "plaatsen",
"priceInternal": 500,
"priceExternal": 1350,
"priceTotal": 1850,
"priceNative": 3203
},
{
"action": "omhoogplaatsen",
"priceInternal": 30,
"priceExternal": 170,
"priceTotal": 200,
"priceNative": 0
},
{
"action": "blikvanger",
"priceInternal": 30,
"priceExternal": 4360,
"priceTotal": 4390,
"priceNative": 0
},
{
"action": "dagtopper",
"priceInternal": 30,
"priceExternal": 200,
"priceTotal": 230,
"priceNative": 0
},
{
"action": "topadvertentie",
"priceInternal": 30,
"priceExternal": 1070,
"priceTotal": 1100,
"priceNative": 0
}
],
"tweedehands": [
{
"action": "plaatsen",
"priceInternal": 30,
"priceExternal": 1499,
"priceTotal": 1529,
"priceNative": 0
}
]
},
"contact": false,
"settings": [
{
"portal": "marktplaats",
"showcontact": true,
"autoreplace": false,
"video": "media.taggle.nl/238934/283928382.mp4"
},
{
"portal": "tweedehands",
"showcontact": false,
"autoreplace": false,
"video": ""
}
],
"images": false,
"misc": {
"licensePlate": ""
}
}
]
}
Example batch delete ads
Request
DELETE /ads/batch/
{
"userId": 12311,
"adId": [
664569,
664570,
664571
]
}
Response
{
"result": true,
"errors": [],
"data": []
}
Example batch patch ads
Request
PATCH /ads/batch/
{
"userId": 12311,
"adId": [
664569,
664570,
664571
],
"status": "draft"
}
Response
{
"result": true,
"errors": [],
"data": []
}